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.

svn path=/trunk/; revision=27843

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  <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 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);