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);

Warning

tny_folder_store_create_folder has been deprecated since version 1.0 and should not be used in newly-written code. Use tny_folder_store_create_folder_async in stead

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);

Warning

tny_folder_store_get_folders has been deprecated since version 1.0 and should not be used in newly-written code. Use tny_folder_store_get_folders_async in stead

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);
}

This is a cancelable operation which means that if another cancelable operation executes, this operation will be aborted. Being aborted means that the callback will still be called, but with cancelled=TRUE.

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