From 9eda0faddf0309f33b16b4614cc1a037d9431566 Mon Sep 17 00:00:00 2001 From: Dan Winship Date: Thu, 18 May 2000 02:24:30 +0000 Subject: Remove unused async open/close and copy_message_to functions. Rename * camel-folder.c: Remove unused async open/close and copy_message_to functions. Rename functions without initial _. Fix glib preconditions and gtk-doc comments. svn path=/trunk/; revision=3116 --- camel/ChangeLog | 7 + camel/camel-folder.c | 1147 ++++++++++++++++++++------------------------------ camel/camel-folder.h | 25 +- 3 files changed, 474 insertions(+), 705 deletions(-) diff --git a/camel/ChangeLog b/camel/ChangeLog index 9fbb0f6de7..9c40ae1392 100644 --- a/camel/ChangeLog +++ b/camel/ChangeLog @@ -1,3 +1,10 @@ +2000-05-17 Dan Winship + + * camel-folder.c: Remove unused async open/close and + copy_message_to functions. + Rename functions without initial _. Fix glib preconditions and + gtk-doc comments. + 2000-05-17 Dan Winship * camel-data-wrapper.c: remove get/set_output_stream operations. diff --git a/camel/camel-folder.c b/camel/camel-folder.c index ed78b42f51..e7d5187d3b 100644 --- a/camel/camel-folder.c +++ b/camel/camel-folder.c @@ -1,15 +1,14 @@ /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */ -/* camelFolder.c : Abstract class for an email folder */ +/* camel-folder.c: Abstract class for an email folder */ -/* - * - * Author : +/* + * Author: * Bertrand Guiheneuf * * Copyright 1999, 2000 Helix Code, Inc. (http://www.helixcode.com) * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License as + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License as * published by the Free Software Foundation; either version 2 of the * License, or (at your option) any later version. * @@ -23,11 +22,13 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ + #include #include #include "camel-folder.h" #include "camel-exception.h" #include "camel-store.h" +#include "camel-mime-message.h" #include "string-utils.h" static CamelObjectClass *parent_class = NULL; @@ -44,161 +45,142 @@ enum SIGNALS { static guint signals[LAST_SIGNAL] = { 0 }; -static void _init (CamelFolder *folder, CamelStore *parent_store, - CamelFolder *parent_folder, const gchar *name, - gchar separator, CamelException *ex); -static void _finalize (GtkObject *object); - +static void init (CamelFolder *folder, CamelStore *parent_store, + CamelFolder *parent_folder, const gchar *name, + gchar separator, CamelException *ex); +static void finalize (GtkObject *object); -static void _open (CamelFolder *folder, - CamelFolderOpenMode mode, - CamelException *ex); -static void _close (CamelFolder *folder, - gboolean expunge, - CamelException *ex); -#ifdef FOLDER_ASYNC_TEST - -/* Async operations are not used for the moment */ -static void _open_async (CamelFolder *folder, - CamelFolderOpenMode mode, - CamelFolderAsyncCallback callback, - gpointer user_data, +static void folder_open (CamelFolder *folder, CamelFolderOpenMode mode, CamelException *ex); -static void _close_async (CamelFolder *folder, - gboolean expunge, - CamelFolderAsyncCallback callback, - gpointer user_data, +static void folder_close (CamelFolder *folder, gboolean expunge, CamelException *ex); -#endif - -static const gchar *_get_name (CamelFolder *folder); -static const gchar *_get_full_name (CamelFolder *folder); +static const gchar *get_name (CamelFolder *folder); +static const gchar *get_full_name (CamelFolder *folder); -static gboolean _can_hold_folders (CamelFolder *folder); -static gboolean _can_hold_messages (CamelFolder *folder); -static gboolean _exists (CamelFolder *folder, CamelException *ex); -static gboolean _is_open (CamelFolder *folder); -static guint32 _get_permanent_flags (CamelFolder *folder, - CamelException *ex); -static CamelFolderOpenMode _get_mode (CamelFolder *folder, - CamelException *ex); +static gboolean can_hold_folders (CamelFolder *folder); +static gboolean can_hold_messages (CamelFolder *folder); +static gboolean exists (CamelFolder *folder, CamelException *ex); +static gboolean is_open (CamelFolder *folder); +static guint32 get_permanent_flags (CamelFolder *folder, CamelException *ex); +static CamelFolderOpenMode get_mode (CamelFolder *folder, CamelException *ex); -static gboolean _create (CamelFolder *folder, CamelException *ex); -static gboolean _delete (CamelFolder *folder, gboolean recurse, - CamelException *ex); +static gboolean create (CamelFolder *folder, CamelException *ex); +static gboolean delete (CamelFolder *folder, gboolean recurse, + CamelException *ex); -static GList *_list_subfolders (CamelFolder *folder, CamelException *ex); -static CamelFolder *_get_subfolder (CamelFolder *folder, - const gchar *folder_name, - CamelException *ex); -static CamelFolder *_get_parent_folder (CamelFolder *folder, - CamelException *ex); -static CamelStore * _get_parent_store (CamelFolder *folder, - CamelException *ex); - - -static gboolean _has_message_number_capability (CamelFolder *folder); -static CamelMimeMessage *_get_message_by_number (CamelFolder *folder, - gint number, - CamelException *ex); -static void _delete_message_by_number (CamelFolder *folder, - gint number, +static GList *list_subfolders (CamelFolder *folder, + CamelException *ex); +static CamelFolder *get_subfolder (CamelFolder *folder, + const gchar *folder_name, CamelException *ex); -static gint _get_message_count (CamelFolder *folder, +static CamelFolder *get_parent_folder (CamelFolder *folder, CamelException *ex); +static CamelStore *get_parent_store (CamelFolder *folder, + CamelException *ex); + +static gboolean has_message_number_capability (CamelFolder *folder); +static CamelMimeMessage *get_message_by_number (CamelFolder *folder, + gint number, + CamelException *ex); +static void delete_message_by_number (CamelFolder *folder, + gint number, + CamelException *ex); +static gint get_message_count (CamelFolder *folder, + CamelException *ex); -static gboolean _delete_messages (CamelFolder *folder, - CamelException *ex); -static void _expunge (CamelFolder *folder, - CamelException *ex); -static void _append_message (CamelFolder *folder, - CamelMimeMessage *message, - CamelException *ex); -static void _copy_message_to (CamelFolder *folder, - CamelMimeMessage *message, - CamelFolder *dest_folder, - CamelException *ex); +static gboolean delete_messages (CamelFolder *folder, + CamelException *ex); +static void expunge (CamelFolder *folder, + CamelException *ex); -static GList *_get_uid_list (CamelFolder *folder, + +static void append_message (CamelFolder *folder, CamelMimeMessage *message, + CamelException *ex); + + +static GList *get_uid_list (CamelFolder *folder, CamelException *ex); -static const gchar *_get_message_uid (CamelFolder *folder, - CamelMimeMessage *message, +static const gchar *get_message_uid (CamelFolder *folder, + CamelMimeMessage *message, CamelException *ex); -static CamelMimeMessage *_get_message_by_uid (CamelFolder *folder, - const gchar *uid, +static CamelMimeMessage *get_message_by_uid (CamelFolder *folder, + const gchar *uid, + CamelException *ex); +static void delete_message_by_uid (CamelFolder *folder, + const gchar *uid, CamelException *ex); -static void _delete_message_by_uid (CamelFolder *folder, - const gchar *uid, - CamelException *ex); -static GPtrArray *get_message_info (CamelFolder *folder, int first, int count); -static GPtrArray *get_subfolder_info (CamelFolder *folder, int first, int count); -static const CamelMessageInfo *summary_get_by_uid(CamelFolder *f, const char *uid); +static GPtrArray *get_message_info (CamelFolder *folder, + int first, int count); +static GPtrArray *get_subfolder_info (CamelFolder *folder, + int first, int count); +static const CamelMessageInfo *summary_get_by_uid (CamelFolder *folder, + const char *uid); + +static GList *search_by_expression (CamelFolder *folder, const char *exp, + CamelException *ex); static void camel_folder_class_init (CamelFolderClass *camel_folder_class) { - GtkObjectClass *gtk_object_class = GTK_OBJECT_CLASS (camel_folder_class); - + GtkObjectClass *gtk_object_class = + GTK_OBJECT_CLASS (camel_folder_class); + parent_class = gtk_type_class (camel_object_get_type ()); - - /* virtual method definition */ - camel_folder_class->init = _init; - camel_folder_class->open = _open; -#ifdef FOLDER_ASYNC_TEST - camel_folder_class->open_async = _open_async; -#endif - camel_folder_class->close = _close; -#ifdef FOLDER_ASYNC_TEST - camel_folder_class->close_async = _close_async; -#endif - camel_folder_class->get_name = _get_name; - camel_folder_class->get_full_name = _get_full_name; - camel_folder_class->can_hold_folders = _can_hold_folders; - camel_folder_class->can_hold_messages = _can_hold_messages; - camel_folder_class->exists = _exists; - camel_folder_class->is_open = _is_open; - camel_folder_class->get_subfolder = _get_subfolder; - camel_folder_class->create = _create; - camel_folder_class->delete = _delete; - camel_folder_class->delete_messages = _delete_messages; - camel_folder_class->get_parent_folder = _get_parent_folder; - camel_folder_class->get_parent_store = _get_parent_store; - camel_folder_class->get_mode = _get_mode; - camel_folder_class->list_subfolders = _list_subfolders; - camel_folder_class->expunge = _expunge; - camel_folder_class->has_message_number_capability = _has_message_number_capability; - camel_folder_class->get_message_by_number = _get_message_by_number; - camel_folder_class->delete_message_by_number = _delete_message_by_number; - camel_folder_class->get_message_count = _get_message_count; - camel_folder_class->append_message = _append_message; - camel_folder_class->get_permanent_flags = _get_permanent_flags; - camel_folder_class->copy_message_to = _copy_message_to; - camel_folder_class->get_message_uid = _get_message_uid; - camel_folder_class->get_message_by_uid = _get_message_by_uid; - camel_folder_class->delete_message_by_uid = _delete_message_by_uid; - camel_folder_class->get_uid_list = _get_uid_list; + /* virtual method definition */ + camel_folder_class->init = init; + camel_folder_class->open = folder_open; + camel_folder_class->close = folder_close; + camel_folder_class->get_name = get_name; + camel_folder_class->get_full_name = get_full_name; + camel_folder_class->can_hold_folders = can_hold_folders; + camel_folder_class->can_hold_messages = can_hold_messages; + camel_folder_class->exists = exists; + camel_folder_class->is_open = is_open; + camel_folder_class->get_subfolder = get_subfolder; + camel_folder_class->create = create; + camel_folder_class->delete = delete; + camel_folder_class->delete_messages = delete_messages; + camel_folder_class->get_parent_folder = get_parent_folder; + camel_folder_class->get_parent_store = get_parent_store; + camel_folder_class->get_mode = get_mode; + camel_folder_class->list_subfolders = list_subfolders; + camel_folder_class->expunge = expunge; + camel_folder_class->has_message_number_capability = + has_message_number_capability; + camel_folder_class->get_message_by_number = get_message_by_number; + camel_folder_class->delete_message_by_number = + delete_message_by_number; + camel_folder_class->get_message_count = get_message_count; + camel_folder_class->append_message = append_message; + camel_folder_class->get_permanent_flags = get_permanent_flags; + camel_folder_class->get_message_uid = get_message_uid; + camel_folder_class->get_message_by_uid = get_message_by_uid; + camel_folder_class->delete_message_by_uid = delete_message_by_uid; + camel_folder_class->get_uid_list = get_uid_list; + camel_folder_class->search_by_expression = search_by_expression; camel_folder_class->get_subfolder_info = get_subfolder_info; camel_folder_class->get_message_info = get_message_info; camel_folder_class->summary_get_by_uid = summary_get_by_uid; /* virtual method overload */ - gtk_object_class->finalize = _finalize; + gtk_object_class->finalize = finalize; signals[FOLDER_CHANGED] = gtk_signal_new ("folder_changed", GTK_RUN_LAST, gtk_object_class->type, - GTK_SIGNAL_OFFSET (CamelFolderClass, folder_changed), + GTK_SIGNAL_OFFSET (CamelFolderClass, + folder_changed), gtk_marshal_NONE__INT, GTK_TYPE_NONE, 1, GTK_TYPE_INT); @@ -207,18 +189,13 @@ camel_folder_class_init (CamelFolderClass *camel_folder_class) } - - - - - GtkType camel_folder_get_type (void) { static GtkType camel_folder_type = 0; - + if (!camel_folder_type) { - GtkTypeInfo camel_folder_info = + GtkTypeInfo camel_folder_info = { "CamelFolder", sizeof (CamelFolder), @@ -229,16 +206,17 @@ camel_folder_get_type (void) /* reserved_2 */ NULL, (GtkClassInitFunc) NULL, }; - - camel_folder_type = gtk_type_unique (camel_object_get_type (), &camel_folder_info); + + camel_folder_type = gtk_type_unique (camel_object_get_type (), + &camel_folder_info); } - + return camel_folder_type; } -static void -_finalize (GtkObject *object) +static void +finalize (GtkObject *object) { CamelFolder *camel_folder = CAMEL_FOLDER (object); @@ -255,31 +233,33 @@ _finalize (GtkObject *object) /** - * _init: init the folder + * init: init the folder * @folder: folder object to initialize * @parent_store: parent store object of the folder * @parent_folder: parent folder of the folder (may be NULL) * @name: (short) name of the folder * @separator: separator between the parent folder name and this name - * + * @ex: a CamelException + * * Initalizes the folder by setting the parent store, parent folder, * and name. **/ -static void -_init (CamelFolder *folder, CamelStore *parent_store, - CamelFolder *parent_folder, const gchar *name, - gchar separator, CamelException *ex) +static void +init (CamelFolder *folder, CamelStore *parent_store, + CamelFolder *parent_folder, const gchar *name, + gchar separator, CamelException *ex) { gchar *full_name; const gchar *parent_full_name; - g_assert (folder != NULL); - g_assert (parent_store != NULL); - g_assert (folder->parent_store == NULL); - + g_return_if_fail (CAMEL_IS_FOLDER (folder)); + g_return_if_fail (CAMEL_IS_STORE (parent_store)); + g_return_if_fail (parent_folder == NULL || CAMEL_IS_FOLDER (parent_folder)); + g_return_if_fail (folder->parent_store == NULL); + folder->parent_store = parent_store; gtk_object_ref (GTK_OBJECT (parent_store)); - + folder->parent_folder = parent_folder; if (parent_folder) gtk_object_ref (GTK_OBJECT (parent_folder)); @@ -288,11 +268,11 @@ _init (CamelFolder *folder, CamelStore *parent_store, folder->open_state = FOLDER_CLOSE; folder->separator = separator; - /* if the folder already has a name, free it */ + /* if the folder already has a name, free it */ g_free (folder->name); g_free (folder->full_name); - - /* set those fields to NULL now, so that if an + + /* set those fields to NULL now, so that if an exception occurs, they will be set anyway */ folder->name = NULL; folder->full_name = NULL; @@ -300,7 +280,7 @@ _init (CamelFolder *folder, CamelStore *parent_store, if (folder->parent_folder) { parent_full_name = camel_folder_get_full_name (folder->parent_folder); - + full_name = g_strdup_printf ("%s%c%s", parent_full_name, folder->separator, name); } else { @@ -312,16 +292,11 @@ _init (CamelFolder *folder, CamelStore *parent_store, } - - - static void -_open (CamelFolder *folder, - CamelFolderOpenMode mode, - CamelException *ex) +folder_open (CamelFolder *folder, CamelFolderOpenMode mode, CamelException *ex) { if (folder->open_state == FOLDER_OPEN) { - camel_exception_set (ex, + camel_exception_set (ex, CAMEL_EXCEPTION_FOLDER_INVALID_STATE, "folder is already open"); return; @@ -331,342 +306,211 @@ _open (CamelFolder *folder, folder->open_mode = mode; } - - - /** - * camel_folder_open: Open a folder + * camel_folder_open: * @folder: The folder object * @mode: open mode (R/W/RW ?) * @ex: exception object * * Open a folder in a given mode. - * **/ -void -camel_folder_open (CamelFolder *folder, - CamelFolderOpenMode mode, +void +camel_folder_open (CamelFolder *folder, CamelFolderOpenMode mode, CamelException *ex) -{ - g_assert (folder != NULL); - CF_CLASS (folder)->open (folder, mode, ex); -} - - - - -#ifdef FOLDER_ASYNC_TEST - -static void -_open_async (CamelFolder *folder, - CamelFolderOpenMode mode, - CamelFolderAsyncCallback callback, - gpointer user_data, - CamelException *ex) { - g_warning ("CamelFolder::open_async not implemented for `%s'", - gtk_type_name (GTK_OBJECT_TYPE (folder))); -} - - - + g_return_if_fail (CAMEL_IS_FOLDER (folder)); + g_return_if_fail (!camel_folder_is_open (folder)); -/** - * camel_folder_open: Open a folder - * @folder: The folder object - * @mode: open mode (R/W/RW ?) - * @callback: function to call when the operation is over - * @user_data: data to pass to the callback - * @ex: exception object - * - * Open a folder in a given mode. When the operation is over - * the callback is called and the client program can determine - * if the operation suceeded by examining the exception. - * - **/ -void -camel_folder_open_async (CamelFolder *folder, - CamelFolderOpenMode mode, - CamelFolderAsyncCallback callback, - gpointer user_data, - CamelException *ex) -{ - g_assert (folder != NULL); - CF_CLASS (folder)->open_async (folder, mode, callback, user_data, ex); + CF_CLASS (folder)->open (folder, mode, ex); } -#endif /* FOLDER_ASYNC_TEST */ - - - static void -_close (CamelFolder *folder, - gboolean expunge, - CamelException *ex) -{ +folder_close (CamelFolder *folder, gboolean expunge, CamelException *ex) +{ folder->open_state = FOLDER_CLOSE; } /** - * camel_folder_close: Close a folder. + * camel_folder_close: * @folder: The folder object - * @expunge: if TRUE, the flagged message are deleted. + * @expunge: whether or not to expunge deleted messages * @ex: exception object * - * Put a folder in its closed state, and possibly - * expunge the flagged messages. - * + * Put a folder in its closed state, and possibly expunge the messages + * flagged for deletion. **/ -void -camel_folder_close (CamelFolder *folder, - gboolean expunge, +void +camel_folder_close (CamelFolder *folder, gboolean expunge, CamelException *ex) { - g_assert (folder != NULL); - CF_CLASS (folder)->close (folder, expunge, ex); -} - - - + g_return_if_fail (CAMEL_IS_FOLDER (folder)); + g_return_if_fail (camel_folder_is_open (folder)); -#ifdef FOLDER_ASYNC_TEST - - -static void -_close_async (CamelFolder *folder, - gboolean expunge, - CamelFolderAsyncCallback callback, - gpointer user_data, - CamelException *ex) -{ - g_warning ("CamelFolder::close_async not implemented for `%s'", - gtk_type_name (GTK_OBJECT_TYPE (folder))); -} - -/** - * camel_folder_close_async: Close a folder. - * @folder: The folder object - * @expunge: if TRUE, the flagged message are deleted. - * @callback: function to call when the operation is over - * @user_data: data to pass to the callback - * @ex: exception object - * - * Put a folder in its closed state, and possibly - * expunge the flagged messages. The callback is called - * when the operation is over and the client program can determine - * if the operation suceeded by examining the exception. - * - **/ -void -camel_folder_close_async (CamelFolder *folder, - gboolean expunge, - CamelFolderAsyncCallback callback, - gpointer user_data, - CamelException *ex) -{ - g_assert (folder != NULL); - CF_CLASS (folder)->close_async (folder, expunge, callback, - user_data, ex); + CF_CLASS (folder)->close (folder, expunge, ex); } -#endif - - static const gchar * -_get_name (CamelFolder *folder) +get_name (CamelFolder *folder) { return folder->name; } - /** - * camel_folder_get_name: get the (short) name of the folder - * @folder: - * - * get the name of the folder. The fully qualified name - * can be obtained with the get_full_ame method (not implemented) + * camel_folder_get_name: + * @folder: a folder + * + * Get the (short) name of the folder. The fully qualified name + * can be obtained with the get_full_name method. * * Return value: name of the folder **/ const gchar * camel_folder_get_name (CamelFolder *folder) { - g_assert (folder != NULL); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), NULL); + return CF_CLASS (folder)->get_name (folder); } - static const gchar * -_get_full_name (CamelFolder *folder) +get_full_name (CamelFolder *folder) { return folder->full_name; } /** - * camel_folder_get_full_name:get the (full) name of the folder - * @folder: folder to get the name - * - * get the name of the folder. - * + * camel_folder_get_full_name: + * @folder: a folder + * + * Get the (full) name of the folder. + * * Return value: full name of the folder **/ const gchar * camel_folder_get_full_name (CamelFolder *folder) { - g_assert (folder != NULL); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), NULL); + return CF_CLASS (folder)->get_full_name (folder); } -/** - * _can_hold_folders: tests if the folder can contain other folders - * @folder: The folder object - * - * Tests if a folder can contain other folder - * (as for example MH folders) - * - * Return value: - **/ static gboolean -_can_hold_folders (CamelFolder *folder) +can_hold_folders (CamelFolder *folder) { return folder->can_hold_folders; } - - - -/** - * _can_hold_messages: tests if the folder can contain messages - * @folder: The folder object - * - * Tests if a folder object can contain messages. - * In the case it can not, it most surely can only - * contain folders (rare). - * - * Return value: true if it can contain messages false otherwise - **/ static gboolean -_can_hold_messages (CamelFolder *folder) +can_hold_messages (CamelFolder *folder) { return folder->can_hold_messages; } - static gboolean -_exists (CamelFolder *folder, CamelException *ex) +exists (CamelFolder *folder, CamelException *ex) { return FALSE; } - /** - * _exists: tests if the folder object exists in its parent store. + * camel_folder_exists: * @folder: folder object - * - * Test if a folder exists on a store. A folder can be - * created without physically on a store. In that case, - * use CamelFolder::create to create it - * - * Return value: true if the folder exists on the store false otherwise + * @ex: a CamelException + * + * Test if a folder exists in a store. A CamelFolder can be created + * without physically existing in a store. In that case, use + * CamelFolder::create to create it. + * + * Return value: whether or not the folder exists **/ gboolean camel_folder_exists (CamelFolder *folder, CamelException *ex) { - g_assert (folder != NULL); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), FALSE); + return CF_CLASS (folder)->exists (folder, ex); } - -/** - * _is_open: test if the folder is open - * @folder: The folder object - * - * Tests if a folder is open. If not open it can be opened - * CamelFolder::open - * - * Return value: true if the folder exists, false otherwise - **/ static gboolean -_is_open (CamelFolder *folder) +is_open (CamelFolder *folder) { return folder->open_state == FOLDER_OPEN; -} - +} /** - * _is_open: test if the folder is open - * @folder: The folder object - * - * Tests if a folder is open. If not open it can be opened + * camel_folder_is_open: + * @folder: a folder object + * + * Tests if a folder is open. If not open it can be opened with * CamelFolder::open - * - * Return value: true if the folder exists, false otherwise + * + * Return value: whether or not the folder is open **/ gboolean camel_folder_is_open (CamelFolder *folder) { - g_assert (folder != NULL); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), FALSE); + return CF_CLASS (folder)->is_open (folder); -} +} static CamelFolder * -_get_subfolder (CamelFolder *folder, - const gchar *folder_name, - CamelException *ex) +get_subfolder (CamelFolder *folder, const gchar *folder_name, + CamelException *ex) { CamelFolder *new_folder; gchar *full_name; const gchar *current_folder_full_name; - - g_assert (folder->parent_store != NULL); - + + g_return_val_if_fail (CAMEL_IS_STORE (folder->parent_store), NULL); + current_folder_full_name = camel_folder_get_full_name (folder); full_name = g_strdup_printf ("%s%c%s", current_folder_full_name, folder->separator, folder_name); - - new_folder = camel_store_get_folder (folder->parent_store, full_name, ex); + new_folder = camel_store_get_folder (folder->parent_store, + full_name, ex); + g_free (full_name); + return new_folder; } - - /** - * camel_folder_get_subfolder: return the (sub)folder object that is specified - * @folder: the folder + * camel_folder_get_subfolder: + * @folder: a folder * @folder_name: subfolder path - * - * This method returns a folder objects. This folder - * is necessarily a subfolder of the current folder. - * It is an error to ask a folder begining with the - * folder separator character. - * - * Return value: Required folder. NULL if the subfolder object could not be obtained + * @ex: a CamelException + * + * This method returns a folder object. This folder is a subfolder of + * the given folder. It is an error to ask for a folder whose name begins + * with the folder separator character. + * + * Return value: the requested folder, or %NULL if the subfolder object + * could not be obtained **/ CamelFolder * -camel_folder_get_subfolder (CamelFolder *folder, gchar *folder_name, CamelException *ex) +camel_folder_get_subfolder (CamelFolder *folder, const gchar *folder_name, + CamelException *ex) { - g_assert (folder != NULL); - g_assert (folder_name != NULL); - g_assert (camel_folder_is_open (folder)); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), NULL); + g_return_val_if_fail (camel_folder_is_open (folder), NULL); + g_return_val_if_fail (folder_name != NULL, NULL); return CF_CLASS (folder)->get_subfolder (folder, folder_name, ex); } - - /** - * _create: creates a folder on its store + * create: creates a folder on its store * @folder: a CamelFolder object. - * + * * this routine handles the recursion mechanism. * Children classes have to implement the actual * creation mechanism. They must call this method @@ -674,21 +518,21 @@ camel_folder_get_subfolder (CamelFolder *folder, gchar *folder_name, CamelExcept * to be sure the parent folder exists. * Calling this routine on an existing folder is * not an error, and returns %TRUE. - * - * Return value: %TRUE if the folder exists, %FALSE otherwise + * + * Return value: %TRUE if the folder exists, %FALSE otherwise **/ static gboolean -_create (CamelFolder *folder, CamelException *ex) +create (CamelFolder *folder, CamelException *ex) { CamelFolder *parent; - - g_assert (folder->parent_store != NULL); - g_assert (folder->name != NULL); - + + g_return_val_if_fail (folder->parent_store != NULL, FALSE); + g_return_val_if_fail (folder->name != NULL, FALSE); + /* if the folder already exists on the store, do nothing and return true */ if (CF_CLASS (folder)->exists (folder, ex)) return TRUE; - + if (folder->parent_folder) { camel_folder_create (folder->parent_folder, ex); if (camel_exception_get_id (ex)) @@ -704,7 +548,7 @@ _create (CamelFolder *folder, CamelException *ex) if (camel_exception_get_id (ex)) return FALSE; } - } + } return TRUE; } @@ -712,35 +556,32 @@ _create (CamelFolder *folder, CamelException *ex) /** * camel_folder_create: create the folder object on the physical store * @folder: folder object to create - * - * This routine physically creates the folder object on - * the store. Having created the object does not - * mean the folder physically exists. If it does not - * exists, this routine will create it. - * if the folder full name contains more than one level - * of hierarchy, all folders between the current folder - * and the last folder name will be created if not existing. - * - * Return value: + * @ex: a CamelException + * + * This routine physically creates the folder on the store. Having + * created the object does not mean the folder physically exists. If + * it does not exist, this routine will create it. If the folder full + * name contains more than one level of hierarchy, all folders between + * the current folder and the last folder name will be created if not + * existing. + * + * Return value: whether or not the operation succeeded **/ gboolean camel_folder_create (CamelFolder *folder, CamelException *ex) { - g_assert (folder != NULL); - g_assert (!camel_folder_is_open (folder)); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), FALSE); + g_return_val_if_fail (!camel_folder_is_open (folder), FALSE); return CF_CLASS (folder)->create (folder, ex); } - - - /** - * _delete: delete folder + * delete: delete folder * @folder: folder to delete * @recurse: true is subfolders must also be deleted - * + * * Delete a folder and its subfolders (if recurse is TRUE). * The scheme is the following: * 1) delete all messages in the folder @@ -748,34 +589,34 @@ camel_folder_create (CamelFolder *folder, CamelException *ex) * return FALSE, else delete current folder and retuen TRUE * if recurse is TRUE, delete subfolders, delete * current folder and return TRUE - * - * subclasses implementing a protocol with a different + * + * subclasses implementing a protocol with a different * deletion behaviour must emulate this one or implement - * empty folders deletion and call this routine which + * empty folders deletion and call this routine which * will do all the works for them. * Opertions must be done in the folllowing order: * - call this routine * - delete empty folder - * + * * Return value: true if the folder has been deleted **/ static gboolean -_delete (CamelFolder *folder, gboolean recurse, CamelException *ex) +delete (CamelFolder *folder, gboolean recurse, CamelException *ex) { GList *subfolders=NULL; GList *sf; gboolean ok; - + /* delete all messages in the folder */ CF_CLASS (folder)->delete_messages (folder, ex); if (camel_exception_get_id (ex)) return FALSE; - subfolders = CF_CLASS (folder)->list_subfolders (folder, ex); + subfolders = CF_CLASS (folder)->list_subfolders (folder, ex); if (camel_exception_get_id (ex)) { if (subfolders) g_list_free (subfolders); return FALSE; } - + ok = TRUE; if (recurse) { /* delete subfolders */ if (subfolders) { @@ -790,200 +631,157 @@ _delete (CamelFolder *folder, gboolean recurse, CamelException *ex) "folder has subfolders"); ok = FALSE; } - + if (subfolders) g_list_free (subfolders); return ok; } - - /** * camel_folder_delete: delete a folder * @folder: folder to delete - * @recurse: TRUE if subfolders must be deleted - * - * Delete a folder. All messages in the folder - * are deleted before the folder is deleted. - * When recurse is true, all subfolders are - * deleted too. When recurse is FALSE and folder - * contains subfolders, all messages are deleted, - * but folder deletion fails. - * - * Return value: TRUE if deletion was successful + * @recurse: %TRUE if subfolders must be deleted + * @ex: a CamelException + * + * Delete a folder. All messages in the folder are deleted before the + * folder is deleted. When @recurse is %TRUE, all subfolders are + * deleted too. When @recurse is %FALSE and folder contains + * subfolders, all messages are deleted, but folder deletion fails. + * + * Return value: whether or not deletion was successful **/ -gboolean +gboolean camel_folder_delete (CamelFolder *folder, gboolean recurse, CamelException *ex) { - g_assert (folder != NULL); - g_assert (!camel_folder_is_open (folder)); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), FALSE); + g_return_val_if_fail (!camel_folder_is_open (folder), FALSE); return CF_CLASS (folder)->delete (folder, recurse, ex); } - - - -/** - * _delete_messages: delete all messages in the folder - * @folder: - * - * - * - * Return value: - **/ -static gboolean -_delete_messages (CamelFolder *folder, CamelException *ex) +static gboolean +delete_messages (CamelFolder *folder, CamelException *ex) { g_warning ("CamelFolder::delete_messages not implemented for `%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); return FALSE; } - /** * camel_folder_delete_messages: delete all messages in the folder - * @folder: folder - * - * delete all messages stored in a folder - * - * Return value: TRUE if the messages could be deleted + * @folder: folder + * @ex: a CamelException + * + * Delete all messages stored in a folder. + * + * Return value: whether or not the messages could be deleted **/ gboolean camel_folder_delete_messages (CamelFolder *folder, CamelException *ex) { - g_assert (folder != NULL); - g_assert (!camel_folder_is_open (folder)); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), FALSE); + g_return_val_if_fail (!camel_folder_is_open (folder), FALSE); return CF_CLASS (folder)->delete_messages (folder, ex); } - - - - -/** - * _get_parent_folder: return parent folder - * @folder: folder to get the parent - * - * - * - * Return value: - **/ static CamelFolder * -_get_parent_folder (CamelFolder *folder, CamelException *ex) +get_parent_folder (CamelFolder *folder, CamelException *ex) { return folder->parent_folder; } - /** - * camel_folder_get_parent_folder:return parent folder - * @folder: folder to get the parent - * - * - * - * Return value: + * camel_folder_get_parent_folder: + * @folder: folder to get the parent of + * @ex: a CamelException + * + * Return value: the folder's parent **/ CamelFolder * camel_folder_get_parent_folder (CamelFolder *folder, CamelException *ex) { - g_assert (folder != NULL); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), NULL); + return CF_CLASS (folder)->get_parent_folder (folder, ex); } -/** - * _get_parent_store: return parent store - * @folder: folder to get the parent - * - * - * - * Return value: - **/ static CamelStore * -_get_parent_store (CamelFolder *folder, CamelException *ex) +get_parent_store (CamelFolder *folder, CamelException *ex) { return folder->parent_store; } - /** - * camel_folder_get_parent_store: return parent store - * @folder: folder to get the parent - * - * Return the parent store of a folder - * - * Return value: the parent store. + * camel_folder_get_parent_store: + * @folder: folder to get the parent of + * @ex: a CamelException + * + * Return value: the parent store of the folder. **/ CamelStore * camel_folder_get_parent_store (CamelFolder *folder, CamelException *ex) { - g_assert (folder != NULL); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), NULL); + return CF_CLASS (folder)->get_parent_store (folder, ex); } - - static CamelFolderOpenMode -_get_mode (CamelFolder *folder, CamelException *ex) +get_mode (CamelFolder *folder, CamelException *ex) { return folder->open_mode; } - /** - * camel_folder_get_mode: return the open mode of a folder - * @folder: - * - * - * - * Return value: open mode of the folder + * camel_folder_get_mode: + * @folder: a folder + * @ex: a CamelException + * + * Return value: the open mode of the folder **/ CamelFolderOpenMode camel_folder_get_mode (CamelFolder *folder, CamelException *ex) { - g_assert (folder != NULL); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), -1); + return CF_CLASS (folder)->get_mode (folder, ex); } - - static GList * -_list_subfolders (CamelFolder *folder, CamelException *ex) +list_subfolders (CamelFolder *folder, CamelException *ex) { g_warning ("CamelFolder::list_folders not implemented for `%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); return NULL; } - /** - * camel_folder_list_subfolders: list subfolders in a folder + * camel_folder_list_subfolders: * @folder: the folder - * - * List subfolders in a folder. - * - * Return value: list of subfolders + * @ex: a CamelException + * + * List subfolders in a folder. + * + * Return value: list of subfolder names **/ GList * camel_folder_list_subfolders (CamelFolder *folder, CamelException *ex) { - g_assert (folder != NULL); - g_assert (camel_folder_is_open (folder)); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), NULL); + g_return_val_if_fail (camel_folder_is_open (folder), NULL); return CF_CLASS (folder)->list_subfolders (folder, ex); } - - static void -_expunge (CamelFolder *folder, CamelException *ex) +expunge (CamelFolder *folder, CamelException *ex) { g_warning ("CamelFolder::expunge not implemented for `%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); @@ -991,110 +789,105 @@ _expunge (CamelFolder *folder, CamelException *ex) /** - * camel_folder_expunge: physically delete messages marked as "DELETED" + * camel_folder_expunge: * @folder: the folder - * - * Delete messages which have been marked as "DELETED" - * - * Return value: list of expunged messages + * @ex: a CamelException + * + * Delete messages which have been marked as "DELETED" **/ void camel_folder_expunge (CamelFolder *folder, CamelException *ex) { - g_assert (folder != NULL); - g_assert (camel_folder_is_open (folder)); + g_return_if_fail (CAMEL_IS_FOLDER (folder)); + g_return_if_fail (camel_folder_is_open (folder)); return CF_CLASS (folder)->expunge (folder, ex); } -static gboolean -_has_message_number_capability (CamelFolder *folder) +static gboolean +has_message_number_capability (CamelFolder *folder) { g_warning ("CamelFolder::has_message_number_capability not " "implemented for `%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); return FALSE; - } - /** - * camel_folder_has_message_number_capability: tests if the message can be numbered within the folder + * camel_folder_has_message_number_capability: * @folder: folder to test - * - * Test if the message in this folder can be - * obtained via the get_by_number method. - * Usually, when the folder has the UID - * capability, messages should be referred to - * by their UID rather than by their number - * as the UID is more reliable. - * - * Return value: TRUE if the folder supports message numbering, FALSE otherwise. + * + * Test if the message in this folder can be obtained via the + * get_by_number method. Usually, when the folder has the UID + * capability, messages should be referred to by their UID rather than + * by their number as the UID is more reliable. + * + * Return value: whether or not the folder supports message numbers **/ -gboolean +gboolean camel_folder_has_message_number_capability (CamelFolder *folder) -{ - g_assert (folder != NULL); +{ + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), FALSE); + return CF_CLASS (folder)->has_message_number_capability (folder); } - - static CamelMimeMessage * -_get_message_by_number (CamelFolder *folder, gint number, CamelException *ex) +get_message_by_number (CamelFolder *folder, gint number, CamelException *ex) { g_warning ("CamelFolder::get_message_by_number not implemented " "for `%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); return NULL; } - - - /** - * camel_folder_get_message_by_number: return the message corresponding to that number in the folder + * camel_folder_get_message_by_number: * @folder: a CamelFolder object * @number: the number of the message within the folder. - * + * @ex: a CamelException + * * Return the message corresponding to that number within the folder. - * - * Return value: A pointer on the corresponding message or NULL if no corresponding message exists + * + * Return value: A pointer on the corresponding message, or %NULL if + * no corresponding message exists **/ CamelMimeMessage * -camel_folder_get_message_by_number (CamelFolder *folder, gint number, CamelException *ex) +camel_folder_get_message_by_number (CamelFolder *folder, gint number, + CamelException *ex) { - g_assert (folder != NULL); - g_assert (camel_folder_is_open (folder)); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), NULL); + g_return_val_if_fail (camel_folder_is_open (folder), NULL); + g_return_val_if_fail (camel_folder_has_message_number_capability (folder), NULL); return CF_CLASS (folder)->get_message_by_number (folder, number, ex); } static void -_delete_message_by_number (CamelFolder *folder, gint number, - CamelException *ex) +delete_message_by_number (CamelFolder *folder, gint number, + CamelException *ex) { g_warning ("CamelFolder::delete_message_by_number not implemented " "for `%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); } /** - * camel_folder_delete_message_by_number: delete the message - * corresponding to that number in the folder + * camel_folder_delete_message_by_number: * @folder: a CamelFolder object * @number: the number of the message within the folder. - * + * @ex: a CamelException + * * Delete the message corresponding to that number within the folder. - * **/ void camel_folder_delete_message_by_number (CamelFolder *folder, gint number, CamelException *ex) { - g_assert (folder != NULL); - g_assert (camel_folder_is_open (folder)); + g_return_if_fail (CAMEL_IS_FOLDER (folder)); + g_return_if_fail (camel_folder_is_open (folder)); + g_return_if_fail (camel_folder_has_message_number_capability (folder)); return CF_CLASS (folder)->delete_message_by_number (folder, number, ex); @@ -1102,36 +895,33 @@ camel_folder_delete_message_by_number (CamelFolder *folder, gint number, static gint -_get_message_count (CamelFolder *folder, CamelException *ex) +get_message_count (CamelFolder *folder, CamelException *ex) { g_warning ("CamelFolder::get_message_count not implemented " "for `%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); return -1; } - - /** - * camel_folder_get_message_count: get the number of messages in the folder + * camel_folder_get_message_count: * @folder: A CamelFolder object - * - * Returns the number of messages in the folder. - * - * Return value: the number of messages or -1 if unknown. + * @ex: a CamelException + * + * Return value: the number of messages in the folder, or -1 if unknown. **/ gint camel_folder_get_message_count (CamelFolder *folder, CamelException *ex) { - g_assert (folder != NULL); - g_assert (camel_folder_is_open (folder)); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), -1); + g_return_val_if_fail (camel_folder_is_open (folder), -1); return CF_CLASS (folder)->get_message_count (folder, ex); } static void -_append_message (CamelFolder *folder, CamelMimeMessage *message, - CamelException *ex) +append_message (CamelFolder *folder, CamelMimeMessage *message, + CamelException *ex) { g_warning ("CamelFolder::append_message not implemented for `%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); @@ -1139,74 +929,51 @@ _append_message (CamelFolder *folder, CamelMimeMessage *message, } - /** * camel_folder_append_message: add a message to a folder * @folder: folder object to add the message to * @message: message object * @ex: exception object - * + * * Add a message to a folder. - * **/ -void -camel_folder_append_message (CamelFolder *folder, - CamelMimeMessage *message, +void +camel_folder_append_message (CamelFolder *folder, + CamelMimeMessage *message, CamelException *ex) -{ - g_assert (folder != NULL); - g_assert (camel_folder_is_open (folder)); +{ + g_return_if_fail (CAMEL_IS_FOLDER (folder)); + g_return_if_fail (camel_folder_is_open (folder)); CF_CLASS (folder)->append_message (folder, message, ex); } static guint32 -_get_permanent_flags (CamelFolder *folder, CamelException *ex) +get_permanent_flags (CamelFolder *folder, CamelException *ex) { return folder->permanent_flags; } - guint32 camel_folder_get_permanent_flags (CamelFolder *folder, CamelException *ex) { - g_assert (folder != NULL); - return CF_CLASS (folder)->get_permanent_flags (folder, ex); -} - - - + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), 0); -static void -_copy_message_to (CamelFolder *folder, CamelMimeMessage *message, CamelFolder *dest_folder, CamelException *ex) -{ - camel_folder_append_message (dest_folder, message, ex); + return CF_CLASS (folder)->get_permanent_flags (folder, ex); } -void -camel_folder_copy_message_to (CamelFolder *folder, - CamelMimeMessage *message, - CamelFolder *dest_folder, - CamelException *ex) -{ - g_assert (folder != NULL); - g_assert (camel_folder_is_open (folder)); - - CF_CLASS (folder)->copy_message_to (folder, message, dest_folder, ex);; -} - -/* summary stuff */ static GPtrArray * get_subfolder_info (CamelFolder *folder, int first, int count) { - g_warning ("CamelFolder::get_subfolder_info not implemented for `%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); + g_warning ("CamelFolder::get_subfolder_info not implemented for `%s'", + gtk_type_name (GTK_OBJECT_TYPE (folder))); return NULL; } /** - * camel_folder_summary_get_subfolder_info: return an array of subfolders + * camel_folder_summary_get_subfolder_info: * @summary: a summary * @first: the index of the first subfolder to return information for * (starting from 0) @@ -1230,12 +997,13 @@ camel_folder_summary_get_subfolder_info (CamelFolder *folder, static GPtrArray * get_message_info (CamelFolder *folder, int first, int count) { - g_warning ("CamelFolder::get_message_info not implemented for `%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); + g_warning ("CamelFolder::get_message_info not implemented for `%s'", + gtk_type_name (GTK_OBJECT_TYPE (folder))); return NULL; } /** - * camel_folder_summary_get_message_info: return an array of messages + * camel_folder_summary_get_message_info: * @folder: a camel folder * @first: the index of the first message to return information for * (starting from 0) @@ -1255,35 +1023,38 @@ camel_folder_summary_get_message_info (CamelFolder *folder, return CF_CLASS (folder)->get_message_info (folder, first, count); } + static const CamelMessageInfo * -summary_get_by_uid(CamelFolder *f, const char *uid) +summary_get_by_uid (CamelFolder *folder, const char *uid) { - g_warning("folder::summary_get_by_uid() unimplemented"); + g_warning ("CamelFolder::summary_get_by_uid not implemented for `%s'", + gtk_type_name (GTK_OBJECT_TYPE (folder))); return NULL; } /** * camel_folder_summary_get_by_uid: - * @folder: - * @uid: - * - * Get a single summary entry, by uid. - * - * Return value: + * @folder: a CamelFolder + * @uid: the uid of a message + * + * Return value: the summary information for the indicated message **/ -const CamelMessageInfo *camel_folder_summary_get_by_uid (CamelFolder *folder, const char *uid) +const CamelMessageInfo * +camel_folder_summary_get_by_uid (CamelFolder *folder, const char *uid) { - g_assert (folder != NULL); - g_assert(uid != NULL); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), NULL); + g_return_val_if_fail (uid != NULL, NULL); + return CF_CLASS (folder)->summary_get_by_uid (folder, uid); } -/* summary stuff */ + /* TODO: is this function required anyway? */ gboolean camel_folder_has_summary_capability (CamelFolder *folder) { - g_assert (folder != NULL); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), FALSE); + return folder->has_summary_capability; } @@ -1293,24 +1064,24 @@ camel_folder_has_summary_capability (CamelFolder *folder) /** * camel_folder_has_uid_capability: detect if the folder support UIDs * @folder: Folder object - * - * Detects if a folder supports UID operations, that is - * reference messages by a Unique IDentifier instead - * of by message number. - * - * Return value: TRUE if the folder supports UIDs + * + * Detects if a folder supports UID operations, that is reference + * messages by a Unique IDentifier instead of by message number. + * + * Return value: %TRUE if the folder supports UIDs **/ gboolean camel_folder_has_uid_capability (CamelFolder *folder) { - g_assert (folder != NULL); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), FALSE); + return folder->has_uid_capability; } - static const gchar * -_get_message_uid (CamelFolder *folder, CamelMimeMessage *message, CamelException *ex) +get_message_uid (CamelFolder *folder, CamelMimeMessage *message, + CamelException *ex) { g_warning ("CamelFolder::get_message_uid not implemented for `%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); @@ -1318,89 +1089,93 @@ _get_message_uid (CamelFolder *folder, CamelMimeMessage *message, CamelException } /** - * camel_folder_get_message_uid: get the UID of a message in a folder + * camel_folder_get_message_uid: * @folder: Folder in which the UID must refer to - * @message: Message object - * + * @message: Message object + * @ex: a CamelException + * * Return the UID of a message relatively to a folder. * A message can have different UID, each one corresponding * to a different folder, if the message is referenced in - * several folders. - * + * several folders. + * * Return value: The UID of the message in the folder **/ -const gchar * -camel_folder_get_message_uid (CamelFolder *folder, CamelMimeMessage *message, CamelException *ex) +const gchar * +camel_folder_get_message_uid (CamelFolder *folder, CamelMimeMessage *message, + CamelException *ex) { - g_assert (folder != NULL); - g_assert (folder->has_uid_capability); - g_assert (camel_folder_is_open (folder)); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), NULL); + g_return_val_if_fail (CAMEL_IS_MIME_MESSAGE (message), NULL); + g_return_val_if_fail (folder->has_uid_capability, NULL); + g_return_val_if_fail (camel_folder_is_open (folder), NULL); return CF_CLASS (folder)->get_message_uid (folder, message, ex); } - static CamelMimeMessage * -_get_message_by_uid (CamelFolder *folder, const gchar *uid, CamelException *ex) +get_message_by_uid (CamelFolder *folder, const gchar *uid, CamelException *ex) { g_warning ("CamelFolder::get_message_by_uid not implemented for `%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); return NULL; } - /** - * camel_folder_get_message_by_uid: Get a message by its UID in a folder + * camel_folder_get_message_by_uid: * @folder: the folder object * @uid: the UID - * - * Get a message from its UID in the folder. Messages - * are cached within a folder, that is, asking twice - * for the same UID returns the same message object. - * + * @ex: a CamelException + * + * Get a message from its UID in the folder. Messages are cached + * within a folder, that is, asking twice for the same UID returns the + * same message object. (FIXME: is this true?) + * * Return value: Message corresponding to the UID **/ CamelMimeMessage * -camel_folder_get_message_by_uid (CamelFolder *folder, const gchar *uid, CamelException *ex) +camel_folder_get_message_by_uid (CamelFolder *folder, const gchar *uid, + CamelException *ex) { - g_assert (folder != NULL); - g_assert (folder->has_uid_capability); - g_assert (camel_folder_is_open (folder)); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), NULL); + g_return_val_if_fail (folder->has_uid_capability, NULL); + g_return_val_if_fail (camel_folder_is_open (folder), NULL); return CF_CLASS (folder)->get_message_by_uid (folder, uid, ex); } + static void -_delete_message_by_uid (CamelFolder *folder, const gchar *uid, - CamelException *ex) +delete_message_by_uid (CamelFolder *folder, const gchar *uid, + CamelException *ex) { g_warning ("CamelFolder::delete_message_by_uid not implemented " "for `%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); } - /** - * camel_folder_delete_message_by_uid: Delete a message by its UID in a folder + * camel_folder_delete_message_by_uid: * @folder: the folder object * @uid: the UID - * - * Delete a message from a folder given its UID. + * @ex: a CamelException * + * Delete a message from a folder given its UID. **/ void -camel_folder_delete_message_by_uid (CamelFolder *folder, const gchar *uid, - CamelException *ex) +camel_folder_delete_message_by_uid (CamelFolder *folder, const gchar *uid, + CamelException *ex) { - g_assert (folder != NULL); - g_assert (folder->has_uid_capability); - g_assert (camel_folder_is_open (folder)); + g_return_if_fail (CAMEL_IS_FOLDER (folder)); + g_return_if_fail (folder->has_uid_capability); + g_return_if_fail (camel_folder_is_open (folder)); return CF_CLASS (folder)->delete_message_by_uid (folder, uid, ex); } + static GList * -_get_uid_list (CamelFolder *folder, CamelException *ex) +get_uid_list (CamelFolder *folder, CamelException *ex) { g_warning ("CamelFolder::get_uid_list not implemented for `%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); @@ -1408,23 +1183,24 @@ _get_uid_list (CamelFolder *folder, CamelException *ex) } /** - * camel_folder_get_uid_list: get the list of UID in a folder + * camel_folder_get_uid_list: * @folder: folder object - * - * get the list of UID available in a folder. This - * routine is usefull to know what messages are - * available when the folder does not support - * summaries. The UIDs in the list must not be freed, - * the folder object caches them. - * - * Return value: Glist of UID correspondind to the messages available in the folder. + * @ex: a CamelException + * + * Get the list of UIDs available in a folder. This routine is useful + * for finding what messages are available when the folder does not + * support summaries. The UIDs in the list must not be freed, the + * folder object caches them. + * + * Return value: GList of UIDs corresponding to the messages available + * in the folder. **/ GList * -camel_folder_get_uid_list (CamelFolder *folder, CamelException *ex) +camel_folder_get_uid_list (CamelFolder *folder, CamelException *ex) { - g_assert (folder != NULL); - g_assert (folder->has_uid_capability); - g_assert (camel_folder_is_open (folder)); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), NULL); + g_return_val_if_fail (folder->has_uid_capability, NULL); + g_return_val_if_fail (camel_folder_is_open (folder), NULL); return CF_CLASS (folder)->get_uid_list (folder, ex); } @@ -1432,26 +1208,35 @@ camel_folder_get_uid_list (CamelFolder *folder, CamelException *ex) /** * camel_folder_has_search_capability: * @folder: Folder object - * + * * Checks if a folder supports searching. - * - * Return value: TRUE if the folder supports UIDs + * + * Return value: %TRUE if the folder supports searching **/ gboolean camel_folder_has_search_capability (CamelFolder *folder) { - g_assert (folder != NULL); + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), FALSE); + return folder->has_search_capability; } -GList *camel_folder_search_by_expression (CamelFolder *folder, - const char *expression, - CamelException *ex) +static GList * +search_by_expression (CamelFolder *folder, const char *expression, + CamelException *ex) { - g_assert (folder != NULL); + g_warning ("CamelFolder::search_by_expression not implemented for " + "`%s'", gtk_type_name (GTK_OBJECT_TYPE (folder))); + return NULL; +} + +GList *camel_folder_search_by_expression (CamelFolder *folder, + const char *expression, + CamelException *ex) +{ + g_return_val_if_fail (CAMEL_IS_FOLDER (folder), NULL); g_return_val_if_fail (folder->has_search_capability, NULL); - return CF_CLASS (folder)->search_by_expression (folder, expression, ex); + return CF_CLASS (folder)->search_by_expression (folder, expression, + ex); } - -/* **** */ diff --git a/camel/camel-folder.h b/camel/camel-folder.h index 3dfd70859b..1bd617a1cd 100644 --- a/camel/camel-folder.h +++ b/camel/camel-folder.h @@ -54,8 +54,6 @@ typedef enum { FOLDER_OPEN_RW = 3 /* folder is read/write */ } CamelFolderOpenMode; -typedef void (*CamelFolderAsyncCallback) (); - struct _CamelFolder { CamelObject parent_object; @@ -95,18 +93,6 @@ typedef struct { gboolean expunge, CamelException *ex); - void (*open_async) (CamelFolder *folder, - CamelFolderOpenMode mode, - CamelFolderAsyncCallback callback, - gpointer user_data, - CamelException *ex); - - void (*close_async) (CamelFolder *folder, - gboolean expunge, - CamelFolderAsyncCallback callback, - gpointer user_data, - CamelException *ex); - const gchar * (*get_name) (CamelFolder *folder); const gchar * (*get_full_name) (CamelFolder *folder); @@ -169,11 +155,6 @@ typedef struct { guint32 (*get_permanent_flags) (CamelFolder *folder, CamelException *ex); - void (*copy_message_to) (CamelFolder *folder, - CamelMimeMessage *message, - CamelFolder *dest_folder, - CamelException *ex); - gboolean (*has_uid_capability) (CamelFolder *folder); const gchar * (*get_message_uid) (CamelFolder *folder, @@ -213,7 +194,7 @@ GtkType camel_folder_get_type (void); CamelFolder * camel_folder_get_subfolder (CamelFolder *folder, - gchar *folder_name, + const gchar *folder_name, CamelException *ex); void camel_folder_open (CamelFolder *folder, @@ -266,10 +247,6 @@ gboolean camel_folder_is_open (CamelFolder *folder); void camel_folder_append_message (CamelFolder *folder, CamelMimeMessage *message, CamelException *ex); -void camel_folder_copy_message_to (CamelFolder *folder, - CamelMimeMessage *message, - CamelFolder *dest_folder, - CamelException *ex); /* summary related operations */ -- cgit v1.2.3