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_get_folders        (TnyFolderStore *self,
                                                         TnyList *list,
                                                         TnyFolderStoreQuery *query,
                                                         GError **err);
void                tny_folder_store_get_folders_async  (TnyFolderStore *self,
                                                         TnyList *list,
                                                         TnyGetFoldersCallback callback,
                                                         TnyFolderStoreQuery *query,
                                                         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;


TnyFolderStoreIface

typedef struct {
   GTypeInterface parent;

   void (*remove_folder_func) (TnyFolderStore *self, TnyFolder *folder, GError **err);
   TnyFolder* (*create_folder_func) (TnyFolderStore *self, const gchar *name, GError **err);
   void (*get_folders_func) (TnyFolderStore *self, TnyList *list, TnyFolderStoreQuery *query, GError **err);
	void (*get_folders_async_func) (TnyFolderStore *self, TnyList *list, TnyGetFoldersCallback callback, TnyFolderStoreQuery *query, TnyStatusCallback status_callback, gpointer user_data);
   void (*add_observer_func) (TnyFolderStore *self, TnyFolderStoreObserver *observer);
   void (*remove_observer_func) (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 represented by 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, but of course not of self, 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 observer 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 (G_OBJECT (remfol));
}

self : a TnyFolderStore object
folder : The folder to remove
err : a GError object or NULL

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 (G_OBJECT (createfol));

self : a TnyFolderStore object
name : The folder name to create
err : a GError object or NULL
Returns : A new folder instance representing the folder that was created or NULL in case of failure

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 (G_OBJECT (folder));
    tny_iterator_next (iter);
}
g_object_unref (G_OBJECT (iter));
g_object_unref (G_OBJECT (folders)); 

self : a TnyFolderStore object
list : A TnyList to fillup
query : A TnyFolderStoreQuery object or NULL
err : a GError object or NULL

tny_folder_store_get_folders_async ()

void                tny_folder_store_get_folders_async  (TnyFolderStore *self,
                                                         TnyList *list,
                                                         TnyGetFoldersCallback callback,
                                                         TnyFolderStoreQuery *query,
                                                         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, 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, callback, NULL, NULL);
        g_object_unref (G_OBJECT (folder));
        tny_iterator_next (iter);
    }
    g_object_unref (G_OBJECT (iter));
    g_object_unref (G_OBJECT (list));
} 
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, callback, NULL, NULL);
}

If you want to use this functionality, you are advised to let your application use a GMainLoop. All Gtk+ applications have this once gtk_main() is called.

When using a GMainLoop, this method will callback using g_idle_add_full. Without a GMainLoop, which the libtinymail-camel implementations detect using (g_main_depth > 0), the callbacks will happen in a worker thread at an unknown moment in time (check your locking).

When using Gtk+ the callback doesn't need gdk_threads_enter and gdk_threads_leave in Gtk+.

self : a TnyFolderStore object
list : A TnyList to fillup
callback : The callback handler
query : A TnyFolderStoreQuery object
status_callback :
user_data : user data for the callback

tny_folder_store_add_observer ()

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

Add observer to the list of interested observers for events that could happen caused by for example folder creates and deletions and other spontaneous changes.

After this, observer will start receiving notification of changes about self.

A weak reference is added to observer. When observer finalizes will self automatically update itself by unregistering observer. It's recommended to use tny_folder_remove_observer yourself to unregister observer as observer for self, though.

self : a TnyFolder instance
observer : a TnyFolderStoreObserver instance

tny_folder_store_remove_observer ()

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

Remove observer from the list of interested observers for events that could happen caused by for example folder creates and deletions and other spontaneous changes.

After this, observer will no longer receive notification of changes about self.

self : a TnyFolderStore instance
observer : a TnyFolderStoreObserver instance

See Also

TnyStoreAccount, TnyFolder, TnyCamelFolder, TnyCamelStoreAccount