TnyFolder

TnyFolder — A type that defines a folder

Synopsis




                    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_add_msg                  (TnyFolder *self,
                                                         TnyMsg *msg,
                                                         GError **err);
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);

Object Hierarchy


  GInterface
   +----TnyFolder

Prerequisites

TnyFolder requires GObject.

Known Implementations

TnyFolder is implemented by TnyCamelFolder, TnyCamelIMAPFolder, TnyCamelNNTPFolder, TnyCamelPOPFolder and TnyMergeFolder.

Description

A abstract type that defines a folder

Details

TnyFolder

typedef struct _TnyFolder TnyFolder;


TnyFolderIface

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;


TNY_TYPE_FOLDER_SIGNAL

#define TNY_TYPE_FOLDER_SIGNAL (tny_folder_signal_get_type())


TNY_TYPE_FOLDER_TYPE

#define TNY_TYPE_FOLDER_TYPE (tny_folder_type_get_type())


TNY_TYPE_FOLDER_CAPS

#define TNY_TYPE_FOLDER_CAPS (tny_folder_caps_get_type())


tny_folder_type_get_type ()

GType               tny_folder_type_get_type            (void);

GType system helper function

Returns : a GType

tny_folder_get_msg_remove_strategy ()

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

tny_folder_set_msg_remove_strategy ()

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

tny_folder_get_msg_receive_strategy ()

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

tny_folder_set_msg_receive_strategy ()

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

tny_folder_remove_msg ()

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

tny_folder_add_msg ()

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.

self : a TnyFolder object
msg : a TnyMsg object
err : a GError object or NULL

tny_folder_sync ()

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

tny_folder_sync_async ()

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

tny_folder_get_msg ()

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

tny_folder_find_msg ()

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

tny_folder_get_msg_async ()

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

self : a TnyFolder object
header : a TnyHeader object
callback : The callback handler
status_callback : the status callback handler
user_data : user data for the callback

tny_folder_get_headers ()

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

tny_folder_get_headers_async ()

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

tny_folder_get_account ()

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

tny_folder_get_id ()

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

tny_folder_get_name ()

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

tny_folder_get_folder_type ()

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

tny_folder_get_all_count ()

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

tny_folder_get_unread_count ()

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

tny_folder_get_local_size ()

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

tny_folder_is_subscribed ()

gboolean            tny_folder_is_subscribed            (TnyFolder *self);

Get the subscribtion status of this folder.

self : a TnyFolder object
Returns : subscribe status

tny_folder_refresh_async ()

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

tny_folder_refresh ()

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

tny_folder_transfer_msgs ()

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

tny_folder_transfer_msgs_async ()

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

tny_folder_copy ()

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

tny_folder_copy_async ()

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

tny_folder_poke_status ()

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

tny_folder_add_observer ()

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

tny_folder_remove_observer ()

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

tny_folder_get_folder_store ()

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

tny_folder_get_stats ()

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

tny_folder_get_caps ()

TnyFolderCaps       tny_folder_get_caps                 (TnyFolder *self);

Get a few relevant capabilities of self.

self : a TnyFolder object
Returns : The capabilities of the folder

tny_folder_get_url_string ()

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.

See Also

TnyFolderStore, TnyStoreAccount, TnyCamelFolder, TnyFolderSignal