CamelStore

CamelStore —

Synopsis




struct      CamelStore;
            CamelFolderInfo;
#define     CAMEL_FOLDER_NOSELECT
#define     CAMEL_FOLDER_NOINFERIORS
#define     CAMEL_FOLDER_CHILDREN
#define     CAMEL_FOLDER_NOCHILDREN
#define     CAMEL_FOLDER_SUBSCRIBED
#define     CAMEL_FOLDER_VIRTUAL
#define     CAMEL_FOLDER_SYSTEM
#define     CAMEL_FOLDER_VTRASH
#define     CAMEL_FOLDER_SHARED_TO_ME
#define     CAMEL_FOLDER_SHARED_BY_ME
#define     CAMEL_FOLDER_TYPE_MASK
#define     CAMEL_FOLDER_TYPE_BIT
#define     CAMEL_FOLDER_TYPE_NORMAL
#define     CAMEL_FOLDER_TYPE_INBOX
#define     CAMEL_FOLDER_TYPE_OUTBOX
#define     CAMEL_FOLDER_TYPE_TRASH
#define     CAMEL_FOLDER_TYPE_JUNK
#define     CAMEL_FOLDER_TYPE_SENT
#define     CAMEL_STORE_READ
#define     CAMEL_STORE_WRITE
            CamelRenameInfo;
#define     CAMEL_STORE_SUBSCRIPTIONS
#define     CAMEL_STORE_VTRASH
#define     CAMEL_STORE_FILTER_INBOX
#define     CAMEL_STORE_VJUNK
#define     CAMEL_STORE_PROXY
#define     CAMEL_STORE_FOLDER_CREATE
#define     CAMEL_STORE_FOLDER_EXCL
#define     CAMEL_STORE_FOLDER_BODY_INDEX
#define     CAMEL_STORE_FOLDER_PRIVATE
#define     CAMEL_STORE_FOLDER_CREATE_EXCL
#define     CAMEL_STORE_FOLDER_INFO_FAST
#define     CAMEL_STORE_FOLDER_INFO_RECURSIVE
#define     CAMEL_STORE_FOLDER_INFO_SUBSCRIBED
#define     CAMEL_STORE_FOLDER_INFO_NO_VIRTUAL
CamelFolder* camel_store_get_folder         (CamelStore *store,
                                             const char *folder_name,
                                             guint32 flags,
                                             CamelException *ex);
CamelFolder* camel_store_get_inbox          (CamelStore *store,
                                             CamelException *ex);
CamelFolder* camel_store_get_trash          (CamelStore *store,
                                             CamelException *ex);
CamelFolder* camel_store_get_junk           (CamelStore *store,
                                             CamelException *ex);
CamelFolderInfo* camel_store_create_folder  (CamelStore *store,
                                             const char *parent_name,
                                             const char *folder_name,
                                             CamelException *ex);
void        camel_store_delete_folder       (CamelStore *store,
                                             const char *folder_name,
                                             CamelException *ex);
void        camel_store_rename_folder       (CamelStore *store,
                                             const char *old_name,
                                             const char *new_name,
                                             CamelException *ex);
void        camel_store_sync                (CamelStore *store,
                                             int expunge,
                                             CamelException *ex);
CamelFolderInfo* camel_store_get_folder_info
                                            (CamelStore *store,
                                             const char *top,
                                             guint32 flags,
                                             CamelException *ex);
void        camel_store_free_folder_info    (CamelStore *store,
                                             CamelFolderInfo *fi);
void        camel_store_free_folder_info_full
                                            (CamelStore *store,
                                             CamelFolderInfo *fi);
void        camel_store_free_folder_info_nop
                                            (CamelStore *store,
                                             CamelFolderInfo *fi);
void        camel_folder_info_free          (CamelFolderInfo *fi);
CamelFolderInfo* camel_folder_info_build    (GPtrArray *folders,
                                             const char *namespace,
                                             char separator,
                                             gboolean short_names);
CamelFolderInfo* camel_folder_info_clone    (CamelFolderInfo *fi);
gboolean    camel_store_supports_subscriptions
                                            (CamelStore *store);
gboolean    camel_store_folder_subscribed   (CamelStore *store,
                                             const char *folder_name);
void        camel_store_subscribe_folder    (CamelStore *store,
                                             const char *folder_name,
                                             CamelException *ex);
void        camel_store_unsubscribe_folder  (CamelStore *store,
                                             const char *folder_name,
                                             CamelException *ex);
void        camel_store_noop                (CamelStore *store,
                                             CamelException *ex);
int         camel_store_folder_uri_equal    (CamelStore *store,
                                             const char *uri0,
                                             const char *uri1);
            CamelISubscribe;
gboolean    camel_isubscribe_subscribed     (CamelStore *store,
                                             const char *name);
void        camel_isubscribe_subscribe      (CamelStore *store,
                                             const char *folder_name,
                                             CamelException *ex);
void        camel_isubscribe_unsubscribe    (CamelStore *store,
                                             const char *folder_name,
                                             CamelException *ex);


Description

Details

struct CamelStore

struct CamelStore {
	CamelService parent_object;
	struct _CamelStorePrivate *priv;
	
	CamelObjectBag *folders;

	guint32 flags;
	guint32 mode;
};


CamelFolderInfo

typedef struct {
	struct _CamelFolderInfo *next;
	struct _CamelFolderInfo *parent;
	struct _CamelFolderInfo *child;

	char *uri;
	char *name;
	char *full_name;

	guint32 flags;
	gint32 unread;
	gint32 total;
} CamelFolderInfo;


CAMEL_FOLDER_NOSELECT

#define CAMEL_FOLDER_NOSELECT (1<<0)


CAMEL_FOLDER_NOINFERIORS

#define CAMEL_FOLDER_NOINFERIORS (1<<1)


CAMEL_FOLDER_CHILDREN

#define CAMEL_FOLDER_CHILDREN (1<<2)


CAMEL_FOLDER_NOCHILDREN

#define CAMEL_FOLDER_NOCHILDREN (1<<3)


CAMEL_FOLDER_SUBSCRIBED

#define CAMEL_FOLDER_SUBSCRIBED (1<<4)


CAMEL_FOLDER_VIRTUAL

#define CAMEL_FOLDER_VIRTUAL (1<<5)


CAMEL_FOLDER_SYSTEM

#define CAMEL_FOLDER_SYSTEM (1<<6)


CAMEL_FOLDER_VTRASH

#define CAMEL_FOLDER_VTRASH (1<<7)


CAMEL_FOLDER_SHARED_TO_ME

#define CAMEL_FOLDER_SHARED_TO_ME (1<<8)


CAMEL_FOLDER_SHARED_BY_ME

#define CAMEL_FOLDER_SHARED_BY_ME (1<<9)


CAMEL_FOLDER_TYPE_MASK

#define CAMEL_FOLDER_TYPE_MASK (7 << 10)


CAMEL_FOLDER_TYPE_BIT

#define CAMEL_FOLDER_TYPE_BIT (10)


CAMEL_FOLDER_TYPE_NORMAL

#define CAMEL_FOLDER_TYPE_NORMAL (0 << 10)


CAMEL_FOLDER_TYPE_INBOX

#define CAMEL_FOLDER_TYPE_INBOX (1 << 10)


CAMEL_FOLDER_TYPE_OUTBOX

#define CAMEL_FOLDER_TYPE_OUTBOX (2 << 10)


CAMEL_FOLDER_TYPE_TRASH

#define CAMEL_FOLDER_TYPE_TRASH (3 << 10)


CAMEL_FOLDER_TYPE_JUNK

#define CAMEL_FOLDER_TYPE_JUNK (4 << 10)


CAMEL_FOLDER_TYPE_SENT

#define CAMEL_FOLDER_TYPE_SENT (5 << 10)


CAMEL_STORE_READ

#define CAMEL_STORE_READ  (1 << 0)


CAMEL_STORE_WRITE

#define CAMEL_STORE_WRITE (1 << 1)


CamelRenameInfo

typedef struct {
	char *old_base;
	struct _CamelFolderInfo *new;
} CamelRenameInfo;


CAMEL_STORE_SUBSCRIPTIONS

#define CAMEL_STORE_SUBSCRIPTIONS	(1 << 0)


CAMEL_STORE_VTRASH

#define CAMEL_STORE_VTRASH		(1 << 1)


CAMEL_STORE_FILTER_INBOX

#define CAMEL_STORE_FILTER_INBOX	(1 << 2)


CAMEL_STORE_VJUNK

#define CAMEL_STORE_VJUNK		(1 << 3)


CAMEL_STORE_PROXY

#define CAMEL_STORE_PROXY		(1 << 4)


CAMEL_STORE_FOLDER_CREATE

#define CAMEL_STORE_FOLDER_CREATE (1<<0)


CAMEL_STORE_FOLDER_EXCL

#define CAMEL_STORE_FOLDER_EXCL (1<<1)


CAMEL_STORE_FOLDER_BODY_INDEX

#define CAMEL_STORE_FOLDER_BODY_INDEX (1<<2)


CAMEL_STORE_FOLDER_PRIVATE

#define CAMEL_STORE_FOLDER_PRIVATE (1<<3) /* a private folder, that shouldn't show up in unmatched/folder info's, etc */


CAMEL_STORE_FOLDER_CREATE_EXCL

#define CAMEL_STORE_FOLDER_CREATE_EXCL (CAMEL_STORE_FOLDER_CREATE | CAMEL_STORE_FOLDER_EXCL)


CAMEL_STORE_FOLDER_INFO_FAST

#define CAMEL_STORE_FOLDER_INFO_FAST       (1 << 0)


CAMEL_STORE_FOLDER_INFO_RECURSIVE

#define CAMEL_STORE_FOLDER_INFO_RECURSIVE  (1 << 1)


CAMEL_STORE_FOLDER_INFO_SUBSCRIBED

#define CAMEL_STORE_FOLDER_INFO_SUBSCRIBED (1 << 2)


CAMEL_STORE_FOLDER_INFO_NO_VIRTUAL

#define CAMEL_STORE_FOLDER_INFO_NO_VIRTUAL (1 << 3)  /* don't include vTrash/vJunk folders */


camel_store_get_folder ()

CamelFolder* camel_store_get_folder         (CamelStore *store,
                                             const char *folder_name,
                                             guint32 flags,
                                             CamelException *ex);

Get a specific folder object from the store by name.

store : a CamelStore object
folder_name : name of the folder to get
flags : folder flags (create, save body index, etc)
ex : a CamelException
Returns : the folder corresponding to the path folder_name.

camel_store_get_inbox ()

CamelFolder* camel_store_get_inbox          (CamelStore *store,
                                             CamelException *ex);

store : a CamelStore object
ex : a CamelException
Returns : the folder in the store into which new mail is delivered, or NULL if no such folder exists.

camel_store_get_trash ()

CamelFolder* camel_store_get_trash          (CamelStore *store,
                                             CamelException *ex);

store : a CamelStore object
ex : a CamelException
Returns : the folder in the store into which trash is delivered, or NULL if no such folder exists.

camel_store_get_junk ()

CamelFolder* camel_store_get_junk           (CamelStore *store,
                                             CamelException *ex);

store : a CamelStore object
ex : a CamelException
Returns : the folder in the store into which junk is delivered, or NULL if no such folder exists.

camel_store_create_folder ()

CamelFolderInfo* camel_store_create_folder  (CamelStore *store,
                                             const char *parent_name,
                                             const char *folder_name,
                                             CamelException *ex);

Creates a new folder as a child of an existing folder. parent_name can be NULL to create a new top-level folder.

store : a CamelStore object
parent_name : name of the new folder's parent, or NULL
folder_name : name of the folder to create
ex : a CamelException
Returns : info about the created folder, which the caller must free with camel_store_free_folder_info

camel_store_delete_folder ()

void        camel_store_delete_folder       (CamelStore *store,
                                             const char *folder_name,
                                             CamelException *ex);

Deletes the named folder. The folder must be empty.

store : a CamelStore object
folder_name : name of the folder to delete
ex : a CamelException

camel_store_rename_folder ()

void        camel_store_rename_folder       (CamelStore *store,
                                             const char *old_name,
                                             const char *new_name,
                                             CamelException *ex);

Rename a named folder to a new name.

store : a CamelStore object
old_name :
new_name : the new name of the folder
ex : a CamelException

camel_store_sync ()

void        camel_store_sync                (CamelStore *store,
                                             int expunge,
                                             CamelException *ex);

Syncs any changes that have been made to the store object and its folders with the real store.

store : a CamelStore object
expunge : TRUE if an expunge should be done after sync or FALSE otherwise
ex : a CamelException

camel_store_get_folder_info ()

CamelFolderInfo* camel_store_get_folder_info
                                            (CamelStore *store,
                                             const char *top,
                                             guint32 flags,
                                             CamelException *ex);

This fetches information about the folder structure of store, starting with top, and returns a tree of CamelFolderInfo structures. If flags includes CAMEL_STORE_FOLDER_INFO_SUBSCRIBED, only subscribed folders will be listed. If the store doesn't support subscriptions, then it will list all folders. If flags includes CAMEL_STORE_FOLDER_INFO_RECURSIVE, the returned tree will include all levels of hierarchy below top. If not, it will only include the immediate subfolders of top. If flags includes CAMEL_STORE_FOLDER_INFO_FAST, the unread_message_count fields of some or all of the structures may be set to -1, if the store cannot determine that information quickly. If flags includes CAMEL_STORE_FOLDER_INFO_NO_VIRTUAL, don't include special virtual folders (such as vTrash or vJunk).

The CAMEL_STORE_FOLDER_INFO_FAST flag should be considered deprecated; most backends will behave the same whether it is supplied or not. The only guaranteed way to get updated folder counts is to both open the folder and invoke refresh_info() it.

store : a CamelStore object
top : the name of the folder to start from
flags : various CAMEL_STORE_FOLDER_INFO_* flags to control behavior
ex : a CamelException
Returns : a CamelFolderInfo tree, which must be freed with camel_store_free_folder_info

camel_store_free_folder_info ()

void        camel_store_free_folder_info    (CamelStore *store,
                                             CamelFolderInfo *fi);

Frees the data returned by camel_store_get_folder_info

store : a CamelStore object
fi : a CamelFolderInfo as gotten via camel_store_get_folder_info

camel_store_free_folder_info_full ()

void        camel_store_free_folder_info_full
                                            (CamelStore *store,
                                             CamelFolderInfo *fi);

An implementation for CamelStore::free_folder_info. Frees all of the data.

store : a CamelStore object
fi : a CamelFolderInfo as gotten via camel_store_get_folder_info

camel_store_free_folder_info_nop ()

void        camel_store_free_folder_info_nop
                                            (CamelStore *store,
                                             CamelFolderInfo *fi);

An implementation for CamelStore::free_folder_info. Does nothing.

store : a CamelStore object
fi : a CamelFolderInfo as gotten via camel_store_get_folder_info

camel_folder_info_free ()

void        camel_folder_info_free          (CamelFolderInfo *fi);

Frees fi.

fi : a CamelFolderInfo

camel_folder_info_build ()

CamelFolderInfo* camel_folder_info_build    (GPtrArray *folders,
                                             const char *namespace,
                                             char separator,
                                             gboolean short_names);

This takes an array of folders and attaches them together according to the hierarchy described by their full_names and separator. If namespace is non-NULL, then it will be ignored as a full_name prefix, for purposes of comparison. If necessary, camel_folder_info_build will create additional CamelFolderInfo with NULL urls to fill in gaps in the tree. The value of short_names is used in constructing the names of these intermediate folders.

NOTE: This is deprected, do not use this. FIXME: remove this/move it to imap, which is the only user of it now.

folders : an array of CamelFolderInfo
namespace : an ignorable prefix on the folder names
separator : the hieararchy separator character
short_names : TRUE if the (short) name of a folder is the part after the last separator in the full name. FALSE if it is the full name.
Returns : the top level of the tree of linked folder info.

camel_folder_info_clone ()

CamelFolderInfo* camel_folder_info_clone    (CamelFolderInfo *fi);

Clones fi recursively.

fi : a CamelFolderInfo
Returns : the cloned CamelFolderInfo tree.

camel_store_supports_subscriptions ()

gboolean    camel_store_supports_subscriptions
                                            (CamelStore *store);

Get whether or not store supports subscriptions to folders.

store : a CamelStore object
Returns : TRUE if folder subscriptions are supported or FALSE otherwise

camel_store_folder_subscribed ()

gboolean    camel_store_folder_subscribed   (CamelStore *store,
                                             const char *folder_name);

Find out if a folder has been subscribed to.

store : a CamelStore object
folder_name : full path of the folder
Returns : TRUE if the folder has been subscribed to or FALSE otherwise

camel_store_subscribe_folder ()

void        camel_store_subscribe_folder    (CamelStore *store,
                                             const char *folder_name,
                                             CamelException *ex);

Subscribe to the folder described by folder_name.

store : a CamelStore object
folder_name : full path of the folder
ex : a CamelException

camel_store_unsubscribe_folder ()

void        camel_store_unsubscribe_folder  (CamelStore *store,
                                             const char *folder_name,
                                             CamelException *ex);

Unsubscribe from the folder described by folder_name.

store : a CamelStore object
folder_name : full path of the folder
ex : a CamelException

camel_store_noop ()

void        camel_store_noop                (CamelStore *store,
                                             CamelException *ex);

Pings store so that its connection doesn't timeout.

store : a CamelStore object
ex : a CamelException

camel_store_folder_uri_equal ()

int         camel_store_folder_uri_equal    (CamelStore *store,
                                             const char *uri0,
                                             const char *uri1);

Compares 2 folder uris to check that they are equal.

store : a CamelStore object
uri0 : a folder uri
uri1 : another folder uri
Returns : TRUE if they are equal or FALSE otherwise

CamelISubscribe

typedef struct {
	CamelInterface iface;

	gboolean (*subscribed)(CamelStore *store, const char *folder_name);
	void (*subscribe)(CamelStore *store, const char *folder_name, CamelException *ex);
	void (*unsubscribe)(CamelStore *store, const char *folder_name, CamelException *ex);
} CamelISubscribe;


camel_isubscribe_subscribed ()

gboolean    camel_isubscribe_subscribed     (CamelStore *store,
                                             const char *name);

store :
name :
Returns :

camel_isubscribe_subscribe ()

void        camel_isubscribe_subscribe      (CamelStore *store,
                                             const char *folder_name,
                                             CamelException *ex);

store :
folder_name :
ex :

camel_isubscribe_unsubscribe ()

void        camel_isubscribe_unsubscribe    (CamelStore *store,
                                             const char *folder_name,
                                             CamelException *ex);

store :
folder_name :
ex :