3 % Time-stamp: <2006-05-04 17:21:51 (djcb)>
6 \newcommand{\modest}{{\tt modest} }
7 \newcommand{\tinymail}{{\tt tinymail} }
8 \newcommand{\camel}{{\tt libcamel} }
10 \newcommand{\djcbemail}{$<$dirk-jan.binnema@nokia.com$>$ }
11 \newcommand{\smtp}{{\sc SMTP} }
12 \newcommand{\pop}{{\sc POP3} }
13 \newcommand{\imap}{{\sc IMAP} }
14 \newcommand{\gtk}{{\sc GTK+} }
15 \newcommand{\gconf}{{\sc GConf} }
19 \author{Dirk-Jan C. Binnema\\\djcbemail}
20 \title{{\huge \modest}\\
21 an e-mail program for small devices\\
22 architecture \& design}
23 \setlength{\parskip}{8pt}
24 \setlength{\parindent}{0pt}
28 \chapter*{Introduction}
29 \modest is a mail user agent (MUA) targetting small devices, in particular
30 Nokia's {\em Nokia 770 Internet Tablet}. This document describes the design
31 and implementation of this software.
33 \modest lives at the top of a extensive stack of software. It is built on
34 top of {\tt libtinymail}, and uses its libcamel backend. It strives to the be
35 a simple yet powerful program, geared towards small devices, for example (but
36 not limited to) Nokia's 770 internet tablet. An important goal is to minimize
37 memory usage while still being able to handle significant amounts of email
38 quickly; much of that is achieved simply by using \tinymail, which
39 uses a number of clever tricks for that, such as the proxy design pattern for
40 listing email headers, and not needing memory for headers which are not
43 \modest, in turn, also tries to be efficient, fast and {\em scalable}. That
44 means that the MUA should support multiple user-interfaces, perhaps making it
45 even possible to switch between them during runtime.
47 To summarize the goals for \modest:
49 \item target devices with limited amounts of memory ("limited" in 2006 terms means
50 less than 64Mb, and of which only part can be used for e-mail);
51 \item target Linux/Unix-like environments with GLib/GTK+-based support;
52 \item support multiple user-interface (UIs) with as
53 much code sharing as possible between the different UIs.
56 Like {\tt libtinymail} and {\tt libcamel}, \modest is programmed in C, using the
57 GObject-system for object-oriented (OO) features. For now, it specifically
58 targets \gtk based UIs (and derivatives like "Hildon").
60 \chapter{Architecture}
61 \modest tries to be quite flexible in its design. However, it's always
62 important not to make things {\em too} generic. Both for reasons of time
63 limitations and keeping the software understandable and ``modest'', it's
64 important to limit the scope.
66 For \modest, the following:
68 \item \modest is a e-mail program using the \tinymail and \camel libraries;
69 \item \modest targets \gtk and \gconf-based user-interfaces, including the Hildon
71 \item \modest main use-case is in small, mobile device such as Nokia's {\em 770
73 \item However, effort is made also to make \modest usable as a
74 general-purpose e-mail client on normal desktop computer.
82 In this chapter, we'll discuss the design of various parts of \modest. We'll
83 not go into the details of various APIs. Please consult the documentation
84 generated from the source code ({\tt gtk-doc}) for that.
86 \section {Configuration}
87 Configuration is the part of \modest that deals with storing all
88 settings. While the design allows for alternative implementations, currently
89 only {\tt gconf} is supported as a backend.
91 All dealing with configuration is done with the {\tt ModestConf} GObject. This
92 object is declared in {\tt modest-conf.h}, and the GConf-based implementation in
93 {\tt modest-conf-gconf.c}. As said, there could be different implementations
94 {\tt modest-conf-myconf.c}, but we use the GConf-backed system. However,
95 nothing GConf-specific is visible in the ModestConf API.
97 \section{Account Management}
98 Account Management is the part of \modest that deals with the setting related
99 to sending and receiving of e-mail. We will follow the libcamel-convention of
100 using the term {\em store} for a e-mail storage/retrieval server, and a {\em
101 transport} for a server that transports mail to its destination.
103 In practice, the following types are available:
105 \item {\bf stores}: \pop and \imap;
106 \item {\bf transports}: {\tt sendmail} and \smtp.
109 \subsection{Definitions}
111 \item A {\bf transport} describes the connection information (servername,
112 username, password etc.) for a transport server;
113 \item A {\bf store} describes the connection information for a store server;
114 \item An {\bf account} is a named entity consisting of a {\bf store} and a
115 {\bf transport}.\footnote{For our mobile use-cases, the {\em transport}
116 cannot be a static entity, but may depend on the network
117 connection. That is however not part of Account Management, so not
121 \chapter{Finding the Transport}
122 One of the interesting topics in designing a mobile e-mail client is to deal
123 with transports (in particular, \smtp). The reason for that is that the
124 majority of \smtp-servers only allow e-mail from the same network. That means
125 that for example {\tt smtp.some-isp.com} will only accept mail from ({\tt MAIL
126 FROM:}) {\tt user@some-isp.com}, and refuse mail from {\tt
127 user@some-other-isp.com}, unless the recipient {\tt RCPT TO:} is on the same
132 \footnote{Some smtp-servers {\bf will} accept mail
137 \chapter*{Coding guidelines}
138 When hacking on \modest, please honour these time-tested coding guidelines.
139 First, please follow the {\em Linux CodingStyle guidelines}:\\
140 {\tt /usr/src/linux/Documentation/CodingStyle}\\
141 Then, read the {\em OSSO Coding Style Guidelines}:\\
143 Here are only some additional notes.
145 Your editor may help you with this, for example for {\tt emacs}:
149 (setq indent-tabs-mode t)
150 (setq c-basic-offset 8)
153 Or the equivalent in your favourite editor.
155 Lines should not exceed 100 characters.
157 Global functions (the ones in {\tt .h}-files) should be commented using
158 doxygen-style comments.
160 Furthermore, please follow 'conventional wisdom' for programming with
161 GLib/GTK+/GObject. Some things to remember:
163 \item {\tt g\_new}, {\tt g\_malloc} and friends {\bf never} return {\tt NULL}. They terminate
164 the application if it happens (normally). No need to check for {\tt NULL} returns.
165 \item {\tt g\_return\_if\_fail} and friends may be 'turned off', ie. they are
166 to be used for error checking, but {\bf not} for your programming logic
169 To test for the validity of function parameters,
170 % g_return_if_fail / g_return_val_if_fail
175 one_divided_by_x (double x)
177 g_return_val_if_fail ((x != 0), -1);
181 This will give us a warning (and a wrong answer) in case we do
182 % one_divided_by_x (0);
184 This is good for testing, but it's important to keep in mind that in
185 production code the check may be turned off. The caller should make
186 sure that the parameter is correct (ie. != 0 in this case).
188 Now, if a similar check is actually part of the logic of a function,
189 then {\tt g\_return\_if\_fail} should not be used, but instead, e.g.:
192 stack_item_num (Stack *stack)
197 /* calculate item count */