X-Git-Url: http://git.maemo.org/git/?a=blobdiff_plain;f=docs%2Freference%2Fmodest-docs.sgml;h=158c68f3d926b1fb7ae8c008b62f39ab7e6d03be;hb=84adff2f6752b9215566a2fc9e6660123e995960;hp=b53344e74049773978bceb1462410884c9217733;hpb=0736dc934551904c45f5169f51b3b9a6271678c9;p=modest diff --git a/docs/reference/modest-docs.sgml b/docs/reference/modest-docs.sgml index b53344e..158c68f 100644 --- a/docs/reference/modest-docs.sgml +++ b/docs/reference/modest-docs.sgml @@ -1,312 +1,133 @@ - - - modest reference manual - + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ - - Introduction + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - modest is a mail user agent - (MUA) targetting small devices, in particular Nokia's - Nokia 770 Internet Tablet. This document - describes the design and implementation of this software. - - - modest lives at the top of a extensive - stack of software. It is built on top - of tinymail, and uses its libcamel - backend. It strives to the be a simple yet powerful program, geared - towards small devices, for example (but not limited - to) Nokia's 770 internet tablet. An important - goal is to minimize memory usage while still being able to handle - significant amounts of email quickly; much of that is achieved simply by - using tinymail, which uses a number of clever - tricks for that, such as the proxy design pattern for listing email - headers, and not needing memory for headers which are not currently - visible. - - - - modest, in turn, also tries to be efficient, - fast and scalable. That means that the MUA should - support multiple user-interfaces, perhaps making it even possible to - switch between them during runtime. - - - To summarize the goals for modest: - - target devices with limited amounts of memory ('limited' in 2006 - terms means less than 64Mb, and of which only part can be used for - e-mail); - target Linux/Unix-like environments with GLib/GTK+-based - support; - support multiple user-interface (UIs) with as much code - sharing as possible between the different UIs. - - - Like tinymail - and libcamel, modest - is programmed in C, using the GObject-system for - object-oriented (OO) features. For now, it specifically targets \gtk based - UIs (and derivatives like 'Hildon'). + - + + + + - - Architecture - - modest tries to be quite flexible in its - design. However, it's always important not to make things too - generic. Both for reasons of time limitations and keeping the software - understandable and 'modest', it's important to limit the scope. - - - - For modest, the following: - - modest is a e-mail program - using the tinymail and camel - libraries; - modest targets gtk and - gconf-based user-interfaces, including the Hildon - environment; - modest main use-case is in - small, mobile device such as the Nokia 770 Internet - Tablet; - However, effort is made also to - make modest usable as a general-purpose - e-mail client on normal desktop computer. - - - - - - - Design - - In this part, we'll discuss the design of various parts of - modest. We'll not go into the details of - various APIs in this chapter. Please consul the documentation generated - from the source code (gtk-doc) for that. - - - - Configuration - Configuration is the part of modest - that deals with storing all settings. While the design allows for - alternative implementations, currently - only GConf is supported as a backend. - - - - All dealing with configuration is done with - the ModestConf-class. It is declared - in modest-conf.h, and - the GConf-based implementation in - modest-conf-gconf.c. As said, there could be - different implementations -- - nothing GConf-specific is visible in the - ModestConf-API. - - - - - Account Management - - Account Management is the part of modest - that deals with the setting related to sending and receiving of - e-mail. We will follow the libcamel-convention of using the - term store for an e-mail storage/retrieval - server, and a transport for a server that - transports mail to its destination. - - - - In practice, the following types are available: - - stores: POP - and IMAP; - transports: sendmail - and SMTP. - - - - - Definitions - - An account is a named entity - consisting of a store and - a transport. Note: For our mobile use-cases, - the transport cannot be a static entity, but - may depend on the network connection. That is however not part of - Account Management, so not discussed here - A server account is account - describing the connection with a specific server. Server accounts - come in two type: - - A transport describes the connection information - (servername, username, password etc.) for a transport - server; - A store describes the connection information for - a store server; - - - - - - - Code - The functions to deal with account and server accounts are - located in ModestAccountMgr, ie. in - modest-account-mgr.[ch]. There function to add - specific values for both, to list the available ones, etc. Please - refer to the source code documentation for details. - - - - - Location in configuration database - - Accounts can be found - in /apps/modest/accounts, - while server accounts can be found - in /app/modest/server_accounts. - - - - The following image show an - account accountstest with server accounts - mystore - and mytransport. - - +]> - - For each of the stores, there are number of parameters specified: - - hostname - the place where the server resides; - username - the username; - password - the password; - proto - the protocal for communication with this server - for - now these are the following valid values (literal strings): - - sendmail; - smtp; - pop - imap. - - - - - - In the modest-proto.[ch] there are - various functions to check whether something is a valid protocol, and whether - it is a transport of a store. - - - Note that server accounts and accounts are relatively independent. While - accounts refer to two server accounts, these server accounts can be - used by other accounts as well. - - - The reason two keep accounts and server accounts separately, is a bit of - flexibility. In mobile use-cases, quite often it's desirable to use a - network-specific smtp-server. The chosen structure makes it easy to iterate - over all smtp-servers and find the right one. - - - + + + modest technical documentation + + 2006, 2007 + Nokia Corporation + + - - Finding the right transport - - One of the interesting topics in designing a mobile e-mail client is - to deal with transports (in - particular, SMTP). The reason for that is that - the majority of SMTP-servers only allow e-mail - from the same network. That means that for example - smtp.some-isp.com will only accept mail from - (MAIL FROM:) - user@some-isp.com, and refuse mail - from user@some-other-isp.com, unless the - recipient (RCPT TO:) is on the same network. - - - - - - Coding guidelines - - When hacking on \modest, please honour these time-tested coding guidelines. - First, please follow the Linux CodingStyle guidelines - (/usr/src/linux/Documentation/CodingStyle). - - - - Here are only some additional notes. - + &preface; - - Your editor may help you with this, for example for emacs: - - (c-set-style "K&R") - (setq tab-width 8) - (setq indent-tabs-mode t) - (setq c-basic-offset 8) - - - - - Or the equivalent in your favourite editor. - - - - Lines should not exceed 100 characters. - - - Global functions (the ones in .h-files) should - be commented using - gtk-doc. - - - - Furthermore, please follow 'conventional wisdom' for programming with - GLib/GTK+/GObject. Some things to remember: - - g_new, g_malloc and - friends never return NULL. They terminate - the application if it happens (normally). No need to check - for NULL returns; - g_return_if_fail and friends may be - 'turned off', ie. they are to be used for error checking, - but not for your programming logic - - - - + &architecture; - + &design; + + &coding-guidelines; + + + API Reference - - - - - - - - - - - - - - - + + + Core/Runtime + &ModestRuntime; + &ModestSingletons; + + + + + + Mail + &ModestTnyMsg; + &ModestTnyFolder; + &ModestTnySendQueue; + &ModestTnyAccountStore; + + &ModestMailOperationQueue; + + + + + Widgets + &ModestAccountView; + &ModestAccountViewWindow; + &ModestComboBox; + &ModestFolderView; + &ModestHeaderView; + &ModestMainWindow; + &ModestMsgView; + &ModestMsgViewWindow; + &ModestMsgEditWindow; + &ModestWindow; + + + + Account Management and Settings + &ModestAccountMgr; + &ModestAccountMgrHelpers; + &ModestConf; + &ModestWidgetMemory; + + + + Other + &ModestCacheMgr; + &ModestError; + &ModestIconNames; + &ModestPair; + &ModestProtocolInfo; + &ModestLocalFolderInfo; + &ModestTextUtils; + + + + + + + Index + +