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);
CamelFolderInfo*    camel_folder_info_new               (void);
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);
gboolean            camel_store_can_refresh_folder      (CamelStore *store,
                                                         CamelFolderInfo *info,
                                                         CamelException *ex);
                    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 "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 "free_folder_info". Does nothing.

store :

a CamelStore object

fi :

a CamelFolderInfo as gotten via camel_store_get_folder_info

camel_folder_info_new ()

CamelFolderInfo*    camel_folder_info_new               (void);

Returns :

a new empty CamelFolderInfo instance

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

camel_store_can_refresh_folder ()

gboolean            camel_store_can_refresh_folder      (CamelStore *store,
                                                         CamelFolderInfo *info,
                                                         CamelException *ex);

param store Store, to which belong folder. param info Info of folder of our interest. param ex [out] Will set this exception in case of any error. return Whether folder should be checked for new mails or not.

store :

info :

ex :

Returns :


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 :