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 reference manual</title>
10 <title>Introduction</title>
12 <para><application>modest</application> is a mail user agent
13 (<abbrev>MUA</abbrev>) targetting small devices, in particular Nokia's
14 <productname>Nokia 770 Internet Tablet</productname>. This document
15 describes the design and implementation of this software.
18 <para><application>modest</application> lives at the top of a extensive
19 stack of software. It is built on top
20 of <application>tinymail</application>, and uses its libcamel
21 backend. It strives to the be a simple yet powerful program, geared
22 towards small devices, for example (but not limited
23 to) <productname>Nokia's 770 internet tablet</productname>. An important
24 goal is to minimize memory usage while still being able to handle
25 significant amounts of email quickly; much of that is achieved simply by
26 using <application>tinymail</application>, which uses a number of clever
27 tricks for that, such as the proxy design pattern for listing email
28 headers, and not needing memory for headers which are not currently
33 <application>modest</application>, in turn, also tries to be efficient,
34 fast and scalable. That means that the <abbrev>MUA</abbrev> should
35 support multiple user-interfaces, perhaps making it even possible to
36 switch between them during runtime.
39 <para>To summarize the goals for <application>modest</application>:
41 <listitem>target devices with limited amounts of memory ('limited' in 2006
42 terms means less than 64Mb, and of which only part can be used for
44 <listitem>target Linux/Unix-like environments with GLib/GTK+-based
46 <listitem>support multiple user-interface (UIs) with as much code
47 sharing as possible between the different UIs.</listitem>
48 </itemizedlist></para>
50 <para>Like <application>tinymail</application>
51 and <application>libcamel</application>, <application>modest</application>
52 is programmed in C, using the <package>GObject</package>-system for
53 object-oriented (OO) features. For now, it specifically targets \gtk based
54 UIs (and derivatives like 'Hildon').</para>
59 <title>Architecture</title>
61 <para><application>modest</application> tries to be quite flexible in its
62 design. However, it's always important not to make things too
63 generic. Both for reasons of time limitations and keeping the software
64 understandable and 'modest', it's important to limit the scope.
68 For <application>modest</application>, the following:
70 <listitem><application>modest</application> is a e-mail program
71 using the <package>tinymail</package> and <package>camel</package>
73 <listitem><application>modest</application> targets gtk and
74 gconf-based user-interfaces, including the Hildon
75 environment;</listitem>
76 <listitem><application>modest</application> main use-case is in
77 small, mobile device such as the <productname>Nokia 770 Internet
78 Tablet</productname>;</listitem>
79 <listitem>However, effort is made also to
80 make <application>modest</application> usable as a general-purpose
81 e-mail client on normal desktop computer.</listitem>
90 <para>In this part, we'll discuss the design of various parts of
91 <application>modest</application>. We'll not go into the details of
92 various APIs in this chapter. Please consul the documentation generated
93 from the source code (<systemitem>gtk-doc</systemitem>) for that.</para>
97 <title>Configuration</title>
98 <para>Configuration is the part of <application>modest</application>
99 that deals with storing all settings. While the design allows for
100 alternative implementations, currently
101 only <systemitem>GConf</systemitem> is supported as a backend.
105 All dealing with configuration is done with
106 the <classname>ModestConf</classname>-class. It is declared
107 in <filename> modest-conf.h</filename>, and
108 the <systemitem>GConf</systemitem>-based implementation in
109 <filename>modest-conf-gconf.c</filename>. As said, there could be
110 different implementations --
111 nothing <systemitem>GConf</systemitem>-specific is visible in the
112 <classname>ModestConf</classname>-<abbrev>API</abbrev>.
117 <title>Account Management</title>
119 Account Management is the part of <application>modest</application>
120 that deals with the setting related to sending and receiving of
121 e-mail. We will follow the libcamel-convention of using the
122 term <emphasis> store</emphasis> for an e-mail storage/retrieval
123 server, and a <emphasis>transport</emphasis> for a server that
124 transports mail to its destination.
128 In practice, the following types are available:
130 <listitem><emphasis>stores</emphasis>: <abbrev>POP</abbrev>
131 and <abbrev>IMAP</abbrev>; </listitem>
132 <listitem> <emphasis>transports</emphasis>: <systemitem>sendmail</systemitem>
133 and <abbrev>SMTP</abbrev>.</listitem>
138 <title>Definitions</title>
140 <listitem>An <emphasis>account</emphasis> is a named entity
141 consisting of a <emphasis>store</emphasis> and
142 a <emphasis>transport</emphasis>. Note: For our mobile use-cases,
143 the <emphasis>transport</emphasis> cannot be a static entity, but
144 may depend on the network connection. That is however not part of
145 Account Management, so not discussed here</listitem>
146 <listitem>A <emphasis>server account</emphasis> is account
147 describing the connection with a specific server. Server accounts
150 <listitem>A <emphasis>transport</emphasis> describes the connection information
151 (servername, username, password etc.) for a transport
153 <listitem>A <emphasis>store</emphasis> describes the connection information for
154 a store server;</listitem>
162 <para>The functions to deal with account and server accounts are
163 located in <classname>ModestAccountMgr</classname>, ie. in
164 <filename>modest-account-mgr.[ch]</filename>. There function to add
165 specific values for both, to list the available ones, etc. Please
166 refer to the source code documentation for details.
171 <title>Location in configuration database</title>
173 <emphasis>Accounts</emphasis> can be found
174 in <systemitem>/apps/modest/accounts</systemitem>,
175 while <emphasis>server accounts</emphasis> can be found
176 in <systemitem>/app/modest/server_accounts</systemitem>.
180 The following image show an
181 account <systemitem>accountstest</systemitem> with server accounts
182 <systemitem>mystore</systemitem>
183 and <systemitem>mytransport</systemitem>.
184 <imagedata fileref="modest-account-mgr.png"/>
188 For each of the stores, there are number of parameters specified:
190 <listitem><emphasis>hostname</emphasis> - the place where the server resides;</listitem>
191 <listitem><emphasis>username</emphasis> - the username;</listitem>
192 <listitem><emphasis>password</emphasis> - the password;</listitem>
193 <listitem><emphasis>proto</emphasis> - the protocal for communication with this server - for
194 now these are the following valid values (literal strings):
196 <listitem><emphasis>sendmail</emphasis>;</listitem>
197 <listitem><emphasis>smtp</emphasis>;</listitem>
198 <listitem><emphasis>pop</emphasis></listitem>
199 <listitem><emphasis>imap</emphasis>.</listitem>
205 <para>In the <filename>modest-proto.[ch]</filename> there are
206 various functions to check whether something is a valid protocol, and whether
207 it is a transport of a store.
210 <para>Note that server accounts and accounts are relatively independent. While
211 accounts refer to two server accounts, these server accounts can be
212 used by other accounts as well.
215 <para>The reason two keep accounts and server accounts separately, is a bit of
216 flexibility. In mobile use-cases, quite often it's desirable to use a
217 network-specific smtp-server. The chosen structure makes it easy to iterate
218 over all smtp-servers and find the right one.
224 <title>Finding the right transport</title>
226 One of the interesting topics in designing a mobile e-mail client is
227 to deal with transports (in
228 particular, <acronym>SMTP</acronym>). The reason for that is that
229 the majority of <acronym>SMTP</acronym>-servers only allow e-mail
230 from the same network. That means that for example <systemitem>
231 smtp.some-isp.com</systemitem> will only accept mail from
232 (<command>MAIL FROM:</command>) <systemitem>
233 user@some-isp.com</systemitem>, and refuse mail
234 from <systemitem>user@some-other-isp.com</systemitem>, unless the
235 recipient (<command>RCPT TO:</command>) is on the same network.
241 <title>Coding guidelines</title>
243 When hacking on \modest, please honour these time-tested coding guidelines.
244 First, please follow the <emphasis>Linux CodingStyle guidelines</emphasis>
245 (<filename>/usr/src/linux/Documentation/CodingStyle</filename>).
249 Here are only some additional notes.
253 Your editor may help you with this, for example for <application>emacs</application>:
255 (c-set-style "K&R")
257 (setq indent-tabs-mode t)
258 (setq c-basic-offset 8)
263 Or the equivalent in your favourite editor.
267 Lines should not exceed 100 characters.
270 <para>Global functions (the ones in <filename>.h</filename>-files) should
272 <systemitem>gtk-doc</systemitem>.
276 Furthermore, please follow 'conventional wisdom' for programming with
277 GLib/GTK+/GObject. Some things to remember:
279 <listitem> <function>g_new</function>, <function>g_malloc</function> and
280 friends <emphasis>never</emphasis> return <function>NULL</function>. They terminate
281 the application if it happens (normally). No need to check
282 for <function>NULL</function> returns;</listitem>
283 <listitem> <function>g_return_if_fail</function> and friends may be
284 'turned off', ie. they are to be used for error checking,
285 but <emphasis>not</emphasis> for your programming logic
292 <title>Object Index</title>
296 <title>API Reference</title>
297 <xi:include href="xml/modest-ui.xml"/>
298 <xi:include href="xml/modest-tny-header-tree-view.xml"/>
299 <xi:include href="xml/modest-tny-msg-view.xml"/>
300 <xi:include href="xml/modest-account-mgr.xml"/>
301 <xi:include href="xml/modest-conf.xml"/>
302 <xi:include href="xml/modest-window-mgr.xml"/>
303 <xi:include href="xml/modest-tny-folder-tree-view.xml"/>
304 <xi:include href="xml/modest-tny-account-store.xml"/>
305 <xi:include href="xml/modest-tny-transport-actions.xml"/>
306 <xi:include href="xml/modest-main-window.xml"/>
307 <xi:include href="xml/modest-edit-window.xml"/>
308 <xi:include href="xml/modest-editor-window.xml"/>
309 <xi:include href="xml/modest-proto.xml"/>
310 <xi:include href="xml/modest-account-keys.xml"/>
311 <xi:include href="xml/modest-conf-keys.xml"/>