2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
8 <holder>Nokia Corporation</holder>
12 <title>modest technical documentation</title>
16 <title>Introduction</title>
17 <para><application>modest</application> is a mail user agent
18 (<abbrev>MUA</abbrev>) targetting small devices, in particular Nokia's
19 <productname>Nokia 770 Internet Tablet</productname>. This document
20 describes the design and implementation of this software.
23 <para><application>modest</application> lives at the top of a extensive
24 stack of software. It is built on top
25 of <application>tinymail</application>, and uses its libcamel
26 backend. It strives to the be a simple yet powerful program, geared
27 towards small devices, for example (but not limited
28 to) <productname>Nokia's 770 internet tablet</productname>. An important
29 goal is to minimize memory usage while still being able to handle
30 significant amounts of email quickly; much of that is achieved simply by
31 using <application>tinymail</application>, which uses a number of clever
32 tricks for that, such as the proxy design pattern for listing email
33 headers, and not needing memory for headers which are not currently
38 <application>modest</application>, in turn, also tries to be efficient,
39 fast and scalable. That means that the <abbrev>MUA</abbrev> should
40 support multiple user-interfaces, perhaps making it even possible to
41 switch between them during runtime.
44 <para>To summarize the goals for <application>modest</application>:
46 <listitem>target devices with limited amounts of memory ('limited' in 2006
47 terms means less than 64Mb, and of which only part can be used for
49 <listitem>target Linux/Unix-like environments with GLib/GTK+-based
51 <listitem>support multiple user-interface (UIs) with as much code
52 sharing as possible between the different UIs.</listitem>
53 </itemizedlist></para>
55 <para>Like <application>tinymail</application>
56 and <application>libcamel</application>, <application>modest</application>
57 is programmed in C, using the <package>GObject</package>-system for
58 object-oriented (OO) features. For now, it specifically targets \gtk based
59 UIs (and derivatives like 'Hildon').</para>
64 <title>Architecture</title>
66 <para><application>modest</application> tries to be quite flexible in its
67 design. However, it's always important not to make things too
68 generic. Both for reasons of time limitations and keeping the software
69 understandable and 'modest', it's important to limit the scope.
73 For <application>modest</application>, the following:
75 <listitem><application>modest</application> is a e-mail program
76 using the <package>tinymail</package> and <package>camel</package>
78 <listitem><application>modest</application> targets gtk and
79 gconf-based user-interfaces, including the Hildon
80 environment;</listitem>
81 <listitem><application>modest</application> main use-case is in
82 small, mobile device such as the <productname>Nokia 770 Internet
83 Tablet</productname>;</listitem>
84 <listitem>However, effort is made also to
85 make <application>modest</application> usable as a general-purpose
86 e-mail client on normal desktop computer.</listitem>
95 <para>In this part, we'll discuss the design of various parts of
96 <application>modest</application>. We'll not go into the details of
97 various APIs in this chapter. Please consul the documentation generated
98 from the source code (<systemitem>gtk-doc</systemitem>) for that.</para>
102 <title>Configuration</title>
103 <para>Configuration is the part of <application>modest</application>
104 that deals with storing all settings. While the design allows for
105 alternative implementations, currently
106 only <systemitem>GConf</systemitem> is supported as a backend.
110 All dealing with configuration is done with
111 the <classname>ModestConf</classname>-class. It is declared
112 in <filename> modest-conf.h</filename>, and
113 the <systemitem>GConf</systemitem>-based implementation in
114 <filename>modest-conf.c</filename>. As said, there could be
115 different implementations --
116 nothing <systemitem>GConf</systemitem>-specific is visible in the
117 <classname>ModestConf</classname>-<abbrev>API</abbrev>.
122 <title>Account Management</title>
124 Account Management is the part of <application>modest</application>
125 that deals with the setting related to sending and receiving of
126 e-mail. We will follow the libcamel-convention of using the
127 term <emphasis>store</emphasis> for an e-mail storage/retrieval
128 server, and a <emphasis>transport</emphasis> for a server that
129 transports mail to its destination.
133 In practice, the following types are available:
135 <listitem><emphasis>stores</emphasis>: <abbrev>POP</abbrev>
136 and <abbrev>IMAP</abbrev>; </listitem>
137 <listitem> <emphasis>transports</emphasis>: <systemitem>sendmail</systemitem>
138 and <abbrev>SMTP</abbrev>.</listitem>
143 <title>Definitions</title>
145 <listitem>An <emphasis>account</emphasis> is a named entity
146 consisting of a <emphasis>store</emphasis> and
147 a <emphasis>transport</emphasis>. Note: For our mobile use-cases,
148 the <emphasis>transport</emphasis> cannot be a static entity, but
149 may depend on the network connection. That is however not part of
150 Account Management, so not discussed here</listitem>
151 <listitem>A <emphasis>server account</emphasis> is account
152 describing the connection with a specific server. Server accounts
155 <listitem>A <emphasis>transport</emphasis> describes the connection information
156 (servername, username, password etc.) for a transport
158 <listitem>A <emphasis>store</emphasis> describes the connection information for
159 a store server;</listitem>
167 <para>The functions to deal with account and server accounts are
168 located in <classname>ModestAccountMgr</classname>, ie. in
169 <filename>modest-account-mgr.[ch]</filename>. There function to add
170 specific values for both, to list the available ones, etc. Please
171 refer to the source code documentation for details.
176 <title>Location in configuration database</title>
178 <emphasis>Accounts</emphasis> can be found
179 in <systemitem>/apps/modest/accounts</systemitem>,
180 while <emphasis>server accounts</emphasis> can be found
181 in <systemitem>/app/modest/server_accounts</systemitem>.
185 The following image show an
186 account <systemitem>accountstest</systemitem> with server accounts
187 <systemitem>mystore</systemitem>
188 and <systemitem>mytransport</systemitem>.
189 <imagedata fileref="modest-account-mgr.png"/>
193 For each of the stores, there are number of parameters specified:
195 <listitem><emphasis>hostname</emphasis> - the place where the server resides;</listitem>
196 <listitem><emphasis>username</emphasis> - the username;</listitem>
197 <listitem><emphasis>password</emphasis> - the password;</listitem>
198 <listitem><emphasis>proto</emphasis> - the protocal for communication with this server - for
199 now these are the following valid values (literal strings):
201 <listitem><emphasis>sendmail</emphasis>;</listitem>
202 <listitem><emphasis>smtp</emphasis>;</listitem>
203 <listitem><emphasis>pop</emphasis></listitem>
204 <listitem><emphasis>imap</emphasis>.</listitem>
210 <para>In <filename>modest-proto.[ch]</filename> there are various
211 functions to check whether something is a valid protocol, and
212 whether it is a transport of a store.
215 <para>Note that server accounts and accounts are relatively independent. While
216 accounts refer to two server accounts, these server accounts can be
217 used by other accounts as well.
220 <para>The reason two keep accounts and server accounts separately, is a bit of
221 flexibility. In mobile use-cases, quite often it's desirable to use a
222 network-specific smtp-server. The chosen structure makes it easy to iterate
223 over all smtp-servers and find the right one.
229 <title>Account Management and Tinymail</title>
231 Tinymail needs the information about all configured accounts - and the
232 mechanism that it uses for that
233 is <interface>TnyAccountStoreIface</interface>. We don't want to use
234 the tinymail-provided <classname>TnyAccountStore</classname>, but
235 provide our own implementation
236 instead: <classname>ModestTnyAccountStore</classname>. This class
237 implements the <interface>TnyAccountStoreIface</interface>-interace in
238 terms of the aforementioned <classname>ModestAccountMgr</classname>.
242 One unexpected function
243 that <classname>ModestTnyAccountStore</classname> needs to implement
244 is <symbol>tny account_store get_session</symbol> (to get the
245 Camel-session). This function must be provided as a public function,
246 with that exact name.
255 <title>Finding the right transport</title>
257 One of the interesting topics in designing a mobile e-mail client is
258 to deal with transports (in
259 particular, <acronym>SMTP</acronym>). The reason for that is that
260 the majority of <acronym>SMTP</acronym>-servers only allow e-mail
261 from the same network. That means that for example <systemitem>
262 smtp.some-isp.com</systemitem> will only accept mail from
263 (<command>MAIL FROM:</command>) <systemitem>
264 user@some-isp.com</systemitem>, and refuse mail
265 from <systemitem>user@some-other-isp.com</systemitem>, unless the
266 recipient (<command>RCPT TO:</command>) is on the same network.
274 <title>Coding guidelines</title>
276 When hacking on modest, please honour these time-tested coding guidelines.
277 First, please follow the <emphasis>Linux CodingStyle guidelines</emphasis>
278 (<filename>/usr/src/linux/Documentation/CodingStyle</filename>).
282 Here are only some additional notes.
286 Your editor may help you with this, for example for <application>emacs</application>:
288 (c-set-style "K&R")
290 (setq indent-tabs-mode t)
291 (setq c-basic-offset 8)
294 Or the equivalent in your favourite editor.
298 Lines must not exceed 100 characters.
302 Functions should do one thing, and do it well. In general, functions
303 should not be much longer than 20-30 lines (except for, say, handling
304 many different cases in a 'switch'-statement). Files should not get to
305 big either; if there's more than, say, 800 lines, it probably shows the
306 codes needs to be refactored a bit.
310 Code should compile cleanly
311 with <command>gcc</command>'s <symbol>-Wall</symbol> compile option. Of
312 course this might not always be possible due to problems in dependent
313 libraries and/or compiler version. Therefore, do not
314 include <symbol>-Werror</symbol> in the standard compile options.
317 <para>Global functions (the ones in <filename>.h</filename>-files) should
319 <systemitem>gtk-doc</systemitem>.
326 Furthermore, please follow 'conventional wisdom' for programming with
327 GLib/GTK+/GObject. Some things to remember:
329 <listitem> <function>g_new</function>, <function>g_malloc</function> and
330 friends <emphasis>never</emphasis> return <function>NULL</function>. They terminate
331 the application if it happens (normally). No need to check
332 for <function>NULL</function> returns;</listitem>
333 <listitem> <function>g_return_if_fail</function> and friends may be
334 'turned off', ie. they are to be used for error checking,
335 but <emphasis>not</emphasis> for your programming logic
342 <title>Object Index</title>
346 <title>API Reference</title>
347 <xi:include href="xml/modest-ui.xml"/>
348 <xi:include href="xml/modest-tny-header-tree-view.xml"/>
349 <xi:include href="xml/modest-tny-msg-view.xml"/>
350 <xi:include href="xml/modest-account-mgr.xml"/>
351 <xi:include href="xml/modest-conf.xml"/>
352 <xi:include href="xml/modest-window-mgr.xml"/>
353 <xi:include href="xml/modest-tny-folder-tree-view.xml"/>
354 <xi:include href="xml/modest-tny-account-store.xml"/>
355 <xi:include href="xml/modest-tny-transport-actions.xml"/>
356 <xi:include href="xml/modest-main-window.xml"/>
357 <xi:include href="xml/modest-editor-window.xml"/>
358 <xi:include href="xml/modest-viewer-window.xml"/>
359 <xi:include href="xml/modest-proto.xml"/>
360 <xi:include href="xml/modest-account-keys.xml"/>
361 <xi:include href="xml/modest-conf-keys.xml"/>