Modest Mail Operations

Introduction

In this section we'll describe how mail operations are implemented in Modest. How operations as "send a mail", "get a list of messages", "move folders", etc, are implemented and used.

Modest uses for this Tinymail, but wraps the Tinymail API in these operations that do almost all the needed logic for the operations to happen.

Where?

• ModestMailOperation: modest-mail-operation.ch?
• ModestMailOperationQueue: modest-mail-operation-queue.ch?

ModestMailOperation

This object represents an asynchronous operation:

• Modest won't die while the operation is running
• Most mail operations are cancellable.
• Provides progress feedback using "progress-changed" signal.
• Allows to get the status of the operation (if it's in progress, succesful, cancelled, or if it failed).
• An operation has a source, which usually points to the window the operation started. It allows to cancel the operation when the window is destroyed.

Mail operation methods

These methods are available to operate with any mail operation:

• get_task_done and get_task_total: amount of work done/total. I.e. moving 10 messages we've moved already 3, then done is 3 and total is 10.
• is_finished: TRUE if operation is finished (successful, cancelled, finished with errors or failed).
• get_status: obtains the current status (in progress, failed, succesful, etc.).
• get_error: obtains the error why the mail operation failed (if any).
• get_source: the object that requested the mail operation (usualy a window)
• cancel: cancels the operation (if it's cancellable). Almost all operations are cancellable, with the important exception of sync_folder.
• get_account: obtain the TnyAccount the operation operates with.
• to_string: a string describing the mail operation for debugging

Internal implementation has these important methods:

• notify_start: emits signal notifying that operation has started.
• notify_end: emits signal notifying that operation has finished. This is also used to remove the operation from mail operation queue.

Mail operations available

• send_mail: sends an already existing message (TnyMsg) using a TnyTransportAccount
• send_new_mail: sends a new mail, creating the instance of TnyMsg with the provided data. Used on sending a mail from editor.
• save_to_drafts: creates a instance of TnyMsg and stores it to drafts. Used on closing the editor without sending the mail.
• update_account: updates an store account (refreshes root folders or all folders). I.e. used when we do a send receive of that account.
• update_folder_counts: very similar to update_account. It updates the number of messages available in each folder.
• Folder operations: create_folder, remove_folder, rename_folder
• xfer_folder: moves or copies a folder (to a different parent in same account, or even in a different account).
• xfer_msgs: moves or copies a set of messages to a different folder.
• remove_msgs: remove a set of messages.
• get_msg_and_parts: obtains a message and all its parts from network (or from local cache). You provide a TnyHeader instance to fetch the message.
• get_msg: obtains the message (parts needed to be shown in message view).
• find_msg: similar to get_msg, but you provide an UID for the message instead of a TnyHeader
• get_msgs_full: allows to fetch a list of messages.
• run_queue: it's a special operation, used to keep a mail operation alive while we're sending mails (and avoid modest closing after starting to send a mail).
• queue_wakeup: similar to run_queue. Also used to keep alive modest while send queue wakeup is still running.
• sync_folder: very important operation. This syncs the flags of a folder to server. In fact it's simply a wrapper to keep modest alive while sync happens.
• shutdown: this special mail operation is the one run when there are no mail operations nor windows running, to allow a proper shutdown, and then exit.
• refresh_folder: refreshes the contents of a folder (the list of message headers).
• noop: an empty mail operation

Mail operation queue

The queue keeps information of all mail operations running, and also allows to know if there are no operations running (see shutdown process in ModestRuntime section).

It emits these signals:

• queue_changed: notifies if mail operations have been added or removed
• queue_empty: notifies all operations have finished.

Other methods:

• num_elements: allows to get the number of operations currently in queue.
• cancel: cancels a mail operation and removes it from queue.
• cancel_all: cancels all unfinished mail operations.
• get_by_source: obtains all operations of a source.
• queue_to_string: represents the status of the queue as a string (for debugging).
• set_running_shutdown, running_shutdown: sets/tell if operation queue is running the final shutdown mail operation.