TnyFolderStore

TnyFolderStore — A type that defines a store for folders

Synopsis

                    TnyFolderStore;
                    TnyFolderStoreIface;
void                tny_folder_store_remove_folder      (TnyFolderStore *self,
                                                         TnyFolder *folder,
                                                         GError **err);
TnyFolder*          tny_folder_store_create_folder      (TnyFolderStore *self,
                                                         const gchar *name,
                                                         GError **err);
void                tny_folder_store_create_folder_async
                                                        (TnyFolderStore *self,
                                                         const gchar *name,
                                                         TnyCreateFolderCallback callback,
                                                         TnyStatusCallback status_callback,
                                                         gpointer user_data);
void                tny_folder_store_get_folders        (TnyFolderStore *self,
                                                         TnyList *list,
                                                         TnyFolderStoreQuery *query,
                                                         GError **err);
void                tny_folder_store_get_folders_async  (TnyFolderStore *self,
                                                         TnyList *list,
                                                         TnyFolderStoreQuery *query,
                                                         TnyGetFoldersCallback callback,
                                                         TnyStatusCallback status_callback,
                                                         gpointer user_data);
void                tny_folder_store_add_observer       (TnyFolderStore *self,
                                                         TnyFolderStoreObserver *observer);
void                tny_folder_store_remove_observer    (TnyFolderStore *self,
                                                         TnyFolderStoreObserver *observer);

Object Hierarchy

  GInterface
   +----TnyFolderStore

Known Derived Interfaces

TnyFolderStore is required by TnyStoreAccount.

Known Implementations

TnyFolderStore is implemented by TnyCamelFolder, TnyCamelNNTPStoreAccount, TnyCamelIMAPStoreAccount, TnyCamelIMAPFolder, TnyCamelStoreAccount, TnyCamelNNTPFolder, TnyCombinedAccount, TnyCamelPOPFolder and TnyCamelPOPStoreAccount.

Description

A abstract type that defines a store for child folders

Details

TnyFolderStore

typedef struct _TnyFolderStore TnyFolderStore;

A store with folders

free-function: g_object_unref


TnyFolderStoreIface

typedef struct {
	GTypeInterface parent;

	void (*remove_folder) (TnyFolderStore *self, TnyFolder *folder, GError **err);
	TnyFolder* (*create_folder) (TnyFolderStore *self, const gchar *name, GError **err);
	void (*create_folder_async) (TnyFolderStore *self, const gchar *name, TnyCreateFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data);
	void (*get_folders) (TnyFolderStore *self, TnyList *list, TnyFolderStoreQuery *query, GError **err);
	void (*get_folders_async) (TnyFolderStore *self, TnyList *list, TnyFolderStoreQuery *query, TnyGetFoldersCallback callback, TnyStatusCallback status_callback, gpointer user_data);
	void (*add_observer) (TnyFolderStore *self, TnyFolderStoreObserver *observer);
	void (*remove_observer) (TnyFolderStore *self, TnyFolderStoreObserver *observer);
} TnyFolderStoreIface;


tny_folder_store_remove_folder ()

void                tny_folder_store_remove_folder      (TnyFolderStore *self,
                                                         TnyFolder *folder,
                                                         GError **err);

Removes a folder from the folder store self. You are responsible for unreferencing the folder instance yourself. This method will not do this for you, leaving the folder instance in an unusable state.

All the TnyFolderObservers and TnyFolderStoreObservers of folder, will automatically be unsubscribed.

This method will always recursively delete all child folders of self. While deleting folders, the folders will also always get unsubscribed (for example in case of IMAP, which means that the folder wont be in LSUB either anymore).

Observers of self and of any the child folders of self will receive delete events in deletion order (childs first, parents after that). Types like the TnyGtkFolderStoreListModel know about this and act on folder deletions by automatically updating themselves.

Example:

static void
my_remove_a_folder (TnyFolderStore *store, TnyFolder *remfol, GError **err)
{
    tny_folder_store_remove_folder (store, remfol, err);
    g_object_unref (remfol);
}

self :

a TnyFolderStore

folder :

a TnyFolder to remove

err :

(null-ok): a GError or NULL

Since 1.0 audience: application-developer


tny_folder_store_create_folder ()

TnyFolder*          tny_folder_store_create_folder      (TnyFolderStore *self,
                                                         const gchar *name,
                                                         GError **err);

Creates a new folder in self. If not NULL, the value returned is the newly created folder instance and must be unreferenced after use.

Example:

TnyFolderStore *store = ...
TnyFolder *createfol;
createfol = tny_folder_store_create_folder (store, "Test", NULL);
if (createfol) 
     g_object_unref (createfol);

self :

a TnyFolderStore

name :

The folder name to create

err :

(null-ok): a GError or NULL

Returns :

(null-ok) (caller-owns): the folder that was created or NULL

Since 1.0 audience: application-developer


tny_folder_store_create_folder_async ()

void                tny_folder_store_create_folder_async
                                                        (TnyFolderStore *self,
                                                         const gchar *name,
                                                         TnyCreateFolderCallback callback,
                                                         TnyStatusCallback status_callback,
                                                         gpointer user_data);

Creates a new folder in self, asynchronously.

self :

a TnyFolderStore

name :

The folder name to create

callback :

(null-ok): a TnyCreateFolderCallback or NULL

status_callback :

(null-ok): a TnyStatusCallback or NULL

user_data :

(null-ok): user data that will be passed to the callbacks

Since 1.0 audience: application-developer


tny_folder_store_get_folders ()

void                tny_folder_store_get_folders        (TnyFolderStore *self,
                                                         TnyList *list,
                                                         TnyFolderStoreQuery *query,
                                                         GError **err);

Get a list of child folders from self. You can use query to limit the list of folders with only folders that match a query or NULL if you don't want to limit the list at all.

Example:

TnyFolderStore *store = ...
TnyIterator *iter; TnyFolderStoreQuery *query = ...
TnyList *folders = tny_simple_list_new ();
tny_folder_store_get_folders (store, folders, query, NULL);
iter = tny_list_create_iterator (folders);
while (!tny_iterator_is_done (iter))
{
    TnyFolder *folder = TNY_FOLDER (tny_iterator_get_current (iter));
    g_print ("%s\n", tny_folder_get_name (folder));
    g_object_unref (folder);
    tny_iterator_next (iter);
}
g_object_unref (iter);
g_object_unref (folders);

self :

a TnyFolderStore

list :

a TnyList to to which the folders will be prepended

query :

(null-ok): a TnyFolderStoreQuery or NULL

err :

(null-ok): a GError or NULL

Since 1.0 audience: application-developer


tny_folder_store_get_folders_async ()

void                tny_folder_store_get_folders_async  (TnyFolderStore *self,
                                                         TnyList *list,
                                                         TnyFolderStoreQuery *query,
                                                         TnyGetFoldersCallback callback,
                                                         TnyStatusCallback status_callback,
                                                         gpointer user_data);

Get a list of child folders from the folder store self and call back when finished. You can use query to limit the list of folders with only folders that match a query or NULL if you don't want to limit the list at all.

Example:

static void 
callback (TnyFolderStore *self, gboolean cancelled, TnyList *list, GError **err, gpointer user_data)
{
    TnyIterator *iter = tny_list_create_iterator (list);
    while (!tny_iterator_is_done (iter))
    {
        TnyFolderStore *folder = tny_iterator_get_current (iter);
        TnyList *folders = tny_simple_list_new ();
        g_print ("%s\n", tny_folder_get_name (TNY_FOLDER (folder)));
        tny_folder_store_get_folders_async (folder,
            folders, NULL, callback, NULL, NULL);
        g_object_unref (folder);
        tny_iterator_next (iter);
    }
    g_object_unref (iter);
} 
static void
get_all_folders (TnyStoreAccount *account)
{
    TnyList *folders;
    folders = tny_simple_list_new ();
    tny_folder_store_get_folders_async (TNY_FOLDER_STORE (account),
        folders, NULL, callback, NULL, NULL);
    g_object_unref (folders);
}

self :

a TnyFolderStore

list :

a TnyList to to which the folders will be prepended

query :

(null-ok): A TnyFolderStoreQuery object

callback :

(null-ok): a TnyGetFoldersCallback or NULL

status_callback :

(null-ok): a TnyStatusCallback or NULL

user_data :

(null-ok): user data that will be passed to the callbacks

Since 1.0 audience: application-developer


tny_folder_store_add_observer ()

void                tny_folder_store_add_observer       (TnyFolderStore *self,
                                                         TnyFolderStoreObserver *observer);

Add observer to the list of event observers. These observers will get notified about folder creations, deletions and subscription changes. A rename will be notified as a deletion followed by a creation. Folder creations, deletions, renames and subscription state changes can happen spontaneous too.

A weak reference is added to observer. When observer finalises will self automatically update itself by unregistering observer. It's recommended to use tny_folder_remove_observer() yourself to unregister observer as observer of self.

self :

a TnyFolder

observer :

a TnyFolderStoreObserver

Since 1.0 audience: application-developer


tny_folder_store_remove_observer ()

void                tny_folder_store_remove_observer    (TnyFolderStore *self,
                                                         TnyFolderStoreObserver *observer);

Remove observer from the list of event observers of self.

The weak reference added by tny_folder_store_add_observer() to observer, is removed.

self :

a TnyFolderStore

observer :

a TnyFolderStoreObserver

Since 1.0 audience: application-developer

See Also

TnyStoreAccount, TnyFolder, TnyCamelFolder, TnyCamelStoreAccount