Modest Account Management And Extensible Protocols

Account management and extensible protocols

Introduction

In Tinymail we handle two types of "server accounts", that are important in !Modest:

• Store accounts: represent storages of messages. !Modest uses !Tinymail implementations for !IMAP, !POP, and !Maildir storage. The storages keep references to the folders where messages are stored.
• Transport accounts: represent a service that can be used to send mails to the world. !Modest uses !SMTP implementation available in !Tinymail.

But, over this, !Modest has also the concept of ModestAccount. A ModestAccount is:

• One store account.
• One transport account.
• A name of the account, the name and email of the user for that account, a signature for sending mails...

So, important difference:

• Modest server account: one store or transport account.
• Modest account: the "user account concept": one store, one transport, and some settings.

Modest provides an extensible and persistent account protocol registration system. The main components of this are:

• ModestConf: utility methods to retrieve and store settings information. It uses GConf as storage.
• ModestAccountMgr: the account manager handles the representation of the available accounts in ModestConf?. It also provides notifications of the status changes. The storage of !Modest accounts and server accounts is here.
• ModestTnyAccountStore: the representation as Tinymail objects of the accounts available. It observes the ModestAccountMgr and updates the account objects depending on this.
• ModestAccountSettings: it's a representation of one account settings in memory (the same information you will expect in account manager for a ModestAccount.
• ModestServerAccountSettings: representation of one server account in memory (transport or store) as one object.
• ModestProtocol and ModestAccountProtocol: they represent a protocol, with its name, its id, some translation strings specific to the method, ports it should use, etc. The protocol id's are used in account manager, account store and the account settings.
• ModestProtocolRegistry: a dynamic registry where the protocols are stored and tagged. With the tags, its said the kind of protocol (store, transport, security, etc), and some specific properties (if it's an store and allows subfolders, etc).

Using ModestPlugin architecture, !Modest can load external plugins that register new protocols into the ModestProtocolRegistry. This way, support for new protocols can be added into !Modest UI.

ModestConf and ModestAccountMgr

ModestConf is a wrapper of Gconf in !Modest. We use Gconf registry for storage of settings, in the path /apps/modest. The name of the used keys in gconf is available in modest-defs.h.

In ModestConf we store all the account settings, but also general settings. It also provides a notication system to track changes on it.

ModestAccountMgr is just a wrapper to ModestConf to store and retrieve the specific accounts and server account settings.

The methods for account manager are spread in modest-account-mgr.h and modest-account-mgr-helpers.h.

ModestTnyAccountStore

The account store is the storage of accounts at Tinymail level. It listens to Account Manager, and keeps Tinymail representation of:

• Store accounts
• Local store, and MMC store.
• Transport accounts
• Specific network SMTP transport accounts

Important methods:

• get_tny_account_by and get_server_account: methods to obtain references to TnyAccount instances inside.
• get_transport_account_for_open_connection: obtains the transport account to use for a modest account. If the account is configured to use specific network smtp services, then it offers a decorated transport account that uses those on sending mails.
• get_session: obtains the TnySessionCamel object. This is used, among other things, to track network status.
• get_local_folders_account: obtain the account for local storage in device.
• get_mmc_folders_account: obtains the account pointing to the mmc storage.
• forget_already_asked and get_password: methods !Modest attaches to Tinymail, for handling password dialogs.
• shutdown: method that shut down all accounts asynchronously. It's used in the finish process.

ModestAccountSettings and dialogs

Creation process

The process of creating a new account is:

• Wizard is shown for that account type. The wizard is a simplified version of the whole settings available of the accounts. This is pure UI.
• Once user finishes wizard and taps on save, then a ModestAccountSettings? object is created with the account and server accounts settings.
• This ModestAccountSettings is stored to ModestAccountMgr.
• ModestAccountMgr notifies the changes to ModestTnyAccountStore, and the new account is created.

On finishing the wizard, if you tap on advanced settings, what will happen is that a ModestAccountSettings is created and passed to the ModestAccountSettingsDialog. Once user saves the changes to that account settings dialog, it will be passed again to the wizard.

Relationship with manager

• modest_account_mgr_add_account_from_settings: creates a new account using account settings object.
• modest_account_mgr_check_already_configured_account: checks if these settings are already in account manger.
• modest_account_mgr_load_account_settings: loads the settings in account manager into a ModestAccountSettings object.

There are other methods detailing the implementation of this, and how the server accounts are also stored to account manager.

In general the idea is avoiding direct access to account manager to save or load accounts, and use if possible the account settings and server account settings objects.

ModestProtocol and ModestProtocolRegistry

ModestProtocol

A name and display name for a protocol. ModestProtocol itself is not much more than this. It acquires all its meaning once it's registered in the protocol registry, with the proper tags.

Methods:

• modest_protocol_new (const gchar *name, const gchar *display_name): the display name is the name that !Modest will show in parts of UI where the protocol is shown. The name should be unique. An example: name=pop, display name=POP3. The name, in account protocols, is used for forming the URIs.
• modest_protocol_get_type_id: on instantiating each protocol, it gets a type_id (type ModestProtocolType). This is also a unique identifier (internally a guint).
• modest_protocol_get and modest_protocol_set: used to store arbitrary information of that protocol as name/values sets.
• modest_protocol_set_translation, modest_protocol_get_translation and modest_protocol_va_get_translation: these methods are used to set and retrieve translations for strings of the protocol. It's used then, as a way to retrieve specific (translated) strings in UI.

ModestAccountProtocol

An account protocol is a protocol for a server account. It's main use is specifying how this is configured and shown in UI, but also adds extensibility points for plugins. !Modest registers by default account protocols for IMAP, POP and SMTP.

An account protocol also has:

• port: the port that this protocol uses.
• alternate_port: the alternate port (usually the port used for using this protocol with SSL).
• account_g_type: the GType register id of the TnyAccount class this account protocol represents.

Extension points/redefinible methods:

• create_account: creates the proper TnyAccount instance
• create_account_settings_dialog: returns a ModestAccountSettingsDialog for this kind of account.
• get_easysetup_wizard_tabs: returns the tabs to be added to the account wizard for this account protocol.
• get_wizard_response_override: set a method to override the response handler in wizard. This is used to control from account protocol with more detail the flow among the tabs.
• save_settings: method that gets an account settings dialog, and saves properly the settings to storage.
• save_wizard_settings: method that gets the information from wizard and saves properly the new account to storage.
• wizard_finished:
• check_support: asynchronous method to check if this protocol is supported/available.
• is_supported: synchronous method telling if this protocol is supported. It should cache the result of check_support.
• cancel_check_support: stop check support call.
• save_remote_draft: allows to handle properly saving the drafts to a remote storage.
• handle_calendar: add specific UI for this account calendar. It's used for servers that have calendar handling, to allow to show proper UI to user.

Special methods for multimailbox accounts:

• get_from: obtains the From: string (name to add to email address) for an account and mailbox.
• get_from_list: obtains the list of From: strings available for this account. Returns a list of pairs (mailbox, from string).
• get_signature: obtains the signature for an account and mailbox.

Special methods for branding:

• get_icon: obtains a specific icon for this protocol. I.e. it allows to set a different icon for this protocols' folders.
• get_service_name and get_service_icon: allows to show a service name and icon for an account. I.e. showing Gmail icon and name in the message view for mails stored in Gmail.

Special methods for streaming from account:

• decode_part_to_stream and decode_part_to_stream_async: allows to get the contents of a specific part in server as a stream.

ModestProtocolRegistry

The protocol registry is a singleton registry where all the protocols used in !Modest should be stored. Each protocol is stored with a set of tags.

Tags available:

• MODEST_PROTOCOL_REGISTRY_CONNECTION_PROTOCOLS. Connection protocols (i.e. none, ssl, tls).
• MODEST_PROTOCOL_REGISTRY_AUTH_PROTOCOLS. Authentication protocols (i.e. none, cram-mdt, ...)
• MODEST_PROTOCOL_REGISTRY_TRANSPORT_STORE_PROTOCOLS. Protocols that are transport or store (and then, server account protocol).
• MODEST_PROTOCOL_REGISTRY_STORE_PROTOCOLS. Store protocols (i.e. pop, imap, maildir).
• MODEST_PROTOCOL_REGISTRY_TRANSPORT_PROTOCOLS. Transport protocols (i.e. smtp).
• MODEST_PROTOCOL_REGISTRY_LOCAL_STORE_PROTOCOLS. Local store protocols (i.e. maildir).
• MODEST_PROTOCOL_REGISTRY_REMOTE_STORE_PROTOCOLS. Remote store protocols (i.e. imap, pop).
• MODEST_PROTOCOL_REGISTRY_SECURE_PROTOCOLS. Protocols that are considered "secure". I.e. ssl, cram-md5.
• MODEST_PROTOCOL_REGISTRY_HAS_LEAVE_ON_SERVER_PROTOCOLS. Store protocols that should show option "leave on server". I.e. pop.
• MODEST_PROTOCOL_REGISTRY_PROVIDER_PROTOCOLS. External provider protocols. I.e. Nokia Messagging.
• MODEST_PROTOCOL_REGISTRY_SINGLETON_PROVIDER_PROTOCOLS. External provider protocols that only allow one instance (i.e. activesync, Nokia Messaging).
• MODEST_PROTOCOL_REGISTRY_MULTI_MAILBOX_PROVIDER_PROTOCOLS. External provider protocols with multimailbox support (i.e. Nokia Messaging).
• MODEST_PROTOCOL_REGISTRY_USE_ALTERNATE_PORT. Security protocols that should use alternate port.
• MODEST_PROTOCOL_REGISTRY_STORE_HAS_FOLDERS. Storage that can have subfolders.
• MODEST_PROTOCOL_REGISTRY_STORE_FORBID_INCOMING_XFERS. Accounts that cannot be the destination of messages or folders transfers
• MODEST_PROTOCOL_REGISTRY_STORE_FORBID_OUTGOING_XFERS. Accounts that do not allow to move messages or folders from
• MODEST_PROTOCOL_REGISTRY_NO_AUTO_UPDATE_PROTOCOLS. Accounts that handle update on their own (and then !Modest don't have to handle their update times).

ModestPlugin and ModestPluginFactory

A developer can implement plugins, loadable binaries that extend !Modest (mainly using the protocol registry).

The important thing is creating a ModestModule object with the method register_module_plugin.

In !Modest plugins are loaded on startup, and never unloaded.