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

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;

A folder, or a mailbox depending on what you prefer to call it

free-function: g_object_unref


TnyFolderIface

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;


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_caps_get_type ()

GType               tny_folder_caps_get_type            (void);

GType system helper function

Returns :

a GType

tny_folder_signal_get_type ()

GType               tny_folder_signal_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.

self :

a TnyFolder

Returns :

(caller-owns): the strategy for removing a message

Since 1.0 audience: application-developer


tny_folder_set_msg_remove_strategy ()

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.

self :

a TnyFolder

st :

a TnyMsgRemoveStrategy

Since 1.0 audience: application-developer


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

Returns :

(caller-owns): the strategy for receiving a message

Since 1.0 audience: application-developer


tny_folder_set_msg_receive_strategy ()

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.

self :

a TnyFolder

st :

a TnyMsgReceiveStrategy

Since 1.0 audience: application-developer


tny_folder_remove_msg ()

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

self :

a TnyFolder

header :

a TnyHeader of the message to remove

err :

(null-ok): a GError or NULL

Since 1.0 audience: application-developer


tny_folder_remove_msgs ()

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

self :

a TnyFolder

headers :

a TnyList with TnyHeader items of the messages to remove

err :

(null-ok): a GError or NULL

Since 1.0 audience: application-developer


tny_folder_add_msg ()

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.

self :

a TnyFolder

msg :

a TnyMsg

err :

(null-ok): a GError or NULL

Since 1.0 audience: application-developer


tny_folder_add_msg_async ()

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.

self :

a TnyFolder

msg :

a TnyMsg

callback :

(null-ok): a TnyFolderCallback or NULL

status_callback :

(null-ok): a TnyStatusCallback or NULL

user_data :

(null-ok): user data that will be passed to the callbacks

Since 1.0 audience: application-developer


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 (header);
tny_folder_sync (folder, TRUE, NULL);
g_object_unref (folder);

self :

a TnyFolder

expunge :

also expunge deleted messages

err :

(null-ok): a GError or NULL

Since 1.0 audience: application-developer


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 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.

self :

a TnyFolder

expunge :

also expunge deleted messages

callback :

(null-ok): a TnySyncFolderCallback or NULL

status_callback :

(null-ok): a TnyStatusCallback or NULL

user_data :

(null-ok): user data that will be passed to the callbacks

Since 1.0 audience: application-developer


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 (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.

self :

a TnyFolder

header :

a TnyHeader the message to get

err :

(null-ok): a GError or NULL

Returns :

(null-ok) (caller-owns): The message instance or NULL

Since 1.0 audience: application-developer


tny_folder_find_msg ()

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

self :

a TnyFolder

url_string :

the url string

err :

(null-ok): a GError or NULL

Returns :

(null-ok) (caller-owns): The message instance or NULL

Since 1.0 audience: application-developer


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

self :

a TnyFolder

header :

a TnyHeader of the message to get

callback :

(null-ok): a TnyGetMsgCallback or NULL

status_callback :

(null-ok): a TnyStatusCallback or NULL

user_data :

(null-ok): user data that will be passed to the callbacks

Since 1.0 audience: application-developer


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

self :

a TnyFolder

headers :

A TnyList where the headers will be prepended to

refresh :

synchronize with the service first

err :

(null-ok): a GError or NULL

Since 1.0 audience: application-developer


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() 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.

self :

a TnyFolder

headers :

A TnyList where the headers will be prepended to

refresh :

synchronize with the service first

callback :

(null-ok): a TnyGetHeadersCallback or NULL

status_callback :

(null-ok): a TnyStatusCallback or NULL

user_data :

(null-ok): user data that will be passed to the callbacks

Since 1.0 audience: application-developer


tny_folder_get_account ()

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.

self :

a TnyFolder

Returns :

(null-ok) (caller-owns): the account of this folder or NULL

Since 1.0 audience: application-developer


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 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.

self :

a TnyFolder

Returns :

unique id

Since 1.0 audience: application-developer


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

Returns :

folder name

Since 1.0 audience: application-developer


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

Returns :

folder type

Since 1.0 audience: application-developer


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 guaranteed to be correct after tny_folder_refresh() or during the callback of a tny_folder_refresh_async().

self :

a TnyFolder

Returns :

amount of messages

Since 1.0 audience: application-developer


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 guaranteed to be correct after tny_folder_refresh() or during the callback of a tny_folder_refresh_async().

self :

a TnyFolder

Returns :

amount of unread messages

Since 1.0 audience: application-developer


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 locally in the caches.

self :

a TnyFolder

Returns :

get the local size of this folder

Since 1.0 audience: application-developer


tny_folder_is_subscribed ()

gboolean            tny_folder_is_subscribed            (TnyFolder *self);

Get the subscription status of self.

self :

a TnyFolder

Returns :

subscription state

Since 1.0 audience: application-developer


tny_folder_refresh_async ()

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

self :

a TnyFolder

callback :

(null-ok): a TnyFolderCallback or NULL

status_callback :

(null-ok): a TnyStatusCallback or NULL

user_data :

(null-ok): user data that will be passed to the callbacks

Since 1.0 audience: application-developer


tny_folder_refresh ()

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.

self :

a TnyFolder

err :

(null-ok): a GError or NULL

Since 1.0 audience: application-developer


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 :

a TnyFolder

header_list :

a TnyList of TnyHeader instances in self to move

folder_dst :

a destination TnyFolder

delete_originals :

TRUE moves msgs, FALSE copies

err :

(null-ok): a GError or NULL

Since 1.0 audience: application-developer


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.

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 :

a TnyFolder

header_list :

a TnyList of TnyHeader instances in self to move

folder_dst :

a destination TnyFolder

delete_originals :

TRUE moves msgs, FALSE copies

callback :

(null-ok): a TnyTransferMsgsCallback or NULL

status_callback :

(null-ok): a TnyStatusCallback or NULL

user_data :

(null-ok): user data that will be passed to the callbacks

Since 1.0 audience: application-developer


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 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.

self :

a TnyFolder

into :

a TnyFolderStore

new_name :

the new name in into

del :

whether or not to delete the original location

err :

(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


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

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

self :

a TnyFolder

into :

a TnyFolderStore

new_name :

the new name in into

del :

whether or not to delete the original location

callback :

(null-ok): a TnyCopyFolderCallback or NULL

status_callback :

(null-ok): a TnyStatusCallback or NULL

user_data :

(null-ok): user data that will be passed to the callbacks

Since 1.0 audience: application-developer


tny_folder_poke_status ()

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

self :

a TnyFolder

Since 1.0 audience: application-developer


tny_folder_add_observer ()

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.

self :

a TnyFolder

observer :

a TnyFolderObserver

Since 1.0 audience: application-developer


tny_folder_remove_observer ()

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.

self :

a TnyFolder

observer :

a TnyFolderObserver

Since 1.0 audience: application-developer


tny_folder_get_folder_store ()

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.

self :

a TnyFolder

Returns :

(null-ok) (caller-owns): the folder store of this folder or NULL

Since 1.0 complexity: low audience: application-developer


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

Returns :

(caller-owns): some statistics of the folder

Since 1.0 audience: application-developer


tny_folder_get_caps ()

TnyFolderCaps       tny_folder_get_caps                 (TnyFolder *self);

Get a few relevant capabilities of self.

self :

a TnyFolder

Returns :

The capabilities of the folder

Since 1.0 audience: application-developer


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

Returns :

(null-ok) (caller-owns): The url string or NULL.

Since 1.0 audience: application-developer

See Also

TnyFolderStore, TnyStoreAccount, TnyCamelFolder, TnyFolderSignal