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">
51 <title>modest technical documentation</title>
54 <holder>Nokia Corporation</holder>
59 <title>Introduction</title>
60 <para><application>modest</application> is a mail user agent
61 (<abbrev>MUA</abbrev>) targetting small devices, in particular Nokia's
62 <productname>Nokia 770 Internet Tablet</productname>. This document
63 describes the design and implementation of this software.
66 <para><application>modest</application> lives at the top of a extensive
67 stack of software. It is built on top
68 of <application>tinymail</application>, and uses its libcamel
69 backend. It strives to the be a simple yet powerful program, geared
70 towards small devices, for example (but not limited
71 to) <productname>Nokia's 770 internet tablet</productname>. An important
72 goal is to minimize memory usage while still being able to handle
73 significant amounts of email quickly; much of that is achieved simply by
74 using <application>tinymail</application>, which uses a number of clever
75 tricks for that, such as the proxy design pattern for listing email
76 headers, and not needing memory for headers which are not currently
81 <application>modest</application>, in turn, also tries to be efficient,
82 fast and scalable. That means that the <abbrev>MUA</abbrev> should
83 support multiple user-interfaces, perhaps making it even possible to
84 switch between them during runtime.
87 <para>To summarize the goals for <application>modest</application>:
89 <listitem>target devices with limited amounts of memory ('limited' in 2006
90 terms means less than 64Mb, and of which only part can be used for
92 <listitem>target Linux/Unix-like environments with GLib/GTK+-based
94 <listitem>support multiple user-interface (UIs) with as much code
95 sharing as possible between the different UIs.</listitem>
96 </itemizedlist></para>
98 <para>Like <application>tinymail</application>
99 and <application>libcamel</application>, <application>modest</application>
100 is programmed in C, using the <package>GObject</package>-system for
101 object-oriented (OO) features. For now, it specifically targets \gtk based
102 UIs (and derivatives like 'Hildon').</para>
107 <title>Architecture</title>
109 <para><application>modest</application> tries to be quite flexible in its
110 design. However, it's always important not to make things too
111 generic. Both for reasons of time limitations and keeping the software
112 understandable and 'modest', it's important to limit the scope.
116 For <application>modest</application>, the following:
118 <listitem><application>modest</application> is a e-mail program
119 using the <package>tinymail</package> and <package>camel</package>
120 libraries;</listitem>
121 <listitem><application>modest</application> targets gtk and
122 gconf-based user-interfaces, including the Hildon
123 environment;</listitem>
124 <listitem><application>modest</application> main use-case is in
125 small, mobile device such as the <productname>Nokia 770 Internet
126 Tablet</productname>;</listitem>
127 <listitem>However, effort is made also to
128 make <application>modest</application> usable as a general-purpose
129 e-mail client on normal desktop computer.</listitem>
136 <title>Design</title>
138 <para>In this part, we'll discuss the design of various parts of
139 <application>modest</application>. We'll not go into the details of
140 various APIs in this chapter. Please consult the documentation generated
141 from the source code (<systemitem>gtk-doc</systemitem>) for that.
146 <title>Configuration</title>
147 <para>Configuration is the part of <application>modest</application>
148 that deals with storing all settings. While the design allows for
149 alternative implementations, currently
150 only <systemitem>GConf</systemitem> is supported as a backend.
154 All dealing with configuration is done with
155 the <classname>ModestConf</classname>-class. It is declared
156 in <filename> modest-conf.h</filename>, and
157 the <systemitem>GConf</systemitem>-based implementation in
158 <filename>modest-conf.c</filename>. As said, there could be
159 different implementations --
160 nothing <systemitem>GConf</systemitem>-specific is visible in the
161 <classname>ModestConf</classname>-<abbrev>API</abbrev>.
166 <title>Account Management</title>
168 Account Management is the part of <application>modest</application>
169 that deals with the setting related to sending and receiving of
170 e-mail. We will follow the libcamel-convention of using the
171 term <emphasis>store</emphasis> for an e-mail storage/retrieval
172 server, and a <emphasis>transport</emphasis> for a server that
173 transports mail to its destination.
177 In practice, the following types are available:
179 <listitem><emphasis>stores</emphasis>: <abbrev>POP</abbrev>
180 and <abbrev>IMAP</abbrev>; </listitem>
181 <listitem> <emphasis>transports</emphasis>: <systemitem>sendmail</systemitem>
182 and <abbrev>SMTP</abbrev>.</listitem>
187 <title>Definitions</title>
189 <listitem>An <emphasis>account</emphasis> is a named entity
190 consisting of a <emphasis>store</emphasis> and
191 a <emphasis>transport</emphasis>. Note: For our mobile use-cases,
192 the <emphasis>transport</emphasis> cannot be a static entity, but
193 may depend on the network connection. That is however not part of
194 Account Management, so not discussed here</listitem>
195 <listitem>A <emphasis>server account</emphasis> is account
196 describing the connection with a specific server. Server accounts
199 <listitem>A <emphasis>transport</emphasis> describes the connection information
200 (servername, username, password etc.) for a transport
202 <listitem>A <emphasis>store</emphasis> describes the connection information for
203 a store server;</listitem>
211 <para>The functions to deal with account and server accounts are
212 located in <classname>ModestAccountMgr</classname>, ie. in
213 <filename>modest-account-mgr.[ch]</filename>. There function to add
214 specific values for both, to list the available ones, etc. Please
215 refer to the source code documentation for details.
220 <title>Location in configuration database</title>
222 <emphasis>Accounts</emphasis> can be found
223 in <systemitem>/apps/modest/accounts</systemitem>,
224 while <emphasis>server accounts</emphasis> can be found
225 in <systemitem>/app/modest/server_accounts</systemitem>.
229 The following image show an
230 account <systemitem>accountstest</systemitem> with server accounts
231 <systemitem>mystore</systemitem>
232 and <systemitem>mytransport</systemitem>.
233 <imagedata fileref="modest-account-mgr.png"/>
237 For each of the stores, there are number of parameters specified:
239 <listitem><emphasis>hostname</emphasis> - the place where the server resides;</listitem>
240 <listitem><emphasis>username</emphasis> - the username;</listitem>
241 <listitem><emphasis>password</emphasis> - the password;</listitem>
242 <listitem><emphasis>proto</emphasis> - the protocal for communication with this server - for
243 now these are the following valid values (literal strings):
245 <listitem><emphasis>sendmail</emphasis>;</listitem>
246 <listitem><emphasis>smtp</emphasis>;</listitem>
247 <listitem><emphasis>pop</emphasis></listitem>
248 <listitem><emphasis>imap</emphasis>.</listitem>
254 <para>In <filename>modest-proto.[ch]</filename> there are various
255 functions to check whether something is a valid protocol, and
256 whether it is a transport of a store.
259 <para>Note that server accounts and accounts are relatively independent. While
260 accounts refer to two server accounts, these server accounts can be
261 used by other accounts as well.
264 <para>The reason two keep accounts and server accounts separately, is a bit of
265 flexibility. In mobile use-cases, quite often it's desirable to use a
266 network-specific smtp-server. The chosen structure makes it easy to iterate
267 over all smtp-servers and find the right one.
272 <title>Account Management and Tinymail</title>
274 Tinymail needs the information about all configured accounts - and the
275 mechanism that it uses for that
276 is <interface>TnyAccountStoreIface</interface>. We don't want to use
277 the tinymail-provided <classname>TnyAccountStore</classname>, but
278 provide our own implementation
279 instead: <classname>ModestTnyAccountStore</classname>. This class
280 implements the <interface>TnyAccountStoreIface</interface>-interace in
281 terms of the aforementioned <classname>ModestAccountMgr</classname>.
285 One unexpected function
286 that <classname>ModestTnyAccountStore</classname> needs to implement
287 is <symbol>tny account_store get_session</symbol> (to get the
288 Camel-session). This function must be provided as a public function,
289 with that exact name.
295 <title>Finding the right transport</title>
297 One of the interesting topics in designing a mobile e-mail client is
298 to deal with transports (in
299 particular, <acronym>SMTP</acronym>). The reason for that is that
300 the majority of <acronym>SMTP</acronym>-servers only allow e-mail
301 from the same network. That means that for example <systemitem>
302 smtp.some-isp.com</systemitem> will only accept mail from
303 (<command>MAIL FROM:</command>) <systemitem>
304 user@some-isp.com</systemitem>, and refuse mail
305 from <systemitem>user@some-other-isp.com</systemitem>, unless the
306 recipient (<command>RCPT TO:</command>) is on the same network.
312 <title>Coding guidelines</title>
314 When hacking on modest, please honour these time-tested coding guidelines.
315 First, please follow the <emphasis>Linux CodingStyle guidelines</emphasis>
316 (<filename>/usr/src/linux/Documentation/CodingStyle</filename>).
320 Here are only some additional notes.
324 Your editor may help you with this, for example for <application>emacs</application>:
326 (c-set-style "K&R")
328 (setq indent-tabs-mode t)
329 (setq c-basic-offset 8)
332 Or the equivalent in your favourite editor.
336 Lines must not exceed 100 characters.
340 Functions should do one thing, and do it well. In general, functions
341 should not be much longer than 20-30 lines (except for, say, handling
342 many different cases in a 'switch'-statement). Files should not get to
343 big either; if there are more than, say, 800 lines, it's a sign that
344 some refactoring should take place.
348 Code should compile cleanly
349 with <command>gcc</command>'s <symbol>-Wall</symbol> compile option. Of
350 course this might not always be possible due to problems in dependent
351 libraries and/or compiler version. Therefore, do not
352 include <symbol>-Werror</symbol> in the standard compile options; but
353 do use it when building / testing things yourself.
357 Code should also run cleanly. GTK+/GLib warnings and errors must be
358 taken very seriously. If you run <application>modest</application> with
359 the <symbol>-d</symbol>-flag, it will <symbol>abort</symbol> whenever
360 there is such a warning. This can be useful when running inside the
364 <para>Global functions (the ones in <filename>.h</filename>-files) must
365 be commented using <systemitem>gtk-doc</systemitem>. This way, we
366 generate nice documentation. After installing
367 (under <filename>/usr/local</filename>), we can browse the results
368 with <application>DevHelp</application>. Just
369 add <systemitem>/usr/local/share/gtk-doc/html</systemitem> to the
370 <systemitem>DEVHELP_SEARCH_PATH</systemitem>-environment variable.
373 Furthermore, please follow 'conventional wisdom' for programming with
374 GLib/GTK+/GObject. Some things to remember:
376 <listitem> <function>g_new</function>, <function>g_malloc</function> and
377 friends <emphasis>never</emphasis> return <function>NULL</function>. They terminate
378 the application if it happens (normally). No need to check
379 for <function>NULL</function> returns;</listitem>
380 <listitem> <function>g_return_if_fail</function> and friends may be
381 'turned off', ie. they are to be used for error checking,
382 but <emphasis>not</emphasis> for your programming logic
389 <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;
424 >k-ModestAccountViewWindow;
425 >k-ModestAccountAssistant;
426 >k-ModestEditMsgWindow;
427 >k-ModestMainWindow;
428 >k-ModestStoreWidget;
429 >k-modestTransportWidget;
432 <chapter id="widgets">
433 <title>Widgets</title>
434 &widgets-ModestAccountView;
435 &widgets-ModestComboBox;
436 &widgets-ModestFolderView;
437 &widgets-ModestHeaderView;
438 &widgets-ModestMsgView;
439 &widgets-modestToolbar;