changed the return value. Now returns the list of expunged messages

1999-12-16  bertrand  <Bertrand.Guiheneuf@aful.org>

	* camel/camel-folder.c (camel_folder_expunge):
	(_expunge):
	* camel/camel-folder-pt-proxy.c (_expunge):
	changed the return value. Now returns the list
	of expunged messages

	* camel/camel-folder.c (_init_with_store):
	cleaned up. Use the exception system now.
	(_open): ditto.
	(camel_folder_open): ditto.
	(camel_folder_open_async): ditto.
	(_close):  ditto.
	(camel_folder_close):  ditto.
	(camel_folder_close_async): ditto.

	* camel/camel-exception.c (camel_exception_set):
	When no exception is given, do nothing, just
	return.
	(camel_exception_set): documented.
	(camel_exception_new): idem.
	(camel_exception_free): idem.
	(camel_exception_xfer): idem.


	* camel/camel-folder.c:
	* camel/camel-folder.h: more clean-ups.
	Removed message list related code.
	This was braindead design.

svn path=/trunk/; revision=1494

7 files changed, 231 insertions, 119 deletions

diff --git a/ChangeLog b/ChangeLog
index 0c82f39d7a..1a70104b0f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,94 @@
+1999-12-16  bertrand  <Bertrand.Guiheneuf@aful.org>
+
+	* camel/camel-folder.c (camel_folder_expunge): 
+	(_expunge): 
+	* camel/camel-folder-pt-proxy.c (_expunge): 
+	changed the return value. Now returns the list 
+	of expunged messages
+
+	* camel/camel-folder.c (_init_with_store): 
+	cleaned up. Use the exception system now.
+	(_open): ditto.
+	(camel_folder_open): ditto.
+	(camel_folder_open_async): ditto.
+	(_close):  ditto.
+	(camel_folder_close):  ditto.
+	(camel_folder_close_async): ditto.
+
+	* camel/camel-exception.c (camel_exception_set): 
+	When no exception is given, do nothing, just
+	return. 
+	(camel_exception_set): documented.
+	(camel_exception_new): idem.
+	(camel_exception_free): idem.
+	(camel_exception_xfer): idem.
+	
+
+	* camel/camel-folder.c:
+	* camel/camel-folder.h: more clean-ups. 
+	Removed message list related code. 
+	This was braindead design. 
+	
+
+	* camel/camel-folder-utils.c (camel_aml_expunge_messages): 
+	implemented. The routines in this file will be
+	called by providers to handle the list of
+	message already standing in memory. 
+
+1999-12-15  bertrand  <Bertrand.Guiheneuf@aful.org>
+
+	* camel/camel-folder-utils.c: 
+	* camel/camel-folder-utils.h: 
+	New files, misc utilities for the 
+	folder providers. Includes active message
+	list utilities. 
+
+	
+	* camel/camel-folder.c (_has_message_number_capability): 
+	(camel_folder_has_message_number_capability): 
+	Added this to know if a folder provides 
+	number-based message access.
+
+	* camel/camel-folder.c (_get_message_count): 
+	added warning when called directly.
+	(_append_message): ditto
+	(_open_async):  ditto
+	(_close_async):  ditto
+	(_delete_messages): ditto 
+	(_expunge):  ditto
+	(_get_message_by_number):  ditto
+	(_get_message_uid):  ditto
+	(_get_message_uid_by_number):  ditto
+	(_get_message_by_uid):  ditto
+	(_get_uid_list):  ditto
+
+	
+	* camel/camel-folder-pt-proxy.c (_open_async): 
+	(_open): 
+	(_close_async): 
+	(_close): 
+	(camel_folder_pt_proxy_class_init): 
+	update 
+	(_get_message_by_number): 
+	Update to reflect changes in CamelFolder
+
+	* camel/camel-folder.h: 
+	* camel/camel-folder.c (_get_subfolder): 
+	(camel_folder_get_subfolder): 
+	The CamelFolder::get_folder is renamed to 
+	get_subfolder as it is more intuitive. 
+
+	* camel/camel-folder.c (_get_message_by_number): 
+	(camel_folder_get_message_by_number): 
+	* camel/camel-folder.h 
+	(camel_folder_get_message_by_number): 
+	The get_message method is now named
+	get_message_by_number for consistency
+	with the _by_uid methods.
+
+	* camel/camel-folder.[ch]: 
+	 clean-ups. 
+
 1999-12-13  Nat Friedman  <nat@helixcode.com>
 
 	* ebook/e-book.h: New file.
diff --git a/camel/camel-exception-list.def b/camel/camel-exception-list.def
index 67c8a13a57..1444c59f2c 100644
--- a/camel/camel-exception-list.def
+++ b/camel/camel-exception-list.def
@@ -1 +1,10 @@
 CAMEL_EXCEPTION_NONE,
+
+/* Generic exceptions */
+CAMEL_EXCEPTION_INVALID_PARAM,
+
+
+/* CamelFolderException */
+CAMEL_EXCEPTION_FOLDER_NULL,
+CAMEL_EXCEPTION_INVALID_FOLDER,
+
diff --git a/camel/camel-exception.c b/camel/camel-exception.c
index e16c152ff2..254b3046e9 100644
--- a/camel/camel-exception.c
+++ b/camel/camel-exception.c
@@ -27,18 +27,16 @@
 #include <config.h>
 #include "camel-exception.h"
 
-void 
-camel_exception_free (CamelException *exception)
-{
-	if (!exception) return;
-
-	if (exception->desc)
-		g_free (exception->desc);
-
-	g_free (exception);
-}
 
 
+/**
+ * camel_exception_new: allocate a new exception object. 
+ * 
+ * Create and returns a new exception object.
+ * 
+ * 
+ * Return value: The newly allocated exception object.
+ **/
 CamelException *
 camel_exception_new ()
 {
@@ -48,18 +46,69 @@ camel_exception_new ()
 	return ex;
 }
 
+/**
+ * camel_exception_free: Free an exception 
+ * @exception: The exception object to free
+ * 
+ * Free an exception object. If the exception
+ * is NULL, nothing is done, the routine simply
+ * returns.
+ **/
+void 
+camel_exception_free (CamelException *exception)
+{
+	if (!exception) return;
+	
+	/* free the description text */
+	if (exception->desc)
+		g_free (exception->desc);
+       	/* free the exeption itself */
+	g_free (exception);
+}
 
+/**
+ * camel_exception_set: set an exception 
+ * @ex: exception object 
+ * @id: exception id 
+ * @desc: textual description of the exception
+ * 
+ * Set the value of an exception. The exception id is 
+ * a unique number representing the exception. The 
+ * textual description is a small text explaining 
+ * what happened and provoked the exception.
+ *
+ * When @ex is NULL, nothing is done, this routine
+ * simply returns.
+ *
+ **/
 void
 camel_exception_set (CamelException *ex,
 		     ExceptionId id,
 		     const char *desc)
 {
+	/* if no exception is given, do nothing */
+	if (!ex) return;
+
 	ex->id = id;
+
+	/* remove the previous exception description */
 	if (ex->desc)
 		g_free (ex->desc);
 	ex->desc = g_strdup (desc);
 }
 
+
+
+/**
+ * camel_exception_xfer: transfer an exception
+ * @ex_dst: Destination exception object 
+ * @ex_src: Source exception object
+ * 
+ * Transfer the content of an exception from
+ * an exception object to another. 
+ * The destination exception receives the id and
+ * the description text of the source exception. 
+ **/
 void 
 camel_exception_xfer (CamelException *ex_dst,
 		      CamelException *ex_src)
diff --git a/camel/camel-folder-pt-proxy.c b/camel/camel-folder-pt-proxy.c
index 83f7af3b93..8119b60755 100644
--- a/camel/camel-folder-pt-proxy.c
+++ b/camel/camel-folder-pt-proxy.c
@@ -90,7 +90,7 @@ static CamelFolder *_get_parent_folder (CamelFolder *folder, CamelException *ex)
 static CamelStore *_get_parent_store (CamelFolder *folder, CamelException *ex);
 static CamelFolderOpenMode _get_mode (CamelFolder *folder, CamelException *ex);
 static GList *_list_subfolders (CamelFolder *folder, CamelException *ex);
-static void _expunge (CamelFolder *folder, CamelException *ex);
+static GList *_expunge (CamelFolder *folder, CamelException *ex);
 static CamelMimeMessage *_get_message_by_number (CamelFolder *folder, gint number, CamelException *ex);
 static gint _get_message_count (CamelFolder *folder, CamelException *ex);
 static gint _append_message (CamelFolder *folder, CamelMimeMessage *message, CamelException *ex);
@@ -684,13 +684,13 @@ _list_subfolders (CamelFolder *folder, CamelException *ex)
 
 
 
-static void
+static GList *
 _expunge (CamelFolder *folder, CamelException *ex)
 {
 	CamelFolderPtProxy *proxy_folder;
 
 	proxy_folder = CAMEL_FOLDER_PT_PROXY (folder);
-	CF_CLASS (proxy_folder->real_folder)->
+	return CF_CLASS (proxy_folder->real_folder)->
 		expunge (proxy_folder->real_folder, ex);
 }
 
diff --git a/camel/camel-folder-utils.c b/camel/camel-folder-utils.c
index e8459134ba..a7f7aa8cc2 100644
--- a/camel/camel-folder-utils.c
+++ b/camel/camel-folder-utils.c
@@ -69,8 +69,8 @@ camel_aml_expunge_messages (GList *aml,
 	guint nb_expunged = 0;  
 	GList *expunged_messages;
 	
-	message_node = folder->message_list;
 
+	message_node = aml;
 	/* look in folder message list which messages
 	 * need to be expunged  */
 	while ( message_node) {
@@ -83,7 +83,7 @@ camel_aml_expunge_messages (GList *aml,
 			if (camel_mime_message_get_flag (message, "DELETED")) {
 				
 				/* remove the message from active message list */
-				g_list_remove_link (folder->message_list, message_node);
+				g_list_remove_link (aml, message_node);
 				g_list_free_1 (message_node);
 				camel_mime_message_set_flag (message, "EXPUNGED", TRUE);
 				expunged_messages = g_list_prepend (expunged_messages, message);
diff --git a/camel/camel-folder.c b/camel/camel-folder.c
index 37796c33a9..3f9399c2ad 100644
--- a/camel/camel-folder.c
+++ b/camel/camel-folder.c
@@ -95,7 +95,7 @@ static gint _get_message_count        (CamelFolder *folder,
 
 static gboolean _delete_messages (CamelFolder *folder, 
 				  CamelException *ex);
-static void _expunge         (CamelFolder *folder, 
+static GList * _expunge         (CamelFolder *folder, 
 			      CamelException *ex);
 static gint _append_message  (CamelFolder *folder, 
 			      CamelMimeMessage *message, 
@@ -202,15 +202,7 @@ _finalize (GtkObject *object)
 	g_free (camel_folder->name);
 	g_free (camel_folder->full_name);
 	g_free (camel_folder->permanent_flags);
-	if (camel_folder->message_list) {
-		/* unref all messages got from the folder */
-		message_node = camel_folder->message_list;
-		while (message_node) {
-			gtk_object_unref (GTK_OBJECT (message_node->data));
-			g_list_next (message_node);
-		}
-		g_list_free (camel_folder->message_list);
-	}
+
 	GTK_OBJECT_CLASS (parent_class)->finalize (object);
 	CAMEL_LOG_FULL_DEBUG ("Leaving CamelFolder::finalize\n");
 }
@@ -226,12 +218,30 @@ _finalize (GtkObject *object)
 static void 
 _init_with_store (CamelFolder *folder, CamelStore *parent_store, CamelException *ex)
 {
-	g_assert(folder);
-	g_assert(parent_store);
+	if (!folder) {
+		camel_exception_set (ex, 
+				     CAMEL_EXCEPTION_FOLDER_NULL,
+				     "folder object is NULL");
+		return;
+	}
+
+	if (!parent_store) {
+		camel_exception_set (ex, 
+				     CAMEL_EXCEPTION_INVALID_PARAM,
+				     "parent_store parameter is NULL");
+		return;
+	}
+	
+	if (!folder->parent_store) {
+		camel_exception_set (ex, 
+				     CAMEL_EXCEPTION_INVALID_FOLDER,
+				     "folder already has a parent store");
+		return;
+	}
 	
-	if (folder->parent_store) gtk_object_unref (GTK_OBJECT (folder->parent_store));
 	folder->parent_store = parent_store;
-	if (parent_store) gtk_object_ref (GTK_OBJECT (parent_store));
+	gtk_object_ref (GTK_OBJECT (parent_store));
+	
 	folder->open_mode = FOLDER_OPEN_UNKNOWN;
 	folder->open_state = FOLDER_CLOSE;
 	folder->name = NULL;
@@ -247,6 +257,13 @@ _open (CamelFolder *folder,
        CamelFolderOpenMode mode, 
        CamelException *ex)
 {
+	if (!folder) {
+		camel_exception_set (ex, 
+				     CAMEL_EXCEPTION_FOLDER_NULL,
+				     "folder object is NULL");
+		return;
+	}
+
   	folder->open_state = FOLDER_OPEN;
   	folder->open_mode = mode;
 }
@@ -268,6 +285,12 @@ camel_folder_open (CamelFolder *folder,
 		   CamelFolderOpenMode mode, 
 		   CamelException *ex)
 {	
+	if (!folder) {
+		camel_exception_set (ex, 
+				     CAMEL_EXCEPTION_FOLDER_NULL,
+				     "folder object is NULL");
+		return;
+	}
 	CF_CLASS(folder)->open (folder, mode, ex);
 }
 
@@ -309,6 +332,12 @@ camel_folder_open_async (CamelFolder *folder,
 			 gpointer user_data, 
 			 CamelException *ex)
 {	
+	if (!folder) {
+		camel_exception_set (ex, 
+				     CAMEL_EXCEPTION_FOLDER_NULL,
+				     "folder object is NULL");
+		return;
+	}
 	CF_CLASS(folder)->open_async (folder, mode, callback, user_data, ex);
 }
 
@@ -322,6 +351,12 @@ _close (CamelFolder *folder,
 	gboolean expunge, 
 	CamelException *ex)
 {	
+	if (!folder) {
+		camel_exception_set (ex, 
+				     CAMEL_EXCEPTION_FOLDER_NULL,
+				     "folder object is NULL");
+		return;
+	}
 	folder->open_state = FOLDER_CLOSE;
 }
 
@@ -340,6 +375,12 @@ camel_folder_close (CamelFolder *folder,
 		    gboolean expunge, 
 		    CamelException *ex)
 {
+	if (!folder) {
+		camel_exception_set (ex, 
+				     CAMEL_EXCEPTION_FOLDER_NULL,
+				     "folder object is NULL");
+		return;
+	}
 	CF_CLASS(folder)->close (folder, expunge, ex);
 }
 
@@ -380,6 +421,12 @@ camel_folder_close_async (CamelFolder *folder,
 			  gpointer user_data, 
 			  CamelException *ex)
 {
+	if (!folder) {
+		camel_exception_set (ex, 
+				     CAMEL_EXCEPTION_FOLDER_NULL,
+				     "folder object is NULL");
+		return;
+	}
 	CF_CLASS(folder)->close_async (folder, expunge, callback, user_data, ex);
 }
 
@@ -943,7 +990,7 @@ camel_folder_list_subfolders (CamelFolder *folder, CamelException *ex)
 
 
 
-static void
+static GList *
 _expunge (CamelFolder *folder, CamelException *ex)
 {
 	CAMEL_LOG_WARNING ("Calling CamelFolder::expunge directly. "
@@ -958,57 +1005,13 @@ _expunge (CamelFolder *folder, CamelException *ex)
  * 
  * Delete messages which have been marked as  "DELETED"
  * 
+ * Return value: list of expunged messages 
  **/
-void
+GList *
 camel_folder_expunge (CamelFolder *folder,  CamelException *ex)
 {
-	CamelMimeMessage *message;
-	GList *message_node;
-	GList *next_message_node;
-	guint nb_expunged = 0;
-
-	
-	/* sort message list by ascending message number
-	if (folder->message_list)
-		folder->message_list = g_list_sort (folder->message_list, camel_mime_message_number_cmp);
-	*/
-	/* call provider method, 
-	 *  PROVIDERS MUST SET THE EXPUNGED FLAGS TO TRUE
-	 * when they expunge a message of the active message list */
 	CF_CLASS (folder)->expunge (folder, ex);
 	
-	message_node = folder->message_list;
-
-	/* look in folder message list which messages
-	 * need to be expunged  */
-	while ( message_node) {
-		message = CAMEL_MIME_MESSAGE (message_node->data);
-
-		/* we may free message_node so get the next node now */
-		next_message_node = message_node->next;
-
-		if (message) {
-			CAMEL_LOG_FULL_DEBUG ("CamelFolder::expunge, examining message %d\n", message->message_number);
-			if (message->expunged) {
-				
-				/* remove the message from active message list */
-				g_list_remove_link (folder->message_list, message_node);
-				g_list_free_1 (message_node);
-				nb_expunged++;
-			} else {
-				/* readjust message number */
-				CAMEL_LOG_FULL_DEBUG ("CamelFolder:: Readjusting message number %d", 
-						      message->message_number);
-				message->message_number -= nb_expunged;
-				CAMEL_LOG_FULL_DEBUG (" to %d\n", message->message_number);
-			}
-		}
-		else {
-			CAMEL_LOG_WARNING ("CamelFolder::expunge warning message_node contains no message\n");
-		}
-		message_node = next_message_node;
-		CAMEL_LOG_FULL_DEBUG ("CamelFolder::expunge, examined message node %p\n", message_node);
-	}
 	
 }
 
@@ -1068,45 +1071,7 @@ _get_message_by_number (CamelFolder *folder, gint number, CamelException *ex)
 CamelMimeMessage *
 camel_folder_get_message_by_number (CamelFolder *folder, gint number, CamelException *ex)
 {
-#warning this code has nothing to do here. 
-	CamelMimeMessage *a_message;
-	CamelMimeMessage *new_message = NULL;
-	GList *message_node;
-	
-	message_node = folder->message_list;
-	CAMEL_LOG_FULL_DEBUG ("CamelFolder::get_message Looking for message number %d\n", number);
-	/* look in folder message list if the 
-	 * if the message has not already been retreived */
-	while ((!new_message) && message_node) {
-		a_message = CAMEL_MIME_MESSAGE (message_node->data);
-		
-		if (a_message) {
-			CAMEL_LOG_FULL_DEBUG ("CamelFolder::get_message "
-					      "found message number %d in the active list\n",
-					      a_message->message_number);
-			if (a_message->message_number == number) {
-				CAMEL_LOG_FULL_DEBUG ("CamelFolder::get_message message "
-						      "%d already retreived once: returning %pOK\n", 
-						      number, a_message);
-				new_message = a_message;
-			} 
-		} else {
-			CAMEL_LOG_WARNING ("CamelFolder::get_message "
-					   " problem in the active list, a message was NULL\n");
-		}
-		message_node = message_node->next;
-		
-		CAMEL_LOG_FULL_DEBUG ("CamelFolder::get_message message node = %p\n", message_node);
-	}
-	if (!new_message) new_message = CF_CLASS (folder)->get_message_by_number (folder, number, ex);
-	if (!new_message) return NULL;
-
-	/* if the message has not been already put in 
-	 * this folder active message list, put it in */
-	if ((!folder->message_list) || (!g_list_find (folder->message_list, new_message)))
-	    folder->message_list = g_list_append (folder->message_list, new_message);
-	
-	return new_message;
+	return CF_CLASS (folder)->get_message_by_number (folder, number, ex);
 }
 
 
diff --git a/camel/camel-folder.h b/camel/camel-folder.h
index 0146ae6325..77eb212888 100644
--- a/camel/camel-folder.h
+++ b/camel/camel-folder.h
@@ -81,8 +81,6 @@ struct _CamelFolder
 
 	gboolean has_uid_capability;
 
-	GList *message_list;
-
 };
 
 
@@ -165,7 +163,7 @@ typedef struct {
 	GList *  (*list_subfolders)   (CamelFolder *folder, 
 				       CamelException *ex);
 
-	void  (*expunge)  (CamelFolder *folder, 
+	GList *  (*expunge)  (CamelFolder *folder, 
 			   CamelException *ex);
 
 	gboolean (*has_message_number_capability) (CamelFolder *folder, CamelException *ex);
@@ -243,7 +241,7 @@ GList *camel_folder_list_subfolders (CamelFolder *folder, CamelException *ex);
 /* delete operations */
 gboolean camel_folder_delete (CamelFolder *folder, gboolean recurse, CamelException *ex);
 gboolean camel_folder_delete_messages (CamelFolder *folder, CamelException *ex);
-void camel_folder_expunge (CamelFolder *folder, CamelException *ex);
+GList *camel_folder_expunge (CamelFolder *folder, CamelException *ex);
 
 
 /* folder name manipulation operations */