From c8f05cb1299423fec36d2503dfa58b8d477fe839 Mon Sep 17 00:00:00 2001 From: Jeffrey Stedfast Date: Thu, 4 Nov 2004 20:52:49 +0000 Subject: Added much in-line documentation. (engine_parse_capability): Use 2004-11-04 Jeffrey Stedfast * providers/imap4/camel-imap4-engine.c: Added much in-line documentation. (engine_parse_capability): Use g_ascii_str[n]casecmp(). (camel_imap4_engine_nstring): New convenience function. svn path=/trunk/; revision=27843 --- camel/ChangeLog | 7 ++ camel/providers/imap4/camel-imap4-engine.c | 158 +++++++++++++++++++++++++++-- camel/providers/imap4/camel-imap4-engine.h | 9 +- 3 files changed, 165 insertions(+), 9 deletions(-) diff --git a/camel/ChangeLog b/camel/ChangeLog index fa375342d8..847815130d 100644 --- a/camel/ChangeLog +++ b/camel/ChangeLog @@ -1,3 +1,10 @@ +2004-11-04 Jeffrey Stedfast + + * providers/imap4/camel-imap4-engine.c: Added much in-line + documentation. + (engine_parse_capability): Use g_ascii_str[n]casecmp(). + (camel_imap4_engine_nstring): New convenience function. + 2004-11-02 Not Zed * camel-object.c (camel_object_hook_event): check interfaces for diff --git a/camel/providers/imap4/camel-imap4-engine.c b/camel/providers/imap4/camel-imap4-engine.c index 7598b6f219..87cf54b35d 100644 --- a/camel/providers/imap4/camel-imap4-engine.c +++ b/camel/providers/imap4/camel-imap4-engine.c @@ -334,6 +334,16 @@ camel_imap4_engine_namespace (CamelIMAP4Engine *engine, CamelException *ex) } +/** + * camel_imap4_engine_select_folder: + * @engine: IMAP4 engine + * @folder: folder to select + * @ex: exception + * + * Convenience function to select @folder. + * + * Returns 0 on success or -1 on fail. + **/ int camel_imap4_engine_select_folder (CamelIMAP4Engine *engine, CamelFolder *folder, CamelException *ex) { @@ -425,11 +435,15 @@ static struct { { "IMAP4", CAMEL_IMAP4_CAPABILITY_IMAP4 }, { "IMAP4REV1", CAMEL_IMAP4_CAPABILITY_IMAP4REV1 }, { "STATUS", CAMEL_IMAP4_CAPABILITY_STATUS }, - { "NAMESPACE", CAMEL_IMAP4_CAPABILITY_NAMESPACE }, - { "UIDPLUS", CAMEL_IMAP4_CAPABILITY_UIDPLUS }, - { "LITERAL+", CAMEL_IMAP4_CAPABILITY_LITERALPLUS }, + { "NAMESPACE", CAMEL_IMAP4_CAPABILITY_NAMESPACE }, /* rfc2342 */ + { "UIDPLUS", CAMEL_IMAP4_CAPABILITY_UIDPLUS }, /* rfc2359 */ + { "LITERAL+", CAMEL_IMAP4_CAPABILITY_LITERALPLUS }, /* rfc2088 */ { "LOGINDISABLED", CAMEL_IMAP4_CAPABILITY_LOGINDISABLED }, { "STARTTLS", CAMEL_IMAP4_CAPABILITY_STARTTLS }, + { "QUOTA", CAMEL_IMAP4_CAPABILITY_QUOTA }, /* rfc2087 */ + { "ACL", CAMEL_IMAP4_CAPABILITY_ACL }, /* rfc2086 */ + { "IDLE", CAMEL_IMAP4_CAPABILITY_IDLE }, /* rfc2177 */ + { "MULTIAPPEND", CAMEL_IMAP4_CAPABILITY_MULTIAPPEND }, /* rfc3502 */ { NULL, 0 } }; @@ -455,14 +469,14 @@ engine_parse_capability (CamelIMAP4Engine *engine, int sentinel, CamelException return -1; while (token.token == CAMEL_IMAP4_TOKEN_ATOM) { - if (!strncasecmp ("AUTH=", token.v.atom, 5)) { + if (!g_ascii_strncasecmp ("AUTH=", token.v.atom, 5)) { CamelServiceAuthType *auth; if ((auth = camel_sasl_authtype (token.v.atom + 5)) != NULL) g_hash_table_insert (engine->authtypes, g_strdup (token.v.atom + 5), auth); } else { for (i = 0; imap4_capabilities[i].name; i++) { - if (!strcasecmp (imap4_capabilities[i].name, token.v.atom)) + if (!g_ascii_strcasecmp (imap4_capabilities[i].name, token.v.atom)) engine->capa |= imap4_capabilities[i].flag; } } @@ -699,6 +713,15 @@ static struct { }; +/** + * camel_imap4_engine_parse_resp_code: + * @engine: IMAP4 engine + * @ex: exception + * + * Parses a RESP-CODE + * + * Returns 0 on success or -1 on fail. + **/ int camel_imap4_engine_parse_resp_code (CamelIMAP4Engine *engine, CamelException *ex) { @@ -945,8 +968,17 @@ camel_imap4_engine_parse_resp_code (CamelIMAP4Engine *engine, CamelException *ex } - -/* returns -1 on error, or one of CAMEL_IMAP4_UNTAGGED_[OK,NO,BAD,PREAUTH,HANDLED] on success */ +/** + * camel_imap4_engine_handle_untagged_1: + * @engine: IMAP4 engine + * @token: IMAP4 token + * @ex: exception + * + * Handles a single untagged response + * + * Returns -1 on error or one of + * CAMEL_IMAP4_UNTAGGED_[OK,NO,BAD,PREAUTH,HANDLED] on success + **/ int camel_imap4_engine_handle_untagged_1 (CamelIMAP4Engine *engine, camel_imap4_token_t *token, CamelException *ex) { @@ -1099,6 +1131,13 @@ camel_imap4_engine_handle_untagged_1 (CamelIMAP4Engine *engine, camel_imap4_toke } +/** + * camel_imap4_engine_handle_untagged: + * @engine: IMAP4 engine + * @ex: exception + * + * Handle a stream of untagged responses. + **/ void camel_imap4_engine_handle_untagged (CamelIMAP4Engine *engine, CamelException *ex) { @@ -1197,6 +1236,7 @@ engine_state_change (CamelIMAP4Engine *engine, CamelIMAP4Command *ic) return retval; } + /** * camel_imap4_engine_iterate: * @engine: IMAP4 engine @@ -1363,6 +1403,13 @@ camel_imap4_engine_prequeue (CamelIMAP4Engine *engine, CamelFolder *folder, cons } +/** + * camel_imap4_engine_dequeue: + * @engine: IMAP4 engine + * @ic: IMAP4 command + * + * Removes @ic from the processing queue. + **/ void camel_imap4_engine_dequeue (CamelIMAP4Engine *engine, CamelIMAP4Command *ic) { @@ -1379,6 +1426,18 @@ camel_imap4_engine_dequeue (CamelIMAP4Engine *engine, CamelIMAP4Command *ic) } +/** + * camel_imap4_engine_next_token: + * @engine: IMAP4 engine + * @token: IMAP4 token + * @ex: exception + * + * Wraps camel_imap4_stream_next_token() to set an exception on + * failure and updates the engine state to DISCONNECTED if the stream + * gets disconencted. + * + * Returns 0 on success or -1 on fail. + **/ int camel_imap4_engine_next_token (CamelIMAP4Engine *engine, camel_imap4_token_t *token, CamelException *ex) { @@ -1396,6 +1455,15 @@ camel_imap4_engine_next_token (CamelIMAP4Engine *engine, camel_imap4_token_t *to } +/** + * camel_imap4_engine_eat_line: + * @engine: IMAP4 engine + * @ex: exception + * + * Gobbles up the remainder of the response line. + * + * Returns 0 on success or -1 on fail + **/ int camel_imap4_engine_eat_line (CamelIMAP4Engine *engine, CamelException *ex) { @@ -1428,6 +1496,19 @@ camel_imap4_engine_eat_line (CamelIMAP4Engine *engine, CamelException *ex) } +/** + * camel_imap4_engine_line: + * @engine: IMAP4 engine + * @line: line pointer + * @len: length pointer + * @ex: exception + * + * Reads in a single line of input from the IMAP4 server and updates + * @line to point to the line buffer. @len is set to the length of the + * line buffer. @line must be free'd using g_free(). + * + * Returns 0 on success or -1 on fail + **/ int camel_imap4_engine_line (CamelIMAP4Engine *engine, unsigned char **line, size_t *len, CamelException *ex) { @@ -1470,6 +1551,20 @@ camel_imap4_engine_line (CamelIMAP4Engine *engine, unsigned char **line, size_t } +/** + * camel_imap4_engine_literal: + * @engine: IMAP4 engine + * @literal: literal pointer + * @len: len pointer + * @ex: exception + * + * Reads in an entire literal string and updates @literal to point to + * it. @len is set to the length of the literal. @literal will also + * conveniently be terminated with a nul-byte. @literal must be free'd + * using g_free(). + * + * Returns 0 on success or -1 on fail. + **/ int camel_imap4_engine_literal (CamelIMAP4Engine *engine, unsigned char **literal, size_t *len, CamelException *ex) { @@ -1513,6 +1608,55 @@ camel_imap4_engine_literal (CamelIMAP4Engine *engine, unsigned char **literal, s } +/** + * camel_imap4_engine_nstring: + * @engine: IMAP4 engine + * @nstring: nstring pointer + * @ex: exception + * + * Reads in an nstring (NIL, atom, qstring or literal) and updates + * @nstring to point to it. @nstring must be free'd using g_free(). + * + * Returns 0 on success or -1 on fail. + **/ +int +camel_imap4_engine_nstring (CamelIMAP4Engine *engine, unsigned char **nstring, CamelException *ex) +{ + camel_imap4_token_t token; + size_t n; + + if (camel_imap4_engine_next_token (engine, &token, ex) == -1) + return -1; + + switch (token.token) { + case CAMEL_IMAP4_TOKEN_NIL: + *nstring = NULL; + break; + case CAMEL_IMAP4_TOKEN_ATOM: + *nstring = g_strdup (token.v.atom); + break; + case CAMEL_IMAP4_TOKEN_QSTRING: + *nstring = g_strdup (token.v.qstring); + break; + case CAMEL_IMAP4_TOKEN_LITERAL: + if (camel_imap4_engine_literal (engine, nstring, &n, ex) == -1) + return -1; + break; + default: + camel_imap4_utils_set_unexpected_token_error (ex, engine, &token); + return -1; + } + + return 0; +} + + +/** + * camel_imap4_resp_code_free: + * @rcode: RESP-CODE + * + * Free's the RESP-CODE + **/ void camel_imap4_resp_code_free (CamelIMAP4RespCode *rcode) { diff --git a/camel/providers/imap4/camel-imap4-engine.h b/camel/providers/imap4/camel-imap4-engine.h index 738a17f7b6..6bc76f9693 100644 --- a/camel/providers/imap4/camel-imap4-engine.h +++ b/camel/providers/imap4/camel-imap4-engine.h @@ -74,8 +74,12 @@ enum { CAMEL_IMAP4_CAPABILITY_LITERALPLUS = (1 << 5), CAMEL_IMAP4_CAPABILITY_LOGINDISABLED = (1 << 6), CAMEL_IMAP4_CAPABILITY_STARTTLS = (1 << 7), - CAMEL_IMAP4_CAPABILITY_useful_lsub = (1 << 8), - CAMEL_IMAP4_CAPABILITY_utf8_search = (1 << 9), + CAMEL_IMAP4_CAPABILITY_IDLE = (1 << 8), + CAMEL_IMAP4_CAPABILITY_QUOTA = (1 << 9), + CAMEL_IMAP4_CAPABILITY_ACL = (1 << 10), + CAMEL_IMAP4_CAPABILITY_MULTIAPPEND = (1 << 11), + CAMEL_IMAP4_CAPABILITY_useful_lsub = (1 << 12), + CAMEL_IMAP4_CAPABILITY_utf8_search = (1 << 13), }; typedef enum { @@ -215,6 +219,7 @@ void camel_imap4_engine_handle_untagged (CamelIMAP4Engine *engine, CamelExceptio int camel_imap4_engine_next_token (CamelIMAP4Engine *engine, struct _camel_imap4_token_t *token, CamelException *ex); int camel_imap4_engine_line (CamelIMAP4Engine *engine, unsigned char **line, size_t *len, CamelException *ex); int camel_imap4_engine_literal (CamelIMAP4Engine *engine, unsigned char **literal, size_t *len, CamelException *ex); +int camel_imap4_engine_nstring (CamelIMAP4Engine *engine, unsigned char **nstring, CamelException *ex); int camel_imap4_engine_eat_line (CamelIMAP4Engine *engine, CamelException *ex); -- cgit v1.2.3