![]() |
![]() |
![]() |
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); GType tny_folder_caps_get_type (void); GType tny_folder_signal_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_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 _TnyFolder TnyFolder;
A folder, or a mailbox depending on what you prefer to call it
free-function: g_object_unref
typedef struct { GTypeInterface parent; /* Methods */ void (*remove_msg) (TnyFolder *self, TnyHeader *header, GError **err); void (*remove_msgs) (TnyFolder *self, TnyList *headers, GError **err); void (*add_msg) (TnyFolder *self, TnyMsg *msg, GError **err); void (*add_msg_async) (TnyFolder *self, TnyMsg *msg, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data); void (*sync) (TnyFolder *self, gboolean expunge, GError **err); void (*sync_async) (TnyFolder *self, gboolean expunge, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data); TnyMsgRemoveStrategy* (*get_msg_remove_strategy) (TnyFolder *self); void (*set_msg_remove_strategy) (TnyFolder *self, TnyMsgRemoveStrategy *st); TnyMsgReceiveStrategy* (*get_msg_receive_strategy) (TnyFolder *self); void (*set_msg_receive_strategy) (TnyFolder *self, TnyMsgReceiveStrategy *st); TnyMsg* (*get_msg) (TnyFolder *self, TnyHeader *header, GError **err); TnyMsg* (*find_msg) (TnyFolder *self, const gchar *url_string, GError **err); void (*get_msg_async) (TnyFolder *self, TnyHeader *header, TnyGetMsgCallback callback, TnyStatusCallback status_callback, gpointer user_data); void (*get_headers) (TnyFolder *self, TnyList *headers, gboolean refresh, GError **err); void (*get_headers_async) (TnyFolder *self, TnyList *headers, gboolean refresh, TnyGetHeadersCallback callback, TnyStatusCallback status_callback, gpointer user_data); const gchar* (*get_name) (TnyFolder *self); const gchar* (*get_id) (TnyFolder *self); TnyAccount* (*get_account) (TnyFolder *self); TnyFolderType (*get_folder_type) (TnyFolder *self); guint (*get_all_count) (TnyFolder *self); guint (*get_unread_count) (TnyFolder *self); guint (*get_local_size) (TnyFolder *self); gboolean (*is_subscribed) (TnyFolder *self); void (*refresh_async) (TnyFolder *self, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data); void (*refresh) (TnyFolder *self, GError **err); void (*transfer_msgs) (TnyFolder *self, TnyList *header_list, TnyFolder *folder_dst, gboolean delete_originals, GError **err); void (*transfer_msgs_async) (TnyFolder *self, TnyList *header_list, TnyFolder *folder_dst, gboolean delete_originals, TnyTransferMsgsCallback callback, TnyStatusCallback status_callback, gpointer user_data); TnyFolder* (*copy) (TnyFolder *self, TnyFolderStore *into, const gchar *new_name, gboolean del, GError **err); void (*copy_async) (TnyFolder *self, TnyFolderStore *into, const gchar *new_name, gboolean del, TnyCopyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data); void (*poke_status) (TnyFolder *self); void (*add_observer) (TnyFolder *self, TnyFolderObserver *observer); void (*remove_observer) (TnyFolder *self, TnyFolderObserver *observer); TnyFolderStore* (*get_folder_store) (TnyFolder *self); TnyFolderStats* (*get_stats) (TnyFolder *self); gchar* (*get_url_string) (TnyFolder *self); TnyFolderCaps (*get_caps) (TnyFolder *self); } TnyFolderIface;
GType tny_folder_type_get_type (void);
GType system helper function
Returns : |
a GType |
GType tny_folder_caps_get_type (void);
GType system helper function
Returns : |
a GType |
GType tny_folder_signal_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.
|
a TnyFolder |
Returns : |
(caller-owns): the strategy for removing a message |
Since 1.0 audience: application-developer
void tny_folder_set_msg_remove_strategy (TnyFolder *self, TnyMsgRemoveStrategy *st);
Set the strategy for removing a message
For more information take a look at tny_msg_remove_strategy_peform_remove()
of TnyMsgRemoveStrategy.
|
a TnyFolder |
|
a TnyMsgRemoveStrategy |
Since 1.0 audience: application-developer
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.
|
a TnyFolder |
Returns : |
(caller-owns): the strategy for receiving a message |
Since 1.0 audience: application-developer
void tny_folder_set_msg_receive_strategy (TnyFolder *self, TnyMsgReceiveStrategy *st);
Set the strategy for receiving a message. Some common strategies are:
- TnyCamelPartialMsgReceiveStrategy for a strategy that tries to only receive the text parts of an E-mail. - TnyCamelFullMsgReceiveStrategy (current default) for a strategy that requests the entire message - TnyCamelBsMsgReceiveStrategy for a strategy that receives a BODYSTRUCTURE and then per MIME part that is needed, requests the needed MIME part
For more information take a look at tny_msg_receive_strategy_peform_get_msg()
of TnyMsgReceiveStrategy.
|
a TnyFolder |
|
a TnyMsgReceiveStrategy |
Since 1.0 audience: application-developer
void tny_folder_remove_msg (TnyFolder *self, TnyHeader *header, GError **err);
Remove a message from a folder. It will use the TnyMsgRemoveStrategy of
self
to perform the removal itself. For more details, check out the
documentation of the used TnyMsgRemoveStrategy type. The default
implementation for libtinymail-camel is the TnyCamelMsgRemoveStrategy.
Folder observers of self
will get a header-removed event 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 (folder); g_object_unref (header); } } }
Since 1.0 audience: application-developer
void tny_folder_remove_msgs (TnyFolder *self, TnyList *headers, GError **err);
Remove messages from a folder. It will use the TnyMsgRemoveStrategy of
self
to perform the removal itself. For more details, check out the
documentation of the used TnyMsgRemoveStrategy type. The default
implementation for libtinymail-camel is the TnyCamelMsgRemoveStrategy.
Folder observers of self
will get only one header-removed trigger caused
by this action (with all the removed headers in the TnyFolderChange).
|
a TnyFolder |
|
a TnyList with TnyHeader items of the messages to remove |
|
(null-ok): a GError or NULL |
Since 1.0 audience: application-developer
void tny_folder_add_msg (TnyFolder *self, TnyMsg *msg, GError **err);
Add a message to a self
. It's recommended to destroy msg
afterwards because
after receiving the same message from the folder again, the instance wont be
the same and a property like the tny_msg_get_id()
will have changed.
Folder observers of self
will get a header-added event caused by this
action.
Since 1.0 audience: application-developer
void tny_folder_add_msg_async (TnyFolder *self, TnyMsg *msg, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data);
Add a message to a self
. It's recommended to destroy msg
afterwards because
after receiving the same message from the folder again, the instance wont be
the same and a property like the tny_msg_get_id()
will have changed.
Folder observers of self
will get a header-added event caused by this
action.
|
a TnyFolder |
|
a TnyMsg |
|
(null-ok): a TnyFolderCallback or NULL |
|
(null-ok): a TnyStatusCallback or NULL |
|
(null-ok): user data that will be passed to the callbacks |
Since 1.0 audience: application-developer
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 (header); tny_folder_sync (folder, TRUE, NULL); g_object_unref (folder);
|
a TnyFolder |
|
also expunge deleted messages |
|
(null-ok): a GError or NULL |
Since 1.0 audience: application-developer
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 paradoxical 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.
|
a TnyFolder |
|
also expunge deleted messages |
|
(null-ok): a TnySyncFolderCallback or NULL |
|
(null-ok): a TnyStatusCallback or NULL |
|
(null-ok): user data that will be passed to the callbacks |
Since 1.0 audience: application-developer
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 (message);
Note that once you received the message this way, the entire message instance
is detached from self
. This means that if you get a new 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 this and
other TnyFolder methods. The message's instance nor its header will receive
updates from the observable folder.
|
a TnyFolder |
|
a TnyHeader the message to get |
|
(null-ok): a GError or NULL |
Returns : |
(null-ok) (caller-owns): The message instance or NULL |
Since 1.0 audience: application-developer
TnyMsg* tny_folder_find_msg (TnyFolder *self, const gchar *url_string, GError **err);
Get the 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 (message);
|
a TnyFolder |
|
the url string |
|
(null-ok): a GError or NULL |
Returns : |
(null-ok) (caller-owns): The message instance or NULL |
Since 1.0 audience: application-developer
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
asynchronously.
Example:
static void status_cb (GObject *sender, TnyStatus *status, gpointer user_data) { printf ("."); } static void folder_get_msg_cb (TnyFolder *folder, gboolean cancelled, TnyMsg *msg, GError **err, gpointer user_data) { TnyMsgView *message_view = user_data; if (!err && msg && !cancelled) tny_msg_view_set_msg (message_view, msg); } 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);
|
a TnyFolder |
|
a TnyHeader of the message to get |
|
(null-ok): a TnyGetMsgCallback or NULL |
|
(null-ok): a TnyStatusCallback or NULL |
|
(null-ok): user data that will be passed to the callbacks |
Since 1.0 audience: application-developer
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()
and tny_folder_refresh_async()
.
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 (header); tny_iterator_next (iter); } g_object_unref (iter); g_object_unref (headers);
|
a TnyFolder |
|
A TnyList where the headers will be prepended to |
|
synchronize with the service first |
|
(null-ok): a GError or NULL |
Since 1.0 audience: application-developer
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()
and tny_folder_refresh_async()
.
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.
|
a TnyFolder |
|
A TnyList where the headers will be prepended to |
|
synchronize with the service first |
|
(null-ok): a TnyGetHeadersCallback or NULL |
|
(null-ok): a TnyStatusCallback or NULL |
|
(null-ok): user data that will be passed to the callbacks |
Since 1.0 audience: application-developer
TnyAccount* tny_folder_get_account (TnyFolder *self);
Get a the account of this folder or NULL. If not NULL, you must unreference the return value after use.
|
a TnyFolder |
Returns : |
(null-ok) (caller-owns): the account of this folder or NULL |
Since 1.0 audience: application-developer
const gchar* tny_folder_get_id (TnyFolder *self);
Get an unique id of self
(unique per account). The id will usually be a
string separated with slashes or backslashes like (but not guaranteed)
"INBOX/parent-folder/folder" depending on the service type (this example is
for IMAP using the libtinymail-camel implementation).
The ID is guaranteed to be unique per account. You must not free the result of this method.
|
a TnyFolder |
Returns : |
unique id |
Since 1.0 audience: application-developer
const gchar* tny_folder_get_name (TnyFolder *self);
Get the displayable name of self
. You should not free the result of
this method.
|
a TnyFolder |
Returns : |
folder name |
Since 1.0 audience: application-developer
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.
|
a TnyFolder |
Returns : |
folder type |
Since 1.0 audience: application-developer
guint tny_folder_get_all_count (TnyFolder *self);
Get the amount of messages in this folder. The value is only guaranteed to
be correct after tny_folder_refresh()
or during the callback of a
tny_folder_refresh_async()
.
|
a TnyFolder |
Returns : |
amount of messages |
Since 1.0 audience: application-developer
guint tny_folder_get_unread_count (TnyFolder *self);
Get the amount of unread messages in this folder. The value is only
guaranteed to be correct after tny_folder_refresh()
or during the
callback of a tny_folder_refresh_async()
.
|
a TnyFolder |
Returns : |
amount of unread messages |
Since 1.0 audience: application-developer
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 locally in the caches.
|
a TnyFolder |
Returns : |
get the local size of this folder |
Since 1.0 audience: application-developer
gboolean tny_folder_is_subscribed (TnyFolder *self);
Get the subscription status of self
.
|
a TnyFolder |
Returns : |
subscription state |
Since 1.0 audience: application-developer
void tny_folder_refresh_async (TnyFolder *self, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data);
Refresh self
and callback 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, when callback
takes place, tny_folder_get_all_count()
and tny_folder_get_unread_count()
are guaranteed to be correct. The API
tny_folder_get_headers()
is guaranteed to put an accurate list of headers
in the provided TnyList.
While the refresh takes place, it's possible that event observers of self
will get notified of new header additions. TnyFolderMonitor copes with those
by publishing them to TnyList instances, like a TnyGtkHeaderListModel.
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 (header); tny_iterator_next (iter); } g_object_unref (iter); g_object_unref (headers); } } TnyFolder *folder = ... g_print ("Getting headers "); tny_folder_refresh_async (folder, folder_refresh_cb, status_update_cb, NULL);
|
a TnyFolder |
|
(null-ok): a TnyFolderCallback or NULL |
|
(null-ok): a TnyStatusCallback or NULL |
|
(null-ok): user data that will be passed to the callbacks |
Since 1.0 audience: application-developer
void tny_folder_refresh (TnyFolder *self, GError **err);
Refresh self
. 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. The API tny_folder_get_headers()
is guaranteed to
put an accurate list of headers in the provided TnyList.
While the refresh takes place, it's possible that event observers of self
will get notified of new header additions. TnyFolderMonitor copes with those
by publishing them to TnyList instances, like a TnyGtkHeaderListModel.
This function can take a very long time. You are advised to consider using
tny_folder_refresh_async()
in stead.
|
a TnyFolder |
|
(null-ok): a GError or NULL |
Since 1.0 audience: application-developer
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()
.
|
a TnyFolder |
|
a TnyList of TnyHeader instances in self to move
|
|
a destination TnyFolder |
|
TRUE moves msgs, FALSE copies |
|
(null-ok): a GError or NULL |
Since 1.0 audience: application-developer
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.
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()
.
|
a TnyFolder |
|
a TnyList of TnyHeader instances in self to move
|
|
a destination TnyFolder |
|
TRUE moves msgs, FALSE copies |
|
(null-ok): a TnyTransferMsgsCallback or NULL |
|
(null-ok): a TnyStatusCallback or NULL |
|
(null-ok): user data that will be passed to the callbacks |
Since 1.0 audience: application-developer
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 result in create events being thrown to the observers of
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 events being thrown to the observers of 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.
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.
|
a TnyFolder |
|
a TnyFolderStore |
|
the new name in into
|
|
whether or not to delete the original location |
|
(null-ok): a GError object or NULL |
Returns : |
(null-ok) (caller-owns): a new folder instance to whom was copied or NULL |
Since 1.0 audience: application-developer
void tny_folder_copy_async (TnyFolder *self, TnyFolderStore *into, const gchar *new_name, gboolean del, TnyCopyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data);
See tny_folder_copy()
. This is the asynchronous version of the same function.
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 (header); tny_iterator_next (iter); } g_object_unref (iter); g_object_unref (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);
|
a TnyFolder |
|
a TnyFolderStore |
|
the new name in into
|
|
whether or not to delete the original location |
|
(null-ok): a TnyCopyFolderCallback or NULL |
|
(null-ok): a TnyStatusCallback or NULL |
|
(null-ok): user data that will be passed to the callbacks |
Since 1.0 audience: application-developer
void tny_folder_poke_status (TnyFolder *self);
Poke for the status, this will invoke an event to the event observers of
self
. 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).
|
a TnyFolder |
Since 1.0 audience: application-developer
void tny_folder_add_observer (TnyFolder *self, TnyFolderObserver *observer);
Add observer
to the list of event observers. Among the events that could
happen are caused by for example a tny_folder_poke_status()
and spontaneous
change notifications like Push E-mail events.
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
.
|
a TnyFolder |
|
a TnyFolderObserver |
Since 1.0 audience: application-developer
void tny_folder_remove_observer (TnyFolder *self, TnyFolderObserver *observer);
Remove observer
from the list of event observers of self
.
The weak reference added by tny_folder_add_observer()
to observer
, is
removed.
|
a TnyFolder |
|
a TnyFolderObserver |
Since 1.0 audience: application-developer
TnyFolderStore* tny_folder_get_folder_store (TnyFolder *self);
Get a the parent TnyFolderStore of this folder. You must unreference the return value after use if not NULL. Note that not every folder strictly has to be inside a folder store. This API will in that case return NULL.
|
a TnyFolder |
Returns : |
(null-ok) (caller-owns): the folder store of this folder or NULL |
Since 1.0 complexity: low audience: application-developer
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.
|
a TnyFolder |
Returns : |
(caller-owns): some statistics of the folder |
Since 1.0 audience: application-developer
TnyFolderCaps tny_folder_get_caps (TnyFolder *self);
Get a few relevant capabilities of self
.
|
a TnyFolder |
Returns : |
The capabilities of the folder |
Since 1.0 audience: application-developer
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.
|
a TnyFolder |
Returns : |
(null-ok) (caller-owns): The url string or NULL. |
Since 1.0 audience: application-developer