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">
6 <title>modest technical documentation</title>
9 <holder>Nokia Corporation</holder>
14 <title>Introduction</title>
15 <para><application>modest</application> is a mail user agent
16 (<abbrev>MUA</abbrev>) targetting small devices, in particular Nokia's
17 <productname>Nokia 770 Internet Tablet</productname>. This document
18 describes the design and implementation of this software.
21 <para><application>modest</application> lives at the top of a extensive
22 stack of software. It is built on top
23 of <application>tinymail</application>, and uses its libcamel
24 backend. It strives to the be a simple yet powerful program, geared
25 towards small devices, for example (but not limited
26 to) <productname>Nokia's 770 internet tablet</productname>. An important
27 goal is to minimize memory usage while still being able to handle
28 significant amounts of email quickly; much of that is achieved simply by
29 using <application>tinymail</application>, which uses a number of clever
30 tricks for that, such as the proxy design pattern for listing email
31 headers, and not needing memory for headers which are not currently
36 <application>modest</application>, in turn, also tries to be efficient,
37 fast and scalable. That means that the <abbrev>MUA</abbrev> should
38 support multiple user-interfaces, perhaps making it even possible to
39 switch between them during runtime.
42 <para>To summarize the goals for <application>modest</application>:
44 <listitem>target devices with limited amounts of memory ('limited' in 2006
45 terms means less than 64Mb, and of which only part can be used for
47 <listitem>target Linux/Unix-like environments with GLib/GTK+-based
49 <listitem>support multiple user-interface (UIs) with as much code
50 sharing as possible between the different UIs.</listitem>
51 </itemizedlist></para>
53 <para>Like <application>tinymail</application>
54 and <application>libcamel</application>, <application>modest</application>
55 is programmed in C, using the <package>GObject</package>-system for
56 object-oriented (OO) features. For now, it specifically targets \gtk based
57 UIs (and derivatives like 'Hildon').</para>
62 <title>Architecture</title>
64 <para><application>modest</application> tries to be quite flexible in its
65 design. However, it's always important not to make things too
66 generic. Both for reasons of time limitations and keeping the software
67 understandable and 'modest', it's important to limit the scope.
71 For <application>modest</application>, the following:
73 <listitem><application>modest</application> is a e-mail program
74 using the <package>tinymail</package> and <package>camel</package>
76 <listitem><application>modest</application> targets gtk and
77 gconf-based user-interfaces, including the Hildon
78 environment;</listitem>
79 <listitem><application>modest</application> main use-case is in
80 small, mobile device such as the <productname>Nokia 770 Internet
81 Tablet</productname>;</listitem>
82 <listitem>However, effort is made also to
83 make <application>modest</application> usable as a general-purpose
84 e-mail client on normal desktop computer.</listitem>
93 <para>In this part, we'll discuss the design of various parts of
94 <application>modest</application>. We'll not go into the details of
95 various APIs in this chapter. Please consult the documentation generated
96 from the source code (<systemitem>gtk-doc</systemitem>) for that.
101 <title>Configuration</title>
102 <para>Configuration is the part of <application>modest</application>
103 that deals with storing all settings. While the design allows for
104 alternative implementations, currently
105 only <systemitem>GConf</systemitem> is supported as a backend.
109 All dealing with configuration is done with
110 the <classname>ModestConf</classname>-class. It is declared
111 in <filename> modest-conf.h</filename>, and
112 the <systemitem>GConf</systemitem>-based implementation in
113 <filename>modest-conf.c</filename>. As said, there could be
114 different implementations --
115 nothing <systemitem>GConf</systemitem>-specific is visible in the
116 <classname>ModestConf</classname>-<abbrev>API</abbrev>.
121 <title>Account Management</title>
123 Account Management is the part of <application>modest</application>
124 that deals with the setting related to sending and receiving of
125 e-mail. We will follow the libcamel-convention of using the
126 term <emphasis>store</emphasis> for an e-mail storage/retrieval
127 server, and a <emphasis>transport</emphasis> for a server that
128 transports mail to its destination.
132 In practice, the following types are available:
134 <listitem><emphasis>stores</emphasis>: <abbrev>POP</abbrev>
135 and <abbrev>IMAP</abbrev>; </listitem>
136 <listitem> <emphasis>transports</emphasis>: <systemitem>sendmail</systemitem>
137 and <abbrev>SMTP</abbrev>.</listitem>
142 <title>Definitions</title>
144 <listitem>An <emphasis>account</emphasis> is a named entity
145 consisting of a <emphasis>store</emphasis> and
146 a <emphasis>transport</emphasis>. Note: For our mobile use-cases,
147 the <emphasis>transport</emphasis> cannot be a static entity, but
148 may depend on the network connection. That is however not part of
149 Account Management, so not discussed here</listitem>
150 <listitem>A <emphasis>server account</emphasis> is account
151 describing the connection with a specific server. Server accounts
154 <listitem>A <emphasis>transport</emphasis> describes the connection information
155 (servername, username, password etc.) for a transport
157 <listitem>A <emphasis>store</emphasis> describes the connection information for
158 a store server;</listitem>
166 <para>The functions to deal with account and server accounts are
167 located in <classname>ModestAccountMgr</classname>, ie. in
168 <filename>modest-account-mgr.[ch]</filename>. There function to add
169 specific values for both, to list the available ones, etc. Please
170 refer to the source code documentation for details.
175 <title>Location in configuration database</title>
177 <emphasis>Accounts</emphasis> can be found
178 in <systemitem>/apps/modest/accounts</systemitem>,
179 while <emphasis>server accounts</emphasis> can be found
180 in <systemitem>/app/modest/server_accounts</systemitem>.
184 The following image show an
185 account <systemitem>accountstest</systemitem> with server accounts
186 <systemitem>mystore</systemitem>
187 and <systemitem>mytransport</systemitem>.
188 <imagedata fileref="modest-account-mgr.png"/>
192 For each of the stores, there are number of parameters specified:
194 <listitem><emphasis>hostname</emphasis> - the place where the server resides;</listitem>
195 <listitem><emphasis>username</emphasis> - the username;</listitem>
196 <listitem><emphasis>password</emphasis> - the password;</listitem>
197 <listitem><emphasis>proto</emphasis> - the protocal for communication with this server - for
198 now these are the following valid values (literal strings):
200 <listitem><emphasis>sendmail</emphasis>;</listitem>
201 <listitem><emphasis>smtp</emphasis>;</listitem>
202 <listitem><emphasis>pop</emphasis></listitem>
203 <listitem><emphasis>imap</emphasis>.</listitem>
209 <para>In <filename>modest-proto.[ch]</filename> there are various
210 functions to check whether something is a valid protocol, and
211 whether it is a transport of a store.
214 <para>Note that server accounts and accounts are relatively independent. While
215 accounts refer to two server accounts, these server accounts can be
216 used by other accounts as well.
219 <para>The reason two keep accounts and server accounts separately, is a bit of
220 flexibility. In mobile use-cases, quite often it's desirable to use a
221 network-specific smtp-server. The chosen structure makes it easy to iterate
222 over all smtp-servers and find the right one.
227 <title>Account Management and Tinymail</title>
229 Tinymail needs the information about all configured accounts - and the
230 mechanism that it uses for that
231 is <interface>TnyAccountStoreIface</interface>. We don't want to use
232 the tinymail-provided <classname>TnyAccountStore</classname>, but
233 provide our own implementation
234 instead: <classname>ModestTnyAccountStore</classname>. This class
235 implements the <interface>TnyAccountStoreIface</interface>-interace in
236 terms of the aforementioned <classname>ModestAccountMgr</classname>.
240 One unexpected function
241 that <classname>ModestTnyAccountStore</classname> needs to implement
242 is <symbol>tny account_store get_session</symbol> (to get the
243 Camel-session). This function must be provided as a public function,
244 with that exact name.
250 <title>Finding the right transport</title>
252 One of the interesting topics in designing a mobile e-mail client is
253 to deal with transports (in
254 particular, <acronym>SMTP</acronym>). The reason for that is that
255 the majority of <acronym>SMTP</acronym>-servers only allow e-mail
256 from the same network. That means that for example <systemitem>
257 smtp.some-isp.com</systemitem> will only accept mail from
258 (<command>MAIL FROM:</command>) <systemitem>
259 user@some-isp.com</systemitem>, and refuse mail
260 from <systemitem>user@some-other-isp.com</systemitem>, unless the
261 recipient (<command>RCPT TO:</command>) is on the same network.
267 <title>Coding guidelines</title>
269 When hacking on modest, please honour these time-tested coding guidelines.
270 First, please follow the <emphasis>Linux CodingStyle guidelines</emphasis>
271 (<filename>/usr/src/linux/Documentation/CodingStyle</filename>).
275 Here are only some additional notes.
279 Your editor may help you with this, for example for <application>emacs</application>:
281 (c-set-style "K&R")
283 (setq indent-tabs-mode t)
284 (setq c-basic-offset 8)
287 Or the equivalent in your favourite editor.
291 Lines must not exceed 100 characters.
295 Functions should do one thing, and do it well. In general, functions
296 should not be much longer than 20-30 lines (except for, say, handling
297 many different cases in a 'switch'-statement). Files should not get to
298 big either; if there are more than, say, 800 lines, it's a sign that
299 some refactoring should take place.
303 Code should compile cleanly
304 with <command>gcc</command>'s <symbol>-Wall</symbol> compile option. Of
305 course this might not always be possible due to problems in dependent
306 libraries and/or compiler version. Therefore, do not
307 include <symbol>-Werror</symbol> in the standard compile options.
310 <para>Global functions (the ones in <filename>.h</filename>-files) must
311 be commented using <systemitem>gtk-doc</systemitem>. This way, we
312 generate nice documentation. After installing
313 (under <filename>/usr/local</filename>), we can browse the results
314 with <application>DevHelp</application>. Just
315 add <systemitem>/usr/local/share/gtk-doc/html</systemitem> to the
316 <systemitem>DEVHELP_SEARCH_PATH</systemitem>-environment variable.
319 Furthermore, please follow 'conventional wisdom' for programming with
320 GLib/GTK+/GObject. Some things to remember:
322 <listitem> <function>g_new</function>, <function>g_malloc</function> and
323 friends <emphasis>never</emphasis> return <function>NULL</function>. They terminate
324 the application if it happens (normally). No need to check
325 for <function>NULL</function> returns;</listitem>
326 <listitem> <function>g_return_if_fail</function> and friends may be
327 'turned off', ie. they are to be used for error checking,
328 but <emphasis>not</emphasis> for your programming logic
335 <title>Object Index</title>
339 <title>API Reference</title>
340 <xi:include href="xml/modest-ui.xml"/>
341 <xi:include href="xml/modest-tny-header-tree-view.xml"/>
342 <xi:include href="xml/modest-tny-msg-view.xml"/>
343 <xi:include href="xml/modest-account-mgr.xml"/>
344 <xi:include href="xml/modest-conf.xml"/>
345 <xi:include href="xml/modest-window-mgr.xml"/>
346 <xi:include href="xml/modest-tny-folder-tree-view.xml"/>
347 <xi:include href="xml/modest-tny-account-store.xml"/>
348 <xi:include href="xml/modest-tny-transport-actions.xml"/>
349 <xi:include href="xml/modest-main-window.xml"/>
350 <xi:include href="xml/modest-editor-window.xml"/>
351 <xi:include href="xml/modest-viewer-window.xml"/>
352 <xi:include href="xml/modest-proto.xml"/>
353 <xi:include href="xml/modest-account-keys.xml"/>
354 <xi:include href="xml/modest-conf-keys.xml"/>