aboutsummaryrefslogtreecommitdiffstats
path: root/mail
diff options
context:
space:
mode:
authorJonathon Jongsma <jonathon@quotidian.org>2009-12-11 07:06:30 +0800
committerJonathon Jongsma <jonathon@quotidian.org>2009-12-16 04:16:08 +0800
commit9c4f98e915d3f2848b9acc5e089bf3fc56ae2b0f (patch)
tree422f3e24d6cc6a8bf7003657115d6f522f8239da /mail
parent65705e4f55560889ac6de638aa8f3245c06349c0 (diff)
downloadgsoc2013-evolution-9c4f98e915d3f2848b9acc5e089bf3fc56ae2b0f.tar
gsoc2013-evolution-9c4f98e915d3f2848b9acc5e089bf3fc56ae2b0f.tar.gz
gsoc2013-evolution-9c4f98e915d3f2848b9acc5e089bf3fc56ae2b0f.tar.bz2
gsoc2013-evolution-9c4f98e915d3f2848b9acc5e089bf3fc56ae2b0f.tar.lz
gsoc2013-evolution-9c4f98e915d3f2848b9acc5e089bf3fc56ae2b0f.tar.xz
gsoc2013-evolution-9c4f98e915d3f2848b9acc5e089bf3fc56ae2b0f.tar.zst
gsoc2013-evolution-9c4f98e915d3f2848b9acc5e089bf3fc56ae2b0f.zip
Add documentation to clarify mail-folder-cache functionality
Added a bunch of gtk-doc documentation as well as a variety of small comments in the code. Also added documentation and renamed a couple of mail_vfolder_* functions that are only used by mail-folder-cache to make things a lot more understandable. https://bugzilla.gnome.org/show_bug.cgi?id=604627
Diffstat (limited to 'mail')
-rw-r--r--mail/mail-folder-cache.c42
-rw-r--r--mail/mail-folder-cache.h37
-rw-r--r--mail/mail-vfolder.c68
-rw-r--r--mail/mail-vfolder.h4
4 files changed, 119 insertions, 32 deletions
diff --git a/mail/mail-folder-cache.c b/mail/mail-folder-cache.c
index 2bba2485d8..39ef7d2074 100644
--- a/mail/mail-folder-cache.c
+++ b/mail/mail-folder-cache.c
@@ -36,6 +36,7 @@
#include <time.h>
#include <glib.h>
+#include <glib-object.h>
#include <glib/gstdio.h>
#include <glib/gi18n.h>
@@ -47,7 +48,6 @@
#include <camel/camel-disco-store.h>
#include <libedataserver/e-data-server-util.h>
-#include "e-util/e-util.h"
#include "shell/e-shell.h"
#include "mail-mt.h"
@@ -66,7 +66,6 @@
#include "em-utils.h"
#include "e-mail-local.h"
-#include "e-mail-store.h"
#define w(x)
#define d(x)
@@ -80,12 +79,15 @@ G_DEFINE_TYPE (MailFolderCache, mail_folder_cache, G_TYPE_OBJECT)
struct _MailFolderCachePrivate
{
+ /* source id for the ping timeout callback */
guint ping_id;
/* Store to storeinfo table, active stores */
GHashTable *stores;
+ /* mutex to protect access to the stores hash */
GMutex *stores_mutex;
/* List of folder changes to be executed in gui thread */
GQueue updates;
+ /* event id for the async event of flushing all pending updates */
gint update_id;
/* hack for people who LIKE to have unsent count */
gint count_sent;
@@ -173,13 +175,14 @@ real_flush_updates (gpointer o, gpointer event_data, gpointer data)
g_mutex_unlock (self->priv->stores_mutex);
if (up->remove) {
+ /* XXX: what's going on here? */
if (up->delete) {
mail_vfolder_delete_uri(up->store, up->uri);
mail_filter_delete_uri(up->store, up->uri);
mail_config_uri_deleted(CAMEL_STORE_CLASS(CAMEL_OBJECT_GET_CLASS(up->store))->compare_folder_name, up->uri);
} else
- mail_vfolder_add_uri(up->store, up->uri, TRUE);
+ mail_vfolder_notify_uri_unavailable (up->store, up->uri);
} else {
/* We can tell the vfolder code though */
if (up->olduri && up->add) {
@@ -191,7 +194,7 @@ real_flush_updates (gpointer o, gpointer event_data, gpointer data)
}
if (!up->olduri && up->add)
- mail_vfolder_add_uri(up->store, up->uri, FALSE);
+ mail_vfolder_notify_uri_available (up->store, up->uri);
}
/* update unread counts */
@@ -533,6 +536,13 @@ folder_renamed(CamelObject *o, gpointer event_data, gpointer user_data)
/* Dont do anything, do it from the store rename event? */
}
+/**
+ * mail_folder_cache_note_folder:
+ *
+ * When a folder has been opened, notify it for watching. The folder must have
+ * already been created on the store (which has already been noted) before the
+ * folder can be opened
+ */
void mail_folder_cache_note_folder(MailFolderCache *self, CamelFolder *folder)
{
CamelStore *store = folder->parent_store;
@@ -815,6 +825,11 @@ free_folder_info_hash(gchar *path, struct _folder_info *mfi, gpointer data)
free_folder_info(mfi);
}
+/**
+ * mail_folder_cache_note_store_remove:
+ *
+ * Notify the cache that the specified @store can be removed from the cache
+ */
void
mail_folder_cache_note_store_remove(MailFolderCache *self, CamelStore *store)
{
@@ -987,9 +1002,16 @@ store_online_cb (CamelStore *store, gpointer data)
g_mutex_unlock (ud->cache->priv->stores_mutex);
}
+/**
+ * mail_folder_cache_note_store:
+ *
+ * Add a store whose folders should appear in the shell The folders are scanned
+ * from the store, and/or added at runtime via the folder_created event. The
+ * @done function returns if we can free folder info.
+ */
void
mail_folder_cache_note_store(MailFolderCache *self, CamelStore *store, CamelOperation *op,
- NoteDoneFunc done, gpointer data)
+ NoteDoneFunc done, gpointer data)
{
struct _store_info *si;
struct _update_data *ud;
@@ -1078,8 +1100,14 @@ static void storeinfo_find_folder_info(CamelStore *store, struct _store_info *si
}
}
-/* returns TRUE if the uri is available, folderp is set to a
- reffed folder if the folder has also already been opened */
+/**
+ * mail_folder_cache_get_folder_from_uri:
+ *
+ * Gets the #CamelFolder for the supplied @uri.
+ *
+ * Return value: TRUE if the uri is available, folderp is set to a reffed folder if
+ * the folder has also already been opened
+ */
gboolean
mail_folder_cache_get_folder_from_uri(MailFolderCache *self, const gchar *uri, CamelFolder **folderp)
{
diff --git a/mail/mail-folder-cache.h b/mail/mail-folder-cache.h
index 762152ffdd..8a7b82eada 100644
--- a/mail/mail-folder-cache.h
+++ b/mail/mail-folder-cache.h
@@ -23,8 +23,6 @@
*
*/
-/* mail-folder-cache.h: Stores information about open folders */
-
#ifndef _MAIL_FOLDER_CACHE_H
#define _MAIL_FOLDER_CACHE_H
@@ -33,7 +31,10 @@
G_BEGIN_DECLS
-/* Stores information about open folders */
+/**
+ * SECTION: mail-folder-cache
+ * @short_description: Stores information about open folders
+ **/
#define MAIL_TYPE_FOLDER_CACHE mail_folder_cache_get_type()
#define MAIL_FOLDER_CACHE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAIL_TYPE_FOLDER_CACHE, MailFolderCache))
@@ -46,6 +47,12 @@ typedef struct _MailFolderCache MailFolderCache;
typedef struct _MailFolderCacheClass MailFolderCacheClass;
typedef struct _MailFolderCachePrivate MailFolderCachePrivate;
+/**
+ * MailFolderCache:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ */
struct _MailFolderCache
{
GObject parent;
@@ -64,26 +71,16 @@ MailFolderCache *mail_folder_cache_new (void);
MailFolderCache *mail_folder_cache_get_default (void);
+/**
+ * NoteDoneFunc:
+ *
+ * The signature of a function to be registered as a callback for
+ * mail_folder_cache_note_store()
+ */
typedef gboolean (*NoteDoneFunc)(CamelStore *store, CamelFolderInfo *info, gpointer data);
-/* Add a store whose folders should appear in the shell
- The folders are scanned from the store, and/or added at
- runtime via the folder_created event.
- The 'done' function returns if we can free folder info. */
-void mail_folder_cache_note_store (MailFolderCache *self,
- CamelStore *store, CamelOperation *op,
- NoteDoneFunc func, gpointer data);
-
-/* de-note a store */
+void mail_folder_cache_note_store (MailFolderCache *self, CamelStore *store, CamelOperation *op, NoteDoneFunc done, gpointer data);
void mail_folder_cache_note_store_remove (MailFolderCache *self, CamelStore *store);
-
-/* When a folder has been opened, notify it for watching.
- The folder must have already been created on the store (which has already been noted)
- before the folder can be opened
- */
void mail_folder_cache_note_folder (MailFolderCache *self, CamelFolder *folder);
-
-/* Returns true if a folder is available (yet), and also sets *folderp (if supplied)
- to a (referenced) copy of the folder if it has already been opened */
gboolean mail_folder_cache_get_folder_from_uri (MailFolderCache *self, const gchar *uri, CamelFolder **folderp);
gboolean mail_folder_cache_get_folder_info_flags (MailFolderCache *self, CamelFolder *folder, gint *flags);
diff --git a/mail/mail-vfolder.c b/mail/mail-vfolder.c
index f58886b214..9380922d26 100644
--- a/mail/mail-vfolder.c
+++ b/mail/mail-vfolder.c
@@ -425,8 +425,24 @@ uri_is_spethal(CamelStore *store, const gchar *uri)
return res;
}
-/* called when a new uri becomes (un)available */
-void
+/**
+ * mail_vfolder_add_uri:
+ *
+ * @store: a #CamelStore containing the uri
+ * @curi: an email uri to be added/removed
+ * @remove: Whether the uri should be removed or added
+ *
+ * Called when a new uri becomes (un)available. If @store is not a
+ * CamelVeeStore, the uri is added/removed from the list of cached source
+ * folders. Then each vfolder rule is checked to see if the specified uri
+ * matches a source of the rule. It builds a list of vfolders that use (or
+ * would use) the specified uri as a source. It then adds (or removes) this uri
+ * to (from) those vfolders via camel_vee_folder_add/remove_folder() but does
+ * not modify the actual filters or write changes to disk.
+ *
+ * NOTE: This function must be called from the main thread.
+ */
+static void
mail_vfolder_add_uri(CamelStore *store, const gchar *curi, gint remove)
{
EFilterRule *rule;
@@ -525,7 +541,53 @@ done:
g_free(uri);
}
-/* called when a uri is deleted from a store */
+/**
+ * mail_vfolder_uri_available:
+ * @store: a #CamelStore containing the uri
+ * @uri: uri of a folder that became available
+ *
+ * Adds @uri to the list of folders searched if any vfolder source matches the
+ * uri. This function has a transient effect and does not permanently modify
+ * the vfolder filter rules on disk.
+ */
+void
+mail_vfolder_notify_uri_available (CamelStore *store, const gchar *uri)
+{
+ mail_vfolder_add_uri (store, uri, FALSE);
+}
+
+/**
+ * mail_vfolder_uri_available:
+ * @store: a #CamelStore containing the uri
+ * @uri: uri of a folder that became unavailable
+ *
+ * Removes @uri from the list of folders searched if any vfolder source matches the
+ * uri. This function has a transient effect and does not permanently modify
+ * the vfolder filter rules on disk.
+ */
+void
+mail_vfolder_notify_uri_unavailable (CamelStore *store, const gchar *uri)
+{
+ mail_vfolder_add_uri (store, uri, TRUE);
+}
+
+/**
+ * mail_vfolder_delete_uri:
+ *
+ * @store: a #CamelStore containing the uri
+ * @curi: an email uri that has been deleted
+ *
+ * Looks through all vfolder rules to see if @curi is listed as a source for any
+ * vfolder rules. If the uri is found in the source for any rule, it is removed
+ * and the user is alerted to the fact that the vfolder rules have been updated.
+ * The new vfolder rules are written to disk.
+ *
+ * XXX: It doesn't appear that the changes to the vfolder rules are sent down to
+ * the camel level, however. So the actual vfolders will not change behavior
+ * until evolution is restarted (?)
+ *
+ * NOTE: This function must be called from the main thread.
+ */
void
mail_vfolder_delete_uri(CamelStore *store, const gchar *curi)
{
diff --git a/mail/mail-vfolder.h b/mail/mail-vfolder.h
index 725f7ec348..8e44ec44d5 100644
--- a/mail/mail-vfolder.h
+++ b/mail/mail-vfolder.h
@@ -44,8 +44,8 @@ void vfolder_gui_add_from_address (CamelInternetAddress *addr, gint flags, const
GList * mail_vfolder_get_sources_local (void);
GList * mail_vfolder_get_sources_remote (void);
-/* add a uri that is now (un)available to vfolders in a transient manner */
-void mail_vfolder_add_uri(CamelStore *store, const gchar *uri, gint remove);
+void mail_vfolder_notify_uri_available(CamelStore *store, const gchar *uri);
+void mail_vfolder_notify_uri_unavailable(CamelStore *store, const gchar *uri);
/* note that a folder has changed name (uri) */
void mail_vfolder_rename_uri(CamelStore *store, const gchar *from, const gchar *to);