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" [
5 <!ENTITY ModestAccountKeys SYSTEM "xml/modest-account-keys.xml">
6 <!ENTITY ModestAccountMgr SYSTEM "xml/modest-account-mgr.xml">
7 <!ENTITY ModestConfKeys SYSTEM "xml/modest-conf-keys.xml">
8 <!ENTITY ModestConf SYSTEM "xml/modest-conf.xml">
9 <!ENTITY ModestError SYSTEM "xml/modest-error.xml">
10 <!ENTITY ModestFormatter SYSTEM "xml/modest-formatter.xml">
11 <!ENTITY ModestIconFactory SYSTEM "xml/modest-icon-factory.xml">
12 <!ENTITY ModestIconNames SYSTEM "xml/modest-icon-names.xml">
13 <!ENTITY ModestMailOperation SYSTEM "xml/modest-mail-operation.xml">
14 <!ENTITY ModestMailOperationQueue SYSTEM "xml/modest-mail-operation-queue.xml">
15 <!ENTITY ModestMarshal SYSTEM "xml/modest-marshal.xml">
16 <!ENTITY ModestPair SYSTEM "xml/modest-pair.xml">
17 <!ENTITY ModestPresets SYSTEM "xml/modest-presets.xml">
18 <!ENTITY ModestProtocolMgr SYSTEM "xml/modest-protocol-mgr.xml">
19 <!ENTITY ModestProto SYSTEM "xml/modest-proto.xml">
20 <!ENTITY ModestTextUtils SYSTEM "xml/modest-text-utils.xml">
21 <!ENTITY ModestTnyAccountStore SYSTEM "xml/modest-tny-account-store.xml">
22 <!ENTITY ModestTnyAttachment SYSTEM "xml/modest-tny-attachment.xml">
23 <!ENTITY ModestTnyMsgActions SYSTEM "xml/modest-tny-msg-actions.xml">
24 <!ENTITY ModestTnyPlatformFactory SYSTEM "xml/modest-tny-platform-factory.xml">
25 <!ENTITY ModestTnyStoreActions SYSTEM "xml/modest-tny-store-actions.xml">
26 <!ENTITY ModestTnyStreamGtkhtml SYSTEM "xml/modest-tny-stream-gtkhtml.xml">
27 <!ENTITY ModestWidgetFactory SYSTEM "xml/modest-widget-factory.xml">
28 <!ENTITY ModestWidgetMemory SYSTEM "xml/modest-widget-memory.xml">
30 <!ENTITY widgets-ModestAccountView SYSTEM "xml/modest-account-view.xml">
31 <!ENTITY widgets-ModestComboBox SYSTEM "xml/modest-combo-box.xml">
32 <!ENTITY widgets-ModestFolderView SYSTEM "xml/modest-folder-view.xml">
33 <!ENTITY widgets-ModestHeaderView SYSTEM "xml/modest-header-view.xml">
34 <!ENTITY widgets-ModestMsgView SYSTEM "xml/modest-msg-view.xml">
35 <!ENTITY widgets-modestToolbar SYSTEM "xml/modest-toolbar.xml">
37 <!ENTITY gtk-ModestAccountViewWindow SYSTEM "xml/modest-account-view-window.xml">
38 <!ENTITY gtk-ModestAccountAssistant SYSTEM "xml/modest-account-assistant.xml">
39 <!ENTITY gtk-ModestEditMsgWindow SYSTEM "xml/modest-edit-msg-window.xml">
40 <!ENTITY gtk-ModestMainWindow SYSTEM "xml/modest-main-window.xml">
41 <!ENTITY gtk-ModestStoreWidget SYSTEM "xml/modest-store-widget.xml">
42 <!ENTITY gtk-modestTransportWidget SYSTEM "xml/modest-transport-widget.xml">
43 <!ENTITY gtk-modestUi SYSTEM "xml/modest-ui.xml">
45 <!ENTITY index-Object-Tree SYSTEM "xml/tree_index.sgml">
49 <!--<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">-->
52 <title>modest technical documentation</title>
55 <holder>Nokia Corporation</holder>
60 <title>Introduction</title>
61 <para><application>modest</application> is a mail user agent
62 (<abbrev>MUA</abbrev>) targetting small devices, in particular Nokia's
63 <productname>Nokia 770 Internet Tablet</productname>. This document
64 describes the design and implementation of this software.
67 <para><application>modest</application> lives at the top of a extensive
68 stack of software. It is built on top
69 of <application>tinymail</application>, and uses its libcamel
70 backend. It strives to the be a simple yet powerful program, geared
71 towards small devices, for example (but not limited
72 to) <productname>Nokia's 770 internet tablet</productname>. An important
73 goal is to minimize memory usage while still being able to handle
74 significant amounts of email quickly; much of that is achieved simply by
75 using <application>tinymail</application>, which uses a number of clever
76 tricks for that, such as the proxy design pattern for listing email
77 headers, and not needing memory for headers which are not currently
82 <application>modest</application>, in turn, also tries to be efficient,
83 fast and scalable. That means that the <abbrev>MUA</abbrev> should
84 support multiple user-interfaces, perhaps making it even possible to
85 switch between them during runtime.
88 <para>To summarize the goals for <application>modest</application>:
90 <listitem>target devices with limited amounts of memory ('limited' in 2006
91 terms means less than 64Mb, and of which only part can be used for
93 <listitem>target Linux/Unix-like environments with GLib/GTK+-based
95 <listitem>support multiple user-interface (UIs) with as much code
96 sharing as possible between the different UIs.</listitem>
97 </itemizedlist></para>
99 <para>Like <application>tinymail</application>
100 and <application>libcamel</application>, <application>modest</application>
101 is programmed in C, using the <package>GObject</package>-system for
102 object-oriented (OO) features. For now, it specifically targets \gtk based
103 UIs (and derivatives like 'Hildon').</para>
108 <title>Architecture</title>
110 <para><application>modest</application> tries to be quite flexible in its
111 design. However, it's always important not to make things too
112 generic. Both for reasons of time limitations and keeping the software
113 understandable and 'modest', it's important to limit the scope.
117 For <application>modest</application>, the following:
119 <listitem><application>modest</application> is a e-mail program
120 using the <package>tinymail</package> and <package>camel</package>
121 libraries;</listitem>
122 <listitem><application>modest</application> targets gtk and
123 gconf-based user-interfaces, including the Hildon
124 environment;</listitem>
125 <listitem><application>modest</application> main use-case is in
126 small, mobile device such as the <productname>Nokia 770 Internet
127 Tablet</productname>;</listitem>
128 <listitem>However, effort is made also to
129 make <application>modest</application> usable as a general-purpose
130 e-mail client on normal desktop computer.</listitem>
137 <title>Design</title>
139 <para>In this part, we'll discuss the design of various parts of
140 <application>modest</application>. We'll not go into the details of
141 various APIs in this chapter. Please consult the documentation generated
142 from the source code (<systemitem>gtk-doc</systemitem>) for that.
147 <title>Configuration</title>
148 <para>Configuration is the part of <application>modest</application>
149 that deals with storing all settings. While the design allows for
150 alternative implementations, currently
151 only <systemitem>GConf</systemitem> is supported as a backend.
155 All dealing with configuration is done with
156 the <classname>ModestConf</classname>-class. It is declared
157 in <filename> modest-conf.h</filename>, and
158 the <systemitem>GConf</systemitem>-based implementation in
159 <filename>modest-conf.c</filename>. As said, there could be
160 different implementations --
161 nothing <systemitem>GConf</systemitem>-specific is visible in the
162 <classname>ModestConf</classname>-<abbrev>API</abbrev>.
167 <title>Account Management</title>
169 Account Management is the part of <application>modest</application>
170 that deals with the setting related to sending and receiving of
171 e-mail. We will follow the libcamel-convention of using the
172 term <emphasis>store</emphasis> for an e-mail storage/retrieval
173 server, and a <emphasis>transport</emphasis> for a server that
174 transports mail to its destination.
178 In practice, the following types are available:
180 <listitem><emphasis>stores</emphasis>: <abbrev>POP</abbrev>
181 and <abbrev>IMAP</abbrev>; </listitem>
182 <listitem> <emphasis>transports</emphasis>: <systemitem>sendmail</systemitem>
183 and <abbrev>SMTP</abbrev>.</listitem>
188 <title>Definitions</title>
190 <listitem>An <emphasis>account</emphasis> is a named entity
191 consisting of a <emphasis>store</emphasis> and
192 a <emphasis>transport</emphasis>. Note: For our mobile use-cases,
193 the <emphasis>transport</emphasis> cannot be a static entity, but
194 may depend on the network connection. That is however not part of
195 Account Management, so not discussed here</listitem>
196 <listitem>A <emphasis>server account</emphasis> is account
197 describing the connection with a specific server. Server accounts
200 <listitem>A <emphasis>transport</emphasis> describes the connection information
201 (servername, username, password etc.) for a transport
203 <listitem>A <emphasis>store</emphasis> describes the connection information for
204 a store server;</listitem>
212 <para>The functions to deal with account and server accounts are
213 located in <classname>ModestAccountMgr</classname>, ie. in
214 <filename>modest-account-mgr.[ch]</filename>. There function to add
215 specific values for both, to list the available ones, etc. Please
216 refer to the source code documentation for details.
221 <title>Location in configuration database</title>
223 <emphasis>Accounts</emphasis> can be found
224 in <systemitem>/apps/modest/accounts</systemitem>,
225 while <emphasis>server accounts</emphasis> can be found
226 in <systemitem>/app/modest/server_accounts</systemitem>.
230 The following image show an
231 account <systemitem>accountstest</systemitem> with server accounts
232 <systemitem>mystore</systemitem>
233 and <systemitem>mytransport</systemitem>.
234 <imagedata fileref="modest-account-mgr.png"/>
238 For each of the stores, there are number of parameters specified:
240 <listitem><emphasis>hostname</emphasis> - the place where the server resides;</listitem>
241 <listitem><emphasis>username</emphasis> - the username;</listitem>
242 <listitem><emphasis>password</emphasis> - the password;</listitem>
243 <listitem><emphasis>proto</emphasis> - the protocal for communication with this server - for
244 now these are the following valid values (literal strings):
246 <listitem><emphasis>sendmail</emphasis>;</listitem>
247 <listitem><emphasis>smtp</emphasis>;</listitem>
248 <listitem><emphasis>pop</emphasis></listitem>
249 <listitem><emphasis>imap</emphasis>.</listitem>
255 <para>In <filename>modest-proto.[ch]</filename> there are various
256 functions to check whether something is a valid protocol, and
257 whether it is a transport of a store.
260 <para>Note that server accounts and accounts are relatively independent. While
261 accounts refer to two server accounts, these server accounts can be
262 used by other accounts as well.
265 <para>The reason two keep accounts and server accounts separately, is a bit of
266 flexibility. In mobile use-cases, quite often it's desirable to use a
267 network-specific smtp-server. The chosen structure makes it easy to iterate
268 over all smtp-servers and find the right one.
273 <title>Account Management and Tinymail</title>
275 Tinymail needs the information about all configured accounts - and the
276 mechanism that it uses for that
277 is <interface>TnyAccountStoreIface</interface>. We don't want to use
278 the tinymail-provided <classname>TnyAccountStore</classname>, but
279 provide our own implementation
280 instead: <classname>ModestTnyAccountStore</classname>. This class
281 implements the <interface>TnyAccountStoreIface</interface>-interace in
282 terms of the aforementioned <classname>ModestAccountMgr</classname>.
286 One unexpected function
287 that <classname>ModestTnyAccountStore</classname> needs to implement
288 is <symbol>tny account_store get_session</symbol> (to get the
289 Camel-session). This function must be provided as a public function,
290 with that exact name.
296 <title>Finding the right transport</title>
298 One of the interesting topics in designing a mobile e-mail client is
299 to deal with transports (in
300 particular, <acronym>SMTP</acronym>). The reason for that is that
301 the majority of <acronym>SMTP</acronym>-servers only allow e-mail
302 from the same network. That means that for example <systemitem>
303 smtp.some-isp.com</systemitem> will only accept mail from
304 (<command>MAIL FROM:</command>) <systemitem>
305 user@some-isp.com</systemitem>, and refuse mail
306 from <systemitem>user@some-other-isp.com</systemitem>, unless the
307 recipient (<command>RCPT TO:</command>) is on the same network.
313 <title>Coding guidelines</title>
315 When hacking on modest, please honour these time-tested coding guidelines.
316 First, please follow the <emphasis>Linux CodingStyle guidelines</emphasis>
317 (<filename>/usr/src/linux/Documentation/CodingStyle</filename>).
321 Here are only some additional notes.
325 Your editor may help you with this, for example for <application>emacs</application>:
327 (c-set-style "K&R")
329 (setq indent-tabs-mode t)
330 (setq c-basic-offset 8)
333 Or the equivalent in your favourite editor.
337 Lines must not exceed 100 characters.
341 Functions should do one thing, and do it well. In general, functions
342 should not be much longer than 20-30 lines (except for, say, handling
343 many different cases in a 'switch'-statement). Files should not get to
344 big either; if there are more than, say, 800 lines, it's a sign that
345 some refactoring should take place.
349 Code should compile cleanly
350 with <command>gcc</command>'s <symbol>-Wall</symbol> compile option. Of
351 course this might not always be possible due to problems in dependent
352 libraries and/or compiler version. Therefore, do not
353 include <symbol>-Werror</symbol> in the standard compile options; but
354 do use it when building / testing things yourself.
358 Code should also run cleanly. GTK+/GLib warnings and errors must be
359 taken very seriously. If you run <application>modest</application> with
360 the <symbol>-d</symbol>-flag, it will <symbol>abort</symbol> whenever
361 there is such a warning. This can be useful when running inside the
365 <para>Global functions (the ones in <filename>.h</filename>-files) must
366 be commented using <systemitem>gtk-doc</systemitem>. This way, we
367 generate nice documentation. After installing
368 (under <filename>/usr/local</filename>), we can browse the results
369 with <application>DevHelp</application>. Just
370 add <systemitem>/usr/local/share/gtk-doc/html</systemitem> to the
371 <systemitem>DEVHELP_SEARCH_PATH</systemitem>-environment variable.
374 Furthermore, please follow 'conventional wisdom' for programming with
375 GLib/GTK+/GObject. Some things to remember:
377 <listitem> <function>g_new</function>, <function>g_malloc</function> and
378 friends <emphasis>never</emphasis> return <function>NULL</function>. They terminate
379 the application if it happens (normally). No need to check
380 for <function>NULL</function> returns;</listitem>
381 <listitem> <function>g_return_if_fail</function> and friends may be
382 'turned off', ie. they are to be used for error checking,
383 but <emphasis>not</emphasis> for your programming logic
390 <title>Object Index</title>
394 <title>API Reference</title>
396 <title>Modest</title>
405 &ModestMailOperation;
406 &ModestMailOperationQueue;
413 &ModestTnyAccountStore;
414 &ModestTnyAttachment;
415 &ModestTnyMsgActions;
416 &ModestTnyPlatformFactory;
417 &ModestTnyStoreActions;
418 &ModestTnyStreamGtkhtml;
419 &ModestWidgetFactory;
425 <chapter id="widgets">
426 <title>Widgets</title>