![]() |
![]() |
![]() |
Reference Manual of the tinymail framework | ![]() |
---|---|---|---|---|
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);
TnyFolderStore is implemented by TnyCamelFolder, TnyCamelNNTPStoreAccount, TnyCamelIMAPStoreAccount, TnyCamelIMAPFolder, TnyCamelStoreAccount, TnyCamelNNTPFolder, TnyCombinedAccount, TnyCamelPOPFolder and TnyCamelPOPStoreAccount.
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;
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 |
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 |
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 |
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 |
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 |
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 |