![]() |
![]() |
![]() |
Reference Manual of the tinymail framework | ![]() |
---|---|---|---|---|
TnyFolder; TnyFolderIface; #define TNY_TYPE_FOLDER_SIGNAL #define TNY_TYPE_FOLDER_TYPE #define TNY_TYPE_FOLDER_CAPS GType tny_folder_type_get_type (void); TnyMsgRemoveStrategy* tny_folder_get_msg_remove_strategy (TnyFolder *self); void tny_folder_set_msg_remove_strategy (TnyFolder *self, TnyMsgRemoveStrategy *st); TnyMsgReceiveStrategy* tny_folder_get_msg_receive_strategy (TnyFolder *self); void tny_folder_set_msg_receive_strategy (TnyFolder *self, TnyMsgReceiveStrategy *st); void tny_folder_remove_msg (TnyFolder *self, TnyHeader *header, GError **err); void tny_folder_remove_msgs (TnyFolder *self, TnyList *headers, GError **err); void tny_folder_remove_msg_async (TnyFolder *self, TnyHeader *header, GError **err); void tny_folder_add_msg (TnyFolder *self, TnyMsg *msg, GError **err); void tny_folder_add_msg_async (TnyFolder *self, TnyMsg *msg, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data); void tny_folder_sync (TnyFolder *self, gboolean expunge, GError **err); void tny_folder_sync_async (TnyFolder *self, gboolean expunge, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data); TnyMsg* tny_folder_get_msg (TnyFolder *self, TnyHeader *header, GError **err); TnyMsg* tny_folder_find_msg (TnyFolder *self, const gchar *url_string, GError **err); void tny_folder_get_msg_async (TnyFolder *self, TnyHeader *header, TnyGetMsgCallback callback, TnyStatusCallback status_callback, gpointer user_data); void tny_folder_get_headers (TnyFolder *self, TnyList *headers, gboolean refresh, GError **err); void tny_folder_get_headers_async (TnyFolder *self, TnyList *headers, gboolean refresh, TnyGetHeadersCallback callback, TnyStatusCallback status_callback, gpointer user_data); TnyAccount* tny_folder_get_account (TnyFolder *self); const gchar* tny_folder_get_id (TnyFolder *self); const gchar* tny_folder_get_name (TnyFolder *self); TnyFolderType tny_folder_get_folder_type (TnyFolder *self); guint tny_folder_get_all_count (TnyFolder *self); guint tny_folder_get_unread_count (TnyFolder *self); guint tny_folder_get_local_size (TnyFolder *self); gboolean tny_folder_is_subscribed (TnyFolder *self); void tny_folder_refresh_async (TnyFolder *self, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data); void tny_folder_refresh (TnyFolder *self, GError **err); void tny_folder_transfer_msgs (TnyFolder *self, TnyList *header_list, TnyFolder *folder_dst, gboolean delete_originals, GError **err); void tny_folder_transfer_msgs_async (TnyFolder *self, TnyList *header_list, TnyFolder *folder_dst, gboolean delete_originals, TnyTransferMsgsCallback callback, TnyStatusCallback status_callback, gpointer user_data); TnyFolder* tny_folder_copy (TnyFolder *self, TnyFolderStore *into, const gchar *new_name, gboolean del, GError **err); void tny_folder_copy_async (TnyFolder *self, TnyFolderStore *into, const gchar *new_name, gboolean del, TnyCopyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data); void tny_folder_poke_status (TnyFolder *self); void tny_folder_add_observer (TnyFolder *self, TnyFolderObserver *observer); void tny_folder_remove_observer (TnyFolder *self, TnyFolderObserver *observer); TnyFolderStore* tny_folder_get_folder_store (TnyFolder *self); TnyFolderStats* tny_folder_get_stats (TnyFolder *self); TnyFolderCaps tny_folder_get_caps (TnyFolder *self); gchar* tny_folder_get_url_string (TnyFolder *self);
TnyFolder is implemented by TnyCamelFolder, TnyCamelIMAPFolder, TnyCamelNNTPFolder, TnyCamelPOPFolder and TnyMergeFolder.
typedef struct { GTypeInterface parent; /* Methods */ void (*remove_msg_func) (TnyFolder *self, TnyHeader *header, GError **err); void (*remove_msgs_func) (TnyFolder *self, TnyList *headers, GError **err); void (*add_msg_func) (TnyFolder *self, TnyMsg *msg, GError **err); void (*add_msg_async_func) (TnyFolder *self, TnyMsg *msg, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data); void (*sync_func) (TnyFolder *self, gboolean expunge, GError **err); void (*sync_async_func) (TnyFolder *self, gboolean expunge, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data); TnyMsgRemoveStrategy* (*get_msg_remove_strategy_func) (TnyFolder *self); void (*set_msg_remove_strategy_func) (TnyFolder *self, TnyMsgRemoveStrategy *st); TnyMsgReceiveStrategy* (*get_msg_receive_strategy_func) (TnyFolder *self); void (*set_msg_receive_strategy_func) (TnyFolder *self, TnyMsgReceiveStrategy *st); TnyMsg* (*get_msg_func) (TnyFolder *self, TnyHeader *header, GError **err); TnyMsg* (*find_msg_func) (TnyFolder *self, const gchar *url_string, GError **err); void (*get_msg_async_func) (TnyFolder *self, TnyHeader *header, TnyGetMsgCallback callback, TnyStatusCallback status_callback, gpointer user_data); void (*get_headers_func) (TnyFolder *self, TnyList *headers, gboolean refresh, GError **err); void (*get_headers_async_func) (TnyFolder *self, TnyList *headers, gboolean refresh, TnyGetHeadersCallback callback, TnyStatusCallback status_callback, gpointer user_data); const gchar* (*get_name_func) (TnyFolder *self); const gchar* (*get_id_func) (TnyFolder *self); TnyAccount* (*get_account_func) (TnyFolder *self); TnyFolderType (*get_folder_type_func) (TnyFolder *self); guint (*get_all_count_func) (TnyFolder *self); guint (*get_unread_count_func) (TnyFolder *self); guint (*get_local_size_func) (TnyFolder *self); gboolean (*is_subscribed_func) (TnyFolder *self); void (*refresh_async_func) (TnyFolder *self, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data); void (*refresh_func) (TnyFolder *self, GError **err); void (*transfer_msgs_func) (TnyFolder *self, TnyList *header_list, TnyFolder *folder_dst, gboolean delete_originals, GError **err); void (*transfer_msgs_async_func) (TnyFolder *self, TnyList *header_list, TnyFolder *folder_dst, gboolean delete_originals, TnyTransferMsgsCallback callback, TnyStatusCallback status_callback, gpointer user_data); TnyFolder* (*copy_func) (TnyFolder *self, TnyFolderStore *into, const gchar *new_name, gboolean del, GError **err); void (*copy_async_func) (TnyFolder *self, TnyFolderStore *into, const gchar *new_name, gboolean del, TnyCopyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data); void (*poke_status_func) (TnyFolder *self); void (*add_observer_func) (TnyFolder *self, TnyFolderObserver *observer); void (*remove_observer_func) (TnyFolder *self, TnyFolderObserver *observer); TnyFolderStore* (*get_folder_store_func) (TnyFolder *self); TnyFolderStats* (*get_stats_func) (TnyFolder *self); gchar* (*get_url_string_func) (TnyFolder *self); TnyFolderCaps (*get_caps_func) (TnyFolder *self); } TnyFolderIface;
GType tny_folder_type_get_type (void);
GType system helper function
Returns : | a GType |
TnyMsgRemoveStrategy* tny_folder_get_msg_remove_strategy (TnyFolder *self);
Get the strategy for removing a message. The return value of this method must be unreferenced after use.
Implementors: This method must return the strategy for removing a message. being the implementer, you must add a reference before returning the instance.
self : |
a TnyFolder object |
Returns : | the strategy for removing a message |
void tny_folder_set_msg_remove_strategy (TnyFolder *self, TnyMsgRemoveStrategy *st);
Set the strategy for removing a message
Implementors: This method must set (store) the strategy for removing a message.
The idea is that devices can have a specific such strategy. For example a strategy that removes it immediately from both local cache and a service or a strategy that does nothing but flag the message for removal upon next expunge or a strategy that does nothing.
For more information take a look at tny_msg_remove_strategy_peform_remove of TnyMsgRemoveStrategy.
self : |
a TnyFolder object |
st : |
a TnyMsgRemoveStrategy object |
TnyMsgReceiveStrategy* tny_folder_get_msg_receive_strategy (TnyFolder *self);
Get the strategy for receiving a message. The return value of this method must be unreferenced after use.
self : |
a TnyFolder object |
Returns : | the strategy for receiving a message |
void tny_folder_set_msg_receive_strategy (TnyFolder *self, TnyMsgReceiveStrategy *st);
Set the strategy for receiving a message
The idea is that devices can have a specific such strategy. For example a strategy that receives the message fully from the service or a strategy that receives it partially from the service (only the body)
For more information take a look at tny_msg_receive_strategy_peform_get_msg of TnyMsgReceiveStrategy.
self : |
a TnyFolder object |
st : |
a TnyMsgReceiveStrategy object |
void tny_folder_remove_msg (TnyFolder *self, TnyHeader *header, GError **err);
Remove a message from a folder. It will use a TnyMsgRemoveStrategy to perform the removal itself. For more details, check out the documentation of the TnyMsgRemoveStrategy type and the implementation that you activated using tny_folder_set_msg_remove_strategy. The default implementation for libtinymail-camel is the TnyCamelMsgRemoveStrategy.
Folder observers of self
will get a header-removed trigger caused by this
action.
Example:
static void on_header_view_key_press_event (GtkTreeView *header_view, GdkEventKey *event, gpointer user_data) { if (event->keyval == GDK_Delete) { GtkTreeSelection *selection; GtkTreeModel *model; GtkTreeIter iter; selection = gtk_tree_view_get_selection (header_view); if (gtk_tree_selection_get_selected (selection, &model, &iter)) { TnyHeader *header; gtk_tree_model_get (model, &iter, TNY_GTK_HEADER_LIST_MODEL_INSTANCE_COLUMN, &header, -1); TnyFolder *folder = tny_header_get_folder (header); tny_folder_remove_msg (folder, header, NULL); tny_list_remove (TNY_LIST (model), G_OBJECT (header)); g_object_unref (G_OBJECT (folder)); g_object_unref (G_OBJECT (header)); } } }
self : |
a TnyFolder object |
header : |
the header of the message to remove |
err : |
a GError object or NULL |
void tny_folder_remove_msgs (TnyFolder *self, TnyList *headers, GError **err);
Remove messages from a folder. It will use a TnyMsgRemoveStrategy to perform the removal itself. For more details, check out the documentation of the TnyMsgRemoveStrategy type and the implementation that you activated using tny_folder_set_msg_remove_strategy. The default implementation for libtinymail-camel is the TnyCamelMsgRemoveStrategy.
Folder observers of self
will get only one header-removed trigger caused by this
action.
self : |
a TnyFolder object |
headers : |
the headers of the messages to remove |
err : |
a GError object or NULL |
void tny_folder_remove_msg_async (TnyFolder *self, TnyHeader *header, GError **err);
self : |
|
header : |
|
err : |
void tny_folder_add_msg (TnyFolder *self, TnyMsg *msg, GError **err);
Add a message to a folder. It's recommended to destroy msg
afterwards because
after receiving the same message from the folder again, the instance wont be
the same anymore and a property like the tny_msg_get_id might have changed
and assigned too.
Folder observers of self
will get a header-added trigger caused by this
action.
void tny_folder_add_msg_async (TnyFolder *self, TnyMsg *msg, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data);
Add a message to a folder. It's recommended to destroy msg
afterwards because
after receiving the same message from the folder again, the instance wont be
the same anymore and a property like the tny_msg_get_id might have changed
and assigned too.
Folder observers of self
will get a header-added trigger caused by this
action.
void tny_folder_sync (TnyFolder *self, gboolean expunge, GError **err);
Persist changes made to a folder to its backing store, expunging deleted
messages (the ones marked with TNY_HEADER_FLAG_DELETED) as well if expunge
is TRUE.
Example:
TnyHeader *header = ... TnyFolder *folder = tny_header_get_folder (header); tny_folder_remove_msg (folder, header, NULL); tny_list_remove (TNY_LIST (mymodel), G_OBJECT (header)); g_object_unref (G_OBJECT (header)); tny_folder_sync (folder, TRUE, NULL); g_object_unref (G_OBJECT (folder));
self : |
a TnyFolder object |
expunge : |
whether or not to also expunge deleted messages |
err : |
a GError object or NULL |
void tny_folder_sync_async (TnyFolder *self, gboolean expunge, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data);
The authors of Tinymail know that sync async sounds paradoxical. Though if you think about it, it makes perfect sense: you synchronize the content in an asynchronous way. Nothing paradoxial about it, right?
Persist changes made to a folder to its backing store, expunging deleted
messages (the ones marked with TNY_HEADER_FLAG_DELETED) as well if expunge
is TRUE.
self : |
a TnyFolder object |
expunge : |
whether or not to also expunge deleted messages |
callback : |
a TnySyncFolderCallback |
status_callback : |
a TnyStatusCallback |
user_data : |
user data that will be passed to the callbacks |
TnyMsg* tny_folder_get_msg (TnyFolder *self, TnyHeader *header, GError **err);
Get a message in self
identified by header
. If not NULL, you must
unreference the return value after use.
Example:
TnyMsgView *message_view = tny_platform_factory_new_msg_view (platfact); TnyFolder *folder = ... TnyHeader *header = ... TnyMsg *message = tny_folder_get_msg (folder, header, NULL); tny_msg_view_set_msg (message_view, message); g_object_unref (G_OBJECT (message));
Note that once you received the message this way, the entire message instance is detached from any folder. This means that if you get the header using the tny_msg_get_header API, that this header can't be used with folder API like tny_folder_transfer_msgs and tny_folder_transfer_msgs_async. You can only use header instances that you got with tny_folder_get_headers for these and other such methods. The message's instance nor its header also wont receive updates from the observable folder (like what a TnyFolderObserver would do, for example in case a message got removed from the remote store, like the folder on the IMAP server).
self : |
a TnyFolder object |
header : |
the header of the message to get |
err : |
a GError object or NULL |
Returns : | The message instance or NULL on failure |
TnyMsg* tny_folder_find_msg (TnyFolder *self, const gchar *url_string, GError **err);
Get a message in self
identified by url_string
. If not NULL, you must
unreference the return value after use.
See tny_folder_get_url_string()
for details of the url
-string syntax.
Example:
TnyMsgView *message_view = tny_platform_factory_new_msg_view (platfact); TnyFolder *folder = ... TnyMsg *message = tny_folder_find_msg (folder, "imap://account/INBOX/100", NULL); tny_msg_view_set_msg (message_view, message); g_object_unref (G_OBJECT (message));
self : |
a TnyFolder object |
url_string : |
the url string |
err : |
a GError object or NULL |
Returns : | The message instance or NULL on failure |
void tny_folder_get_msg_async (TnyFolder *self, TnyHeader *header, TnyGetMsgCallback callback, TnyStatusCallback status_callback, gpointer user_data);
Get a message in self
identified by header
.
If you want to use this functionality, it's advised to let your application
use the 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 implementation detects 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 the gdk_threads_enter and gdk_threads_leave guards (because it happens in the GMainLoop).
Example:
static void status_cb (GObject *sender, TnyStatus *status, gpointer user_data) { printf ("."); } static void folder_get_msg_cb (TnyFolder *folder, TnyMsg *msg, GError **err, gpointer user_data) { TnyMsgView *message_view = user_data; tny_msg_view_set_msg (message_view, message); } TnyMsgView *message_view = tny_platform_factory_new_msg_view (platfact); TnyFolder *folder = ...; TnyHeader *header = ...; tny_folder_get_msg_async (folder, header, folder_get_msg_cb, status_cb, message_view);
void tny_folder_get_headers (TnyFolder *self, TnyList *headers, gboolean refresh, GError **err);
Get the list of message header instances that are in self
. Also read
about tny_folder_refresh.
API warning: it's possible that between the refresh
and err
, a pointer to
a query object will be placed. This will introduce both an API and ABI
breakage.
Example:
TnyList *headers = tny_simple_list_new (); TnyFolder *folder = ...; TnyIterator *iter; tny_folder_get_headers (folder, headers, TRUE, NULL); iter = tny_list_create_iterator (headers); while (!tny_iterator_is_done (iter)) { TnyHeader *header = tny_iterator_get_current (iter); g_print ("%s\n", tny_header_get_subject (header)); g_object_unref (G_OBJECT (header)); tny_iterator_next (iter); } g_object_unref (G_OBJECT (iter)); g_object_unref (G_OBJECT (headers));
self : |
a TnyFolder object |
headers : |
A TnyList instance where the headers will be put |
refresh : |
whether or not to synchronize with the service first |
err : |
a GError object or NULL |
void tny_folder_get_headers_async (TnyFolder *self, TnyList *headers, gboolean refresh, TnyGetHeadersCallback callback, TnyStatusCallback status_callback, gpointer user_data);
Get the list of message header instances that are in self
. Also read
about tny_folder_refresh.
API warning: it's possible that between the refresh
and callback
, a pointer
to a query object will be placed. This will introduce both an API and ABI
breakage.
self : |
a TnyFolder object |
headers : |
A TnyList instance where the headers will be put |
refresh : |
whether or not to synchronize with the service first |
callback : |
the callback that happens when the operation finished |
status_callback : |
status callback |
user_data : |
user data |
TnyAccount* tny_folder_get_account (TnyFolder *self);
Get a the parent account of this folder or NULL. If not NULL, you must unreference the return value after use.
self : |
a TnyFolder object |
Returns : | the account of this folder or NULL |
const gchar* tny_folder_get_id (TnyFolder *self);
Get an unique id of self
(unique per account). The ID will usually be a "/"
separated string like (but not guaranteed) "INBOX/parent-folder/folder"
depending on the service type (the example is for IMAP using the
libtinymail-camel implementation).
The ID is guaranteed to be unique per account. You should not free the result of this method.
self : |
a TnyFolder object |
Returns : | A unique id |
const gchar* tny_folder_get_name (TnyFolder *self);
Get the displayable name of
self. You should not free the result of
this method.
self : |
a TnyFolder object |
Returns : | The folder name |
TnyFolderType tny_folder_get_folder_type (TnyFolder *self);
Get the type of self
(Inbox, Outbox etc.)
Most implementations decide the type by comparing the name of the folder
with some hardcoded values.
Some implementations (such as camel) might not provide precise information
before a connection has been made. For instance, the return value might
be TNY_FOLDER_TYPE_NORMAL rather than TNY_FOLDER_TYPE_SENT.
self : |
a TnyFolder object |
Returns : | The folder type as a TnyFolderType enum |
guint tny_folder_get_all_count (TnyFolder *self);
Get the amount of messages in this folder. The value is only garuanteed to be correct after tny_folder_refresh or after the callback of a tny_folder_refresh_async happened.
self : |
a TnyFolder object |
Returns : | amount of messages |
guint tny_folder_get_unread_count (TnyFolder *self);
Get the amount of unread messages in this folder. The value is only garuanteed to be correct after tny_folder_refresh or after the callback of a tny_folder_refresh_async happened.
self : |
a TnyFolder object |
Returns : | amount of unread messages |
guint tny_folder_get_local_size (TnyFolder *self);
Get the local size of this folder in bytes. Local size means the amount of disk space that this folder consumes.
self : |
a TnyFolder object |
Returns : | get the local size of this folder |
gboolean tny_folder_is_subscribed (TnyFolder *self);
Get the subscribtion status of this folder.
self : |
a TnyFolder object |
Returns : | subscribe status |
void tny_folder_refresh_async (TnyFolder *self, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data);
Refresh self
and call back when finished. This gets the summary information
from the E-Mail service, writes it to the the on-disk cache and/or updates
it.
After this method, tny_folder_get_all_count and tny_folder_get_unread_count are guaranteed to be correct.
If you want to use this method, it's advised to let your application
use the 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 implementation detects using (g_main_depth > 0), the callbacks will happen in a worker thread at an unknown moment in time (check your locking in this case).
When using Gtk+, the callback doesn't need the gdk_threads_enter and gdk_threads_leave guards (because it happens in the GMainLoop).
Example:
static void status_update_cb (GObject *sender, TnyStatus *status, gpointer user_data) { g_print ("."); } static void folder_refresh_cb (TnyFolder *folder, gboolean cancelled, GError **err, gpointer user_data) { if (!cancelled) { TnyList *headers = tny_simple_list_new (); TnyIterator *iter; g_print ("done\nHeaders for %s are:", tny_folder_get_name (folder)); tny_folder_get_headers (folder, headers, FALSE); iter = tny_list_create_iterator (headers); while (!tny_iterator_is_done (iter)) { TnyHeader *header = tny_iterator_current (iter); g_print ("\t%s\n", tny_header_get_subject (header)); g_object_unref (G_OBJECT (header)); tny_iterator_next (iter); } g_object_unref (G_OBJECT (headers)); } } TnyFolder *folder = ... g_print ("Getting headers "); tny_folder_refresh_async (folder, folder_refresh_cb, status_update_cb, NULL);
self : |
a TnyFolder object |
callback : |
The callback handler. This is called last. |
status_callback : |
A callback for status notifications. This is never called after callback .
|
user_data : |
user data for the callback |
void tny_folder_refresh (TnyFolder *self, GError **err);
Refresh the folder. This gets the summary information from the E-Mail service, writes it to the the on-disk cache and/or updates it.
After this method, tny_folder_get_all_count and tny_folder_get_unread_count are guaranteed to be correct.
Also read about tny_folder_get_headers.
self : |
a TnyFolder object |
err : |
a GError object or NULL |
void tny_folder_transfer_msgs (TnyFolder *self, TnyList *header_list, TnyFolder *folder_dst, gboolean delete_originals, GError **err);
Transfers messages of which the headers are in header_list
from self
to
folder_dst
. They could be moved or just copied depending on the value of
the delete_originals
argument.
You must not use header instances that you got from tny_msg_get_header with this API. You must only use instances that you got from tny_folder_get_headers!
self : |
the TnyFolder where the headers are stored |
header_list : |
a list of TnyHeader objects |
folder_dst : |
the TnyFolder where the msgs will be transfered |
delete_originals : |
if TRUE then move msgs, else copy them |
err : |
a GError object or NULL |
void tny_folder_transfer_msgs_async (TnyFolder *self, TnyList *header_list, TnyFolder *folder_dst, gboolean delete_originals, TnyTransferMsgsCallback callback, TnyStatusCallback status_callback, gpointer user_data);
Transfers messages of which the headers are in header_list
from self
to
folder_dst
. They could be moved or just copied depending on the value of
the delete_originals
argument
If you want to use this functionality, it's advised to let your application
use the 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 implementation detects 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 the gdk_threads_enter and gdk_threads_leave guards (because it happens in the GMainLoop).
You must not use header instances that you got from tny_msg_get_header with this API. You must only use instances that you got from tny_folder_get_headers!
self : |
the TnyFolder where the headers are stored |
header_list : |
a list of TnyHeader objects |
folder_dst : |
the TnyFolder where the msgs will be transfered |
delete_originals : |
if TRUE then move msgs, else copy them |
callback : |
The callback handler |
status_callback : |
the status callback handler |
user_data : |
user data for the callback |
TnyFolder* tny_folder_copy (TnyFolder *self, TnyFolderStore *into, const gchar *new_name, gboolean del, GError **err);
Copies self
to into
giving the new folder the name new_name
. Returns the
newly created folder in into
, which will carry the name new_name
. For some
remote services this functionality is implemented as a rename operation.
It will do both copying and in case of del
being TRUE, removing too,
recursively. If you don't want it to be recursive, you should in stead create
the folder new_name
in into
manually using tny_folder_store_create_folder
and then use the tny_folder_transfer_msgs API.
This method will always result in create observer events being throw for each
subfolder of self
that is copied or moved to new_name
in creation order
(parents first, childs after that).
In case of del
being TRUE it will on top of that and before those create
events also result in remove observer events being throw for each subfolder
of self
in deletion order (the exact reversed order: childs first, parents
after that)
Standard folder models like the TnyGtkFolderStoreListModel know about this behavior and will act by updating themselves automatically.
When you are moving self
to into
with del
set to TRUE (moving self
), you
MUST make sure that self
nor any of its sub folders are used anymore. For
example if you have gotten headers using tny_folder_get_headers, you MUST get
rid of those first. In case you used a default component like the
TnyGtkHeaderListModel or any other TnyList for storing the headers, you can
easily get rid if your headers by setting the model of the GtkTreeView to
an empty one or unreferencing the list. You MUST NOT try to keep using it nor
any of its headers. These instances will be invalid and in a destroyed state.
If new_name
already exists in into
and err
is not NULL, then an error will
be set in err
and no further action will be performed.
self : |
a TnyFolder object |
into : |
a TnyFolderStore object |
new_name : |
the new name in into
|
del : |
whether or not to delete the original location |
err : |
a GError object or NULL |
Returns : | a new folder instance to whom was copied or NULL in case of failure |
void tny_folder_copy_async (TnyFolder *self, TnyFolderStore *into, const gchar *new_name, gboolean del, TnyCopyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data);
Copies self
to into
giving the new folder the name new_name
. Returns the
newly created folder in into
, which will carry the name new_name
. For some
remote services this functionality is implemented as a rename operation.
It will do both copying and in case of del
being TRUE, removing too,
recursively. If you don't want it to be recursive, you should in stead create
the folder new_name
in into
manually using tny_folder_store_create_folder
and then use the tny_folder_transfer_msgs API.
This method will always result in create observer events being throw for each
subfolder of self
that is copied or moved to new_name
in creation order
(parents first, childs after that).
In case of del
being TRUE it will on top of that and before those create
events also result in remove observer events being throw for each subfolder
of self
in deletion order (the exact reversed order: childs first, parents
after that)
Standard folder models like the TnyGtkFolderStoreListModel know about this behavior and will act by updating themselves automatically.
When you are moving self
to into
with del
set to TRUE (moving self
), you
MUST make sure that self
nor any of its sub folders are used anymore. For
example if you have gotten headers using tny_folder_get_headers, you MUST get
rid of those first. In case you used a default component like the
TnyGtkHeaderListModel or any other TnyList for storing the headers, you can
easily get rid if your headers by setting the model of the GtkTreeView to
an empty one or unreferencing the list. You MUST NOT try to keep using it nor
any of its headers. These instances will be invalid and in a destroyed state.
If new_name
already exists in into
and err
is not NULL, then an error will
be set in err
and no further action will be performed.
If you want to use this method, it's advised to let your application
use the 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 implementation detects using (g_main_depth > 0), the callbacks will happen in a worker thread at an unknown moment in time (check your locking in this case).
When using Gtk+, the callback doesn't need the gdk_threads_enter and gdk_threads_leave guards (because it happens in the GMainLoop).
Example:
static void status_update_cb (GObject *sender, TnyStatus *status, gpointer user_data) { g_print ("."); } static void folder_copy_cb (TnyFolder *folder, TnyFolderStore *into, const gchar *new_name, gboolean cancelled, GError **err, gpointer user_data) { if (!cancelled) { TnyList *headers = tny_simple_list_new (); TnyIterator *iter; g_print ("done\nHeaders copied into %s are:", tny_folder_get_name (into)); tny_folder_get_headers (into, headers, FALSE); iter = tny_list_create_iterator (headers); while (!tny_iterator_is_done (iter)) { TnyHeader *header = tny_iterator_current (iter); g_print ("\t%s\n", tny_header_get_subject (header)); g_object_unref (G_OBJECT (header)); tny_iterator_next (iter); } g_object_unref (G_OBJECT (headers)); } } TnyFolder *folder = ... TnyFolderStore *into = ... gchar *new_name = ... g_print ("Getting headers "); tny_folder_copy_async (folder, into, new_name, folder_copy_cb, status_update_cb, NULL);
self : |
a TnyFolder object |
into : |
a TnyFolderStore object |
new_name : |
the new name in into
|
del : |
whether or not to delete the original location |
callback : |
callback that happens when the operation finished |
status_callback : |
cllback that'll happen whenever there's status |
user_data : |
user data |
void tny_folder_poke_status (TnyFolder *self);
Poke for the status, this will invoke the event of sending a TnyFolderChange to the observers. The change will always at least contain the unread and total folder count, also if the unread and total didn't change at all. This makes it possible for a model or view that shows folders to get the initial folder unread and total counts (the TnyGtkFolderStoreListModel uses this method internally, for example).
self : |
a TnyFolder object |
void tny_folder_add_observer (TnyFolder *self, TnyFolderObserver *observer);
Add observer
to the list of interested observers for events that could happen
caused by for example a tny_folder_poke_status and other spontaneous changes
(like Push E-mail events).
After this, observer
will start receiving notification of changes about self
.
You must use tny_folder_remove_observer in for example the finalization of
your type if you used this method. Adding an observer to self
, changes
reference counting of the objects involved. Removing the observer will undo
those reference counting changes. Therefore if you don't, you will introduce
memory leaks.
self : |
a TnyFolder instance |
observer : |
a TnyFolderObserver instance |
void tny_folder_remove_observer (TnyFolder *self, TnyFolderObserver *observer);
Remove observer
from the list of interested observers for events that could
happen caused by for example a tny_folder_poke_status and other spontaneous
changes (like Push E-mail events).
After this, observer
will no longer receive notification of changes about self
.
You must use this method in for example the finalization of your type if you
used tny_folder_add_observer. Adding an observer to self
, changes reference
counting of the objects involved. Removing the observer will undo those
reference counting changes. Therefore if you don't, you will introduce memory
leaks.
self : |
a TnyFolder instance |
observer : |
a TnyFolderObserver instance |
TnyFolderStore* tny_folder_get_folder_store (TnyFolder *self);
Get a the parent store of this folder. You must unreference the return value after use. Note that not every folder strictly has to be inside a folder store.
self : |
a TnyFolder object |
Returns : | the folder store of this folder, or NULL if the folder is not inside a folder store |
TnyFolderStats* tny_folder_get_stats (TnyFolder *self);
Get some statistics of the folder self
. The returned statistics object will
not change after you got it. If you need an updated version, you need to call
this method again. You must unreference the return value after use.
This method is a rather heavy operation that might consume a lot of memory to achieve its return value. There are more finegrained APIs available in TnyFolder that will get you the same counts in a less expensive way. With this method you get a combined statistic, however.
self : |
a TnyFolder object |
Returns : | some statistics of the folder |
TnyFolderCaps tny_folder_get_caps (TnyFolder *self);
Get a few relevant capabilities of self
.
self : |
a TnyFolder object |
Returns : | The capabilities of the folder |
gchar* tny_folder_get_url_string (TnyFolder *self);
Get the url_string of self
or NULL if it's impossible to determine the url
string of self
. If not NULL, the returned value must be freed after use.
The url string is specified in RFC 1808 and / or RFC 4467 and looks like this: imap://server/INBOX/folder. Note that it doesn't necessarily contain the password of the IMAP account but can contain it.
self : |
a TnyFolder object |
Returns : | The url string or NULL. |