<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-<!ENTITY ModestAccountKeys SYSTEM "xml/modest-account-keys.xml">
+<!ENTITY ModestAccountMgrHelpers SYSTEM "xml/modest-account-mgr-helpers.xml">
<!ENTITY ModestAccountMgr SYSTEM "xml/modest-account-mgr.xml">
-<!ENTITY ModestConfKeys SYSTEM "xml/modest-conf-keys.xml">
+<!ENTITY ModestAccountViewWindow SYSTEM "xml/modest-account-view-window.xml">
+<!ENTITY ModestAccountView SYSTEM "xml/modest-account-view.xml">
+<!ENTITY ModestCacheMgr SYSTEM "xml/modest-cache-mgr.xml">
+<!ENTITY ModestComboBox SYSTEM "xml/modest-combo-box.xml">
<!ENTITY ModestConf SYSTEM "xml/modest-conf.xml">
<!ENTITY ModestError SYSTEM "xml/modest-error.xml">
-<!ENTITY ModestFormatter SYSTEM "xml/modest-formatter.xml">
-<!ENTITY ModestIconFactory SYSTEM "xml/modest-icon-factory.xml">
+<!ENTITY ModestFolderView SYSTEM "xml/modest-folder-view.xml">
+<!ENTITY ModestHeaderView SYSTEM "xml/modest-header-view.xml">
<!ENTITY ModestIconNames SYSTEM "xml/modest-icon-names.xml">
-<!ENTITY ModestMailOperation SYSTEM "xml/modest-mail-operation.xml">
+<!ENTITY ModestLocalFolderInfo SYSTEM "xml/modest-local-folder-info.xml">
<!ENTITY ModestMailOperationQueue SYSTEM "xml/modest-mail-operation-queue.xml">
-<!ENTITY ModestMarshal SYSTEM "xml/modest-marshal.xml">
+<!ENTITY ModestMailOperations SYSTEM "xml/modest-mail-operation.xml">
+<!ENTITY ModestMainWindow SYSTEM "xml/modest-main-window.xml">
+<!ENTITY ModestMsgEditWindow SYSTEM "xml/modest-msg-edit-window.xml">
+<!ENTITY ModestMsgViewWindow SYSTEM "xml/modest-msg-view-window.xml">
+<!ENTITY ModestMsgView SYSTEM "xml/modest-msg-view.xml">
<!ENTITY ModestPair SYSTEM "xml/modest-pair.xml">
-<!ENTITY ModestPresets SYSTEM "xml/modest-presets.xml">
-<!ENTITY ModestProtocolMgr SYSTEM "xml/modest-protocol-mgr.xml">
-<!ENTITY ModestProto SYSTEM "xml/modest-proto.xml">
+<!ENTITY ModestProtocolInfo SYSTEM "xml/modest-protocol-info.xml">
+<!ENTITY ModestRuntime SYSTEM "xml/modest-runtime.xml">
+<!ENTITY ModestSingletons SYSTEM "xml/modest-singletons.xml">
<!ENTITY ModestTextUtils SYSTEM "xml/modest-text-utils.xml">
<!ENTITY ModestTnyAccountStore SYSTEM "xml/modest-tny-account-store.xml">
-<!ENTITY ModestTnyAttachment SYSTEM "xml/modest-tny-attachment.xml">
-<!ENTITY ModestTnyMsgActions SYSTEM "xml/modest-tny-msg-actions.xml">
+<!ENTITY ModestTnyAccount SYSTEM "xml/modest-tny-account.xml">
+<!ENTITY ModestTnyFolder SYSTEM "xml/modest-tny-folder.xml">
+<!ENTITY ModestTnyMsg SYSTEM "xml/modest-tny-msg.xml">
<!ENTITY ModestTnyPlatformFactory SYSTEM "xml/modest-tny-platform-factory.xml">
-<!ENTITY ModestTnyStoreActions SYSTEM "xml/modest-tny-store-actions.xml">
-<!ENTITY ModestTnyStreamGtkhtml SYSTEM "xml/modest-tny-stream-gtkhtml.xml">
-<!ENTITY ModestWidgetFactory SYSTEM "xml/modest-widget-factory.xml">
+<!ENTITY ModestTnySendQueue SYSTEM "xml/modest-tny-send-queue.xml">
+<!ENTITY ModestTnyStreamGtkHtml SYSTEM "xml/modest-tny-stream-gtkhtml.xml">
+<!ENTITY ModestUIActions SYSTEM "xml/modest-ui-actions.xml">
<!ENTITY ModestWidgetMemory SYSTEM "xml/modest-widget-memory.xml">
+<!ENTITY ModestWindow SYSTEM "xml/modest-window.xml">
-<!ENTITY widgets-ModestAccountView SYSTEM "xml/modest-account-view.xml">
-<!ENTITY widgets-ModestComboBox SYSTEM "xml/modest-combo-box.xml">
-<!ENTITY widgets-ModestFolderView SYSTEM "xml/modest-folder-view.xml">
-<!ENTITY widgets-ModestHeaderView SYSTEM "xml/modest-header-view.xml">
-<!ENTITY widgets-ModestMsgView SYSTEM "xml/modest-msg-view.xml">
-<!ENTITY widgets-modestToolbar SYSTEM "xml/modest-toolbar.xml">
+<!-- <!ENTITY index-Object-Tree SYSTEM "xml/tree_index.sgml"> -->
-<!ENTITY gtk-ModestAccountViewWindow SYSTEM "xml/modest-account-view-window.xml">
-<!ENTITY gtk-ModestAccountAssistant SYSTEM "xml/modest-account-assistant.xml">
-<!ENTITY gtk-ModestEditMsgWindow SYSTEM "xml/modest-edit-msg-window.xml">
-<!ENTITY gtk-ModestMainWindow SYSTEM "xml/modest-main-window.xml">
-<!ENTITY gtk-ModestStoreWidget SYSTEM "xml/modest-store-widget.xml">
-<!ENTITY gtk-modestTransportWidget SYSTEM "xml/modest-transport-widget.xml">
-<!ENTITY gtk-modestUi SYSTEM "xml/modest-ui.xml">
-
-<!ENTITY index-Object-Tree SYSTEM "xml/tree_index.sgml">
+<!ENTITY preface SYSTEM "modest-preface.sgml">
+<!ENTITY architecture SYSTEM "modest-architecture.sgml">
+<!ENTITY design SYSTEM "modest-design.sgml">
+<!ENTITY coding-guidelines SYSTEM "modest-coding-guidelines.sgml">
]>
<bookinfo>
<title>modest technical documentation</title>
<copyright>
- <year>2006</year>
+ <year>2006, 2007</year>
<holder>Nokia Corporation</holder>
</copyright>
</bookinfo>
- <preface>
- <title>Introduction</title>
- <para><application>modest</application> is a mail user agent
- (<abbrev>MUA</abbrev>) targetting small devices, in particular Nokia's
- <productname>Nokia 770 Internet Tablet</productname>. This document
- describes the design and implementation of this software.
- </para>
-
- <para><application>modest</application> lives at the top of a extensive
- stack of software. It is built on top
- of <application>tinymail</application>, 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) <productname>Nokia's 770 internet tablet</productname>. 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 <application>tinymail</application>, 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.
- </para>
-
- <para>
- <application>modest</application>, in turn, also tries to be efficient,
- fast and scalable. That means that the <abbrev>MUA</abbrev> should
- support multiple user-interfaces, perhaps making it even possible to
- switch between them during runtime.
- </para>
-
- <para>To summarize the goals for <application>modest</application>:
- <itemizedlist>
- <listitem>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);</listitem>
- <listitem>target Linux/Unix-like environments with GLib/GTK+-based
- support;</listitem>
- <listitem>support multiple user-interface (UIs) with as much code
- sharing as possible between the different UIs.</listitem>
- </itemizedlist></para>
-
- <para>Like <application>tinymail</application>
- and <application>libcamel</application>, <application>modest</application>
- is programmed in C, using the <package>GObject</package>-system for
- object-oriented (OO) features. For now, it specifically targets \gtk based
- UIs (and derivatives like 'Hildon').</para>
-
- </preface>
+ &preface;
- <part>
- <title>Architecture</title>
- <partintro>
- <para><application>modest</application> 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.
- </para>
-
- <para>
- For <application>modest</application>, the following:
- <itemizedlist>
- <listitem><application>modest</application> is a e-mail program
- using the <package>tinymail</package> and <package>camel</package>
- libraries;</listitem>
- <listitem><application>modest</application> targets gtk and
- gconf-based user-interfaces, including the Hildon
- environment;</listitem>
- <listitem><application>modest</application> main use-case is in
- small, mobile device such as the <productname>Nokia 770 Internet
- Tablet</productname>;</listitem>
- <listitem>However, effort is made also to
- make <application>modest</application> usable as a general-purpose
- e-mail client on normal desktop computer.</listitem>
- </itemizedlist>
- </para>
- </partintro>
- </part>
+ &architecture;
- <part>
- <title>Design</title>
- <partintro>
- <para>In this part, we'll discuss the design of various parts of
- <application>modest</application>. We'll not go into the details of
- various APIs in this chapter. Please consult the documentation generated
- from the source code (<systemitem>gtk-doc</systemitem>) for that.
- </para>
- </partintro>
-
- <chapter>
- <title>Configuration</title>
- <para>Configuration is the part of <application>modest</application>
- that deals with storing all settings. While the design allows for
- alternative implementations, currently
- only <systemitem>GConf</systemitem> is supported as a backend.
- </para>
-
- <para>
- All dealing with configuration is done with
- the <classname>ModestConf</classname>-class. It is declared
- in <filename> modest-conf.h</filename>, and
- the <systemitem>GConf</systemitem>-based implementation in
- <filename>modest-conf.c</filename>. As said, there could be
- different implementations --
- nothing <systemitem>GConf</systemitem>-specific is visible in the
- <classname>ModestConf</classname>-<abbrev>API</abbrev>.
- </para>
- </chapter>
-
- <chapter>
- <title>Account Management</title>
- <para>
- Account Management is the part of <application>modest</application>
- that deals with the setting related to sending and receiving of
- e-mail. We will follow the libcamel-convention of using the
- term <emphasis>store</emphasis> for an e-mail storage/retrieval
- server, and a <emphasis>transport</emphasis> for a server that
- transports mail to its destination.
- </para>
-
- <para>
- In practice, the following types are available:
- <itemizedlist>
- <listitem><emphasis>stores</emphasis>: <abbrev>POP</abbrev>
- and <abbrev>IMAP</abbrev>; </listitem>
- <listitem> <emphasis>transports</emphasis>: <systemitem>sendmail</systemitem>
- and <abbrev>SMTP</abbrev>.</listitem>
- </itemizedlist>
- </para>
-
- <sect1>
- <title>Definitions</title>
- <itemizedlist>
- <listitem>An <emphasis>account</emphasis> is a named entity
- consisting of a <emphasis>store</emphasis> and
- a <emphasis>transport</emphasis>. Note: For our mobile use-cases,
- the <emphasis>transport</emphasis> cannot be a static entity, but
- may depend on the network connection. That is however not part of
- Account Management, so not discussed here</listitem>
- <listitem>A <emphasis>server account</emphasis> is account
- describing the connection with a specific server. Server accounts
- come in two type:
- <itemizedlist>
- <listitem>A <emphasis>transport</emphasis> describes the connection information
- (servername, username, password etc.) for a transport
- server;</listitem>
- <listitem>A <emphasis>store</emphasis> describes the connection information for
- a store server;</listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1>
- <title>Code</title>
- <para>The functions to deal with account and server accounts are
- located in <classname>ModestAccountMgr</classname>, ie. in
- <filename>modest-account-mgr.[ch]</filename>. There function to add
- specific values for both, to list the available ones, etc. Please
- refer to the source code documentation for details.
- </para>
- </sect1>
-
- <sect1>
- <title>Location in configuration database</title>
- <para>
- <emphasis>Accounts</emphasis> can be found
- in <systemitem>/apps/modest/accounts</systemitem>,
- while <emphasis>server accounts</emphasis> can be found
- in <systemitem>/app/modest/server_accounts</systemitem>.
- </para>
-
- <para>
- The following image show an
- account <systemitem>accountstest</systemitem> with server accounts
- <systemitem>mystore</systemitem>
- and <systemitem>mytransport</systemitem>.
- <imagedata fileref="modest-account-mgr.png"/>
- </para>
-
- <para>
- For each of the stores, there are number of parameters specified:
- <itemizedlist>
- <listitem><emphasis>hostname</emphasis> - the place where the server resides;</listitem>
- <listitem><emphasis>username</emphasis> - the username;</listitem>
- <listitem><emphasis>password</emphasis> - the password;</listitem>
- <listitem><emphasis>proto</emphasis> - the protocal for communication with this server - for
- now these are the following valid values (literal strings):
- <itemizedlist>
- <listitem><emphasis>sendmail</emphasis>;</listitem>
- <listitem><emphasis>smtp</emphasis>;</listitem>
- <listitem><emphasis>pop</emphasis></listitem>
- <listitem><emphasis>imap</emphasis>.</listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>In <filename>modest-proto.[ch]</filename> there are various
- functions to check whether something is a valid protocol, and
- whether it is a transport of a store.
- </para>
-
- <para>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.
- </para>
-
- <para>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.
- </para>
- </sect1>
-
- <sect1>
- <title>Account Management and Tinymail</title>
- <para>
- Tinymail needs the information about all configured accounts - and the
- mechanism that it uses for that
- is <interface>TnyAccountStoreIface</interface>. We don't want to use
- the tinymail-provided <classname>TnyAccountStore</classname>, but
- provide our own implementation
- instead: <classname>ModestTnyAccountStore</classname>. This class
- implements the <interface>TnyAccountStoreIface</interface>-interace in
- terms of the aforementioned <classname>ModestAccountMgr</classname>.
- </para>
-
- <para>
- One unexpected function
- that <classname>ModestTnyAccountStore</classname> needs to implement
- is <symbol>tny account_store get_session</symbol> (to get the
- Camel-session). This function must be provided as a public function,
- with that exact name.
- </para>
- </sect1>
- </chapter>
-
- <chapter>
- <title>Finding the right transport</title>
- <para>
- One of the interesting topics in designing a mobile e-mail client is
- to deal with transports (in
- particular, <acronym>SMTP</acronym>). The reason for that is that
- the majority of <acronym>SMTP</acronym>-servers only allow e-mail
- from the same network. That means that for example <systemitem>
- smtp.some-isp.com</systemitem> will only accept mail from
- (<command>MAIL FROM:</command>) <systemitem>
- user@some-isp.com</systemitem>, and refuse mail
- from <systemitem>user@some-other-isp.com</systemitem>, unless the
- recipient (<command>RCPT TO:</command>) is on the same network.
- </para>
- </chapter>
- </part>
+ &design;
- <chapter>
- <title>Coding guidelines</title>
- <para>
- When hacking on modest, please honour these time-tested coding guidelines.
- First, please follow the <emphasis>Linux CodingStyle guidelines</emphasis>
- (<filename>/usr/src/linux/Documentation/CodingStyle</filename>).
- </para>
-
- <para>
- Here are only some additional notes.
- </para>
-
- <para>
- Your editor may help you with this, for example for <application>emacs</application>:
- <programlisting>
- (c-set-style "K&R")
- (setq tab-width 8)
- (setq indent-tabs-mode t)
- (setq c-basic-offset 8)
- </programlisting>
-
- Or the equivalent in your favourite editor.
- </para>
-
- <para>
- Lines must not exceed 100 characters.
- </para>
-
- <para>
- Functions should do one thing, and do it well. In general, functions
- should not be much longer than 20-30 lines (except for, say, handling
- many different cases in a 'switch'-statement). Files should not get to
- big either; if there are more than, say, 800 lines, it's a sign that
- some refactoring should take place.
- </para>
-
- <para>
- Code should compile cleanly
- with <command>gcc</command>'s <symbol>-Wall</symbol> compile option. Of
- course this might not always be possible due to problems in dependent
- libraries and/or compiler version. Therefore, do not
- include <symbol>-Werror</symbol> in the standard compile options; but
- do use it when building / testing things yourself.
- </para>
-
- <para>
- Code should also run cleanly. GTK+/GLib warnings and errors must be
- taken very seriously. If you run <application>modest</application> with
- the <symbol>-d</symbol>-flag, it will <symbol>abort</symbol> whenever
- there is such a warning. This can be useful when running inside the
- debugger.
- </para>
-
- <para>Global functions (the ones in <filename>.h</filename>-files) must
- be commented using <systemitem>gtk-doc</systemitem>. This way, we
- generate nice documentation. After installing
- (under <filename>/usr/local</filename>), we can browse the results
- with <application>DevHelp</application>. Just
- add <systemitem>/usr/local/share/gtk-doc/html</systemitem> to the
- <systemitem>DEVHELP_SEARCH_PATH</systemitem>-environment variable.
- </para>
- <para>
- Furthermore, please follow 'conventional wisdom' for programming with
- GLib/GTK+/GObject. Some things to remember:
- <itemizedlist>
- <listitem> <function>g_new</function>, <function>g_malloc</function> and
- friends <emphasis>never</emphasis> return <function>NULL</function>. They terminate
- the application if it happens (normally). No need to check
- for <function>NULL</function> returns;</listitem>
- <listitem> <function>g_return_if_fail</function> and friends may be
- 'turned off', ie. they are to be used for error checking,
- but <emphasis>not</emphasis> for your programming logic
- </listitem>
- </itemizedlist>
- </para>
- </chapter>
+ &coding-guidelines;
+<!--
<reference>
<title>Object Index</title>
&index-Object-Tree;
</reference>
-
+-->
<reference>
<title>API Reference</title>
- <chapter id="src">
- <title>Modest</title>
- &ModestAccountKeys;
- &ModestAccountMgr;
- &ModestConfKeys;
- &ModestConf;
- &ModestError;
- &ModestFormatter;
- &ModestIconFactory;
- &ModestIconNames;
- &ModestMailOperation;
- &ModestMailOperationQueue;
- &ModestMarshal;
- &ModestPair;
- &ModestPresets;
- &ModestProtocolMgr;
- &ModestProto;
- &ModestTextUtils;
- &ModestTnyAccountStore;
- &ModestTnyAttachment;
- &ModestTnyMsgActions;
- &ModestTnyPlatformFactory;
- &ModestTnyStoreActions;
- &ModestTnyStreamGtkhtml;
- &ModestWidgetFactory;
- &ModestWidgetMemory;
+
+ <chapter id="core">
+ <title>Core/Runtime</title>
+ &ModestRuntime;
+ &ModestSingletons;
+<!-- &ModestPlatform; -->
+<!-- &ModestInit; -->
</chapter>
- <chapter id="gtk">
- <title>Gtk</title>
- >k-ModestAccountViewWindow;
- >k-ModestAccountAssistant;
- >k-ModestEditMsgWindow;
- >k-ModestMainWindow;
- >k-ModestStoreWidget;
- >k-modestTransportWidget;
- >k-modestUi;
+
+ <chapter id="mail">
+ <title>Mail</title>
+ &ModestTnyMsg;
+ &ModestTnyFolder;
+ &ModestTnySendQueue;
+ &ModestTnyAccountStore;
+<!-- &ModestMailOperation; -->
+ &ModestMailOperationQueue;
</chapter>
+
+
<chapter id="widgets">
<title>Widgets</title>
- &widgets-ModestAccountView;
- &widgets-ModestComboBox;
- &widgets-ModestFolderView;
- &widgets-ModestHeaderView;
- &widgets-ModestMsgView;
- &widgets-modestToolbar;
+ &ModestAccountView;
+ &ModestAccountViewWindow;
+ &ModestComboBox;
+ &ModestFolderView;
+ &ModestHeaderView;
+ &ModestMainWindow;
+ &ModestMsgView;
+ &ModestMsgViewWindow;
+ &ModestMsgEditWindow;
+ &ModestWindow;
</chapter>
+
+ <chapter id="accmgmt_settings">
+ <title>Account Management and Settings</title>
+ &ModestAccountMgr;
+ &ModestAccountMgrHelpers;
+ &ModestConf;
+ &ModestWidgetMemory;
+ </chapter>
+
+ <chapter id="other">
+ <title>Other</title>
+ &ModestCacheMgr;
+ &ModestError;
+ &ModestIconNames;
+ &ModestPair;
+ &ModestProtocolInfo;
+ &ModestLocalFolderInfo;
+ &ModestTextUtils;
+ </chapter>
+
</reference>