Added much in-line documentation. (engine_parse_capability): Use

2004-11-04  Jeffrey Stedfast  <fejj@novell.com>

	* 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.

diff --git a/camel/ChangeLog b/camel/ChangeLog
index fa37534..8478151 100644 (file)
--- a/camel/ChangeLog
+++ b/camel/ChangeLog
@@ -1,3 +1,10 @@
+2004-11-04  Jeffrey Stedfast  <fejj@novell.com>
+
+       * 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  <NotZed@Ximian.com>
 
        * 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 7598b6f..87cf54b 100644 (file)
--- 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 738a17f..6bc76f9 100644 (file)
--- 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);