+++ /dev/null
-%
-% modest-design.tex
-% Time-stamp: <2006-05-12 18:47:13 (djcb)>
-%
-\documentclass{book}
-\usepackage{graphics}
-
-% macros
-\newcommand{\modest}{{\tt modest} }
-\newcommand{\tinymail}{{\tt tinymail} }
-\newcommand{\camel}{{\tt libcamel} }
-
-\newcommand{\djcbemail}{$<$dirk-jan.binnema@nokia.com$>$ }
-\newcommand{\smtp}{{\sc SMTP} }
-\newcommand{\pop}{{\sc POP3} }
-\newcommand{\imap}{{\sc IMAP} }
-\newcommand{\gtk}{{\sc GTK+} }
-\newcommand{\gconf}{{\sc GConf} }
-
-\author{Dirk-Jan C. Binnema\\\djcbemail}
-\title{{\huge \modest}\\
-an e-mail program for small devices\\
-architecture \& design}
-\setlength{\parskip}{8pt}
-\setlength{\parindent}{0pt}
-\begin{document}
-\maketitle
-\tableofcontents
-\chapter*{Introduction}
-\modest is a mail user agent (MUA) targetting small devices, in particular
-Nokia's {\em Nokia 770 Internet Tablet}. This document describes the design
-and implementation of this software.
-
-\modest lives at the top of a extensive stack of software. It is built on
-top of {\tt libtinymail}, and uses its libcamel backend. It strives to the be
-a simple yet powerful program, geared towards small devices, for example (but
-not limited to) Nokia's 770 internet tablet. An important goal is to minimize
-memory usage while still being able to handle significant amounts of email
-quickly; much of that is achieved simply by using \tinymail, which
-uses a number of clever tricks for that, such as the proxy design pattern for
-listing email headers, and not needing memory for headers which are not
-currently visible.
-
-\modest, in turn, also tries to be efficient, fast and {\em scalable}. That
-means that the MUA should support multiple user-interfaces, perhaps making it
-even possible to switch between them during runtime.
-
-To summarize the goals for \modest:
-\begin{itemize}
-\item target devices with limited amounts of memory ("limited" in 2006 terms means
- less than 64Mb, and of which only part can be used for e-mail);
-\item target Linux/Unix-like environments with GLib/GTK+-based support;
-\item support multiple user-interface (UIs) with as
- much code sharing as possible between the different UIs.
-\end{itemize}
-
-Like {\tt libtinymail} and {\tt libcamel}, \modest is programmed in C, using the
-GObject-system for object-oriented (OO) features. For now, it specifically
-targets \gtk based UIs (and derivatives like "Hildon").
-
-\chapter{Architecture}
-\modest tries to be quite flexible in its design. However, it's always
-important not to make things {\em too} generic. Both for reasons of time
-limitations and keeping the software understandable and ``modest'', it's
-important to limit the scope.
-
-For \modest, the following:
-\begin{itemize}
- \item \modest is a e-mail program using the \tinymail and \camel libraries;
- \item \modest targets \gtk and \gconf-based user-interfaces, including the Hildon
- environment;
- \item \modest main use-case is in small, mobile device such as Nokia's {\em 770
- Internet Tablet};
- \item However, effort is made also to make \modest usable as a
- general-purpose e-mail client on normal desktop computer.
-\end{itemize}
-
-
-\chapter{Design}
-In this chapter, we'll discuss the design of various parts of \modest. We'll
-not go into the details of various APIs. Please consult the documentation
-generated from the source code ({\tt gtk-doc}) for that.
-
-There are {\tt \#define}-definitions for many account keys in {\tt
- modest-account-keys.h}.
-
-\section {Configuration}
-Configuration is the part of \modest that deals with storing all
-settings. While the design allows for alternative implementations, currently
-only {\tt gconf} is supported as a backend.
-
-All dealing with configuration is done with the {\tt ModestConf} GObject. This
-object is declared in {\tt modest-conf.h}, and the GConf-based implementation in
-{\tt modest-conf-gconf.c}. As said, there could be different implementations
-{\tt modest-conf-myconf.c}, but we use the GConf-backed system. However,
-nothing GConf-specific is visible in the ModestConf API.
-
-\section{Account Management}
-Account Management is the part of \modest that deals with the setting related
-to sending and receiving of e-mail. We will follow the libcamel-convention of
-using the term {\em store} for a e-mail storage/retrieval server, and a {\em
- transport} for a server that transports mail to its destination.
-
-In practice, the following types are available:
-\begin{itemize}
- \item {\bf stores}: \pop and \imap;
- \item {\bf transports}: {\tt sendmail} and \smtp.
-\end{itemize}
-
-\subsection{Definitions}
-\begin{itemize}
- \item An {\bf account} is a named entity consisting of a {\bf store} and a
- {\bf transport}.\footnote{For our mobile use-cases, the {\em transport}
- cannot be a static entity, but may depend on the network
- connection. That is however not part of Account Management, so not
- discussed here}
- \item A {\bf server account} is account describing the connection with a
- specific server. Server accounts come in two type:
- \begin{itemize}
- \item A {\bf transport} describes the connection information (servername,
- username, password etc.) for a transport server;
- \item A {\bf store} describes the connection information for a store server;
- \end{itemize}
-\end{itemize}
-
-\subsection{Code}
-The functions to deal with account and server accounts are located in {\tt
- ModestAccountMgr}, ie. in {\tt modest-account-mgr.[ch]}. There function to
-add specific values for both, to list the available ones, etc. Please refer to
-the source code documentation for details.
-
-\subsection{Location in configuration database}
-{\em Accounts} can be found in {\tt /apps/modest/accounts}, while {\em server
- accounts} can be found in {\tt /app/modest/server\_accounts}.
-
-The following image show an account {\em accountstest} with server accounts
-{\tt mystore} and {\tt mytransport}.
-
-\includegraphics{modest-account-mgr.png}
-
-For each of the stores, there are number of parameters specified:
-\begin{itemize}
-\item {\tt hostname} - the place where the server resides;
-\item {\tt username} - the username;
-\item {\tt password} - the password;
-\item {\tt proto} - the protocal for communication with this server - for
- now these are the following valid values (literal strings):
- \begin{itemize}
- \item {\tt sendmail};
- \item {\tt smtp};
- \item {\tt pop}
- \item {\tt imap}.
- \end{itemize}
-\end{itemize}
-
-In the {\tt modest-proto.[ch]} there are various functions to check whether
-something is a valid protocol, and whether it is a transport of a store.
-
-Note that server accounts and accounts are relatively independent. While
-accounts refer to two server accounts, these server accounts can be
-used by other accounts as well.
-
-The reason two keep accounts and server accounts separately, is a bit of
-flexibility. In mobile use-cases, quite often it's desirable to use a
-network-specific smtp-server. The chosen structure makes it easy to iterate
-over all smtp-servers and find the right one.
-
-\chapter{Finding the Transport}
-One of the interesting topics in designing a mobile e-mail client is to deal
-with transports (in particular, \smtp). The reason for that is that the
-majority of \smtp-servers only allow e-mail from the same network. That means
-that for example {\tt smtp.some-isp.com} will only accept mail from ({\tt MAIL
- FROM:}) {\tt user@some-isp.com}, and refuse mail from {\tt
- user@some-other-isp.com}, unless the recipient {\tt RCPT TO:} is on the same
-network.
-
-To summarize:
-
-\footnote{Some smtp-servers {\bf will} accept mail
- from}
-
-
-
-\chapter*{Coding guidelines}
-When hacking on \modest, please honour these time-tested coding guidelines.
-First, please follow the {\em Linux CodingStyle guidelines}:\\
- {\tt /usr/src/linux/Documentation/CodingStyle}\\
-Then, read the {\em OSSO Coding Style Guidelines}:\\
- {\tt http://foo}
-Here are only some additional notes.
-
-Your editor may help you with this, for example for {\tt emacs}:
-\begin{verbatim}
- (c-set-style "K&R")
- (setq tab-width 8)
- (setq indent-tabs-mode t)
- (setq c-basic-offset 8)
-\end{verbatim}
-
-Or the equivalent in your favourite editor.
-
-Lines should not exceed 100 characters.
-
-Global functions (the ones in {\tt .h}-files) should be commented using
-doxygen-style comments.
-
-Furthermore, please follow 'conventional wisdom' for programming with
-GLib/GTK+/GObject. Some things to remember:
-\begin{itemize}
-\item {\tt g\_new}, {\tt g\_malloc} and friends {\bf never} return {\tt NULL}. They terminate
- the application if it happens (normally). No need to check for {\tt NULL} returns.
-\item {\tt g\_return\_if\_fail} and friends may be 'turned off', ie. they are
- to be used for error checking, but {\bf not} for your programming logic
-\end{itemize}
-
-To test for the validity of function parameters,
-% g_return_if_fail / g_return_val_if_fail
-
-ie.
-\begin{verbatim}
-double
-one_divided_by_x (double x)
-{
- g_return_val_if_fail ((x != 0), -1);
- return 1/x;
-}
-\end{verbatim}
-This will give us a warning (and a wrong answer) in case we do
-% one_divided_by_x (0);
-
-This is good for testing, but it's important to keep in mind that in
-production code the check may be turned off. The caller should make
-sure that the parameter is correct (ie. != 0 in this case).
-
-Now, if a similar check is actually part of the logic of a function,
-then {\tt g\_return\_if\_fail} should not be used, but instead, e.g.:
-\begin{verbatim}
-int
-stack_item_num (Stack *stack)
-{
- if (!stack)
- return 0;
-
- /* calculate item count */
-}
-\end{verbatim}
-\end{document}
<preface>
<title>Introduction</title>
- <para>modest is a lightweight e-mail program, built on top of
- tinymail and libcamel</para>
+
+ <para><application>modest</application> is a mail user agent
+ (<abbrev>MUA</abbrev>) targetting small devices, in particular Nokia's
+ <productname>Nokia 770 Internet Tablet</productname>. This document
+ describes the design and implementation of this software.
+ </para>
+
+ <para><application>modest</application> lives at the top of a extensive
+ stack of software. It is built on top
+ of <application>tinymail</application>, and uses its libcamel
+ backend. It strives to the be a simple yet powerful program, geared
+ towards small devices, for example (but not limited
+ to) <productname>Nokia's 770 internet tablet</productname>. An important
+ goal is to minimize memory usage while still being able to handle
+ significant amounts of email quickly; much of that is achieved simply by
+ using <application>tinymail</application>, which uses a number of clever
+ tricks for that, such as the proxy design pattern for listing email
+ headers, and not needing memory for headers which are not currently
+ visible.
+ </para>
+
+ <para>
+ <application>modest</application>, in turn, also tries to be efficient,
+ fast and scalable. That means that the <abbrev>MUA</abbrev> should
+ support multiple user-interfaces, perhaps making it even possible to
+ switch between them during runtime.
+ </para>
+
+ <para>To summarize the goals for <application>modest</application>:
+ <itemizedlist>
+ <listitem>target devices with limited amounts of memory ('limited' in 2006
+ terms means less than 64Mb, and of which only part can be used for
+ e-mail);</listitem>
+ <listitem>target Linux/Unix-like environments with GLib/GTK+-based
+ support;</listitem>
+ <listitem>support multiple user-interface (UIs) with as much code
+ sharing as possible between the different UIs.</listitem>
+ </itemizedlist></para>
+
+ <para>Like <application>tinymail</application>
+ and <application>libcamel</application>, <application>modest</application>
+ is programmed in C, using the <package>GObject</package>-system for
+ object-oriented (OO) features. For now, it specifically targets \gtk based
+ UIs (and derivatives like 'Hildon').</para>
+
</preface>
+
+ <part>
+ <title>Architecture</title>
+ <partintro>
+ <para><application>modest</application> tries to be quite flexible in its
+ design. However, it's always important not to make things too
+ generic. Both for reasons of time limitations and keeping the software
+ understandable and 'modest', it's important to limit the scope.
+ </para>
+
+ <para>
+ For <application>modest</application>, the following:
+ <itemizedlist>
+ <listitem><application>modest</application> is a e-mail program
+ using the <package>tinymail</package> and <package>camel</package>
+ libraries;</listitem>
+ <listitem><application>modest</application> targets gtk and
+ gconf-based user-interfaces, including the Hildon
+ environment;</listitem>
+ <listitem><application>modest</application> main use-case is in
+ small, mobile device such as the <productname>Nokia 770 Internet
+ Tablet</productname>;</listitem>
+ <listitem>However, effort is made also to
+ make <application>modest</application> usable as a general-purpose
+ e-mail client on normal desktop computer.</listitem>
+ </itemizedlist>
+ </para>
+ </partintro>
+ </part>
+
+ <part>
+ <title>Design</title>
+ <partintro>
+ <para>In this part, we'll discuss the design of various parts of
+ <application>modest</application>. We'll not go into the details of
+ various APIs in this chapter. Please consul the documentation generated
+ from the source code (<systemitem>gtk-doc</systemitem>) for that.</para>
+ </partintro>
+
+ <chapter>
+ <title>Configuration</title>
+ <para>Configuration is the part of <application>modest</application>
+ that deals with storing all settings. While the design allows for
+ alternative implementations, currently
+ only <systemitem>GConf</systemitem> is supported as a backend.
+ </para>
+
+ <para>
+ All dealing with configuration is done with
+ the <classname>ModestConf</classname>-class. It is declared
+ in <filename> modest-conf.h</filename>, and
+ the <systemitem>GConf</systemitem>-based implementation in
+ <filename>modest-conf-gconf.c</filename>. As said, there could be
+ different implementations --
+ nothing <systemitem>GConf</systemitem>-specific is visible in the
+ <classname>ModestConf</classname>-<abbrev>API</abbrev>.
+ </para>
+ </chapter>
+
+ <chapter>
+ <title>Account Management</title>
+ <para>
+ Account Management is the part of <application>modest</application>
+ that deals with the setting related to sending and receiving of
+ e-mail. We will follow the libcamel-convention of using the
+ term <emphasis> store</emphasis> for an e-mail storage/retrieval
+ server, and a <emphasis>transport</emphasis> for a server that
+ transports mail to its destination.
+ </para>
+
+ <para>
+ In practice, the following types are available:
+ <itemizedlist>
+ <listitem><emphasis>stores</emphasis>: <abbrev>POP</abbrev>
+ and <abbrev>IMAP</abbrev>; </listitem>
+ <listitem> <emphasis>transports</emphasis>: <systemitem>sendmail</systemitem>
+ and <abbrev>SMTP</abbrev>.</listitem>
+ </itemizedlist>
+ </para>
+
+ <sect1>
+ <title>Definitions</title>
+ <itemizedlist>
+ <listitem>An <emphasis>account</emphasis> is a named entity
+ consisting of a <emphasis>store</emphasis> and
+ a <emphasis>transport</emphasis>. Note: For our mobile use-cases,
+ the <emphasis>transport</emphasis> cannot be a static entity, but
+ may depend on the network connection. That is however not part of
+ Account Management, so not discussed here</listitem>
+ <listitem>A <emphasis>server account</emphasis> is account
+ describing the connection with a specific server. Server accounts
+ come in two type:
+ <itemizedlist>
+ <listitem>A <emphasis>transport</emphasis> describes the connection information
+ (servername, username, password etc.) for a transport
+ server;</listitem>
+ <listitem>A <emphasis>store</emphasis> describes the connection information for
+ a store server;</listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>Code</title>
+ <para>The functions to deal with account and server accounts are
+ located in <classname>ModestAccountMgr</classname>, ie. in
+ <filename>modest-account-mgr.[ch]</filename>. There function to add
+ specific values for both, to list the available ones, etc. Please
+ refer to the source code documentation for details.
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Location in configuration database</title>
+ <para>
+ <emphasis>Accounts</emphasis> can be found
+ in <systemitem>/apps/modest/accounts</systemitem>,
+ while <emphasis>server accounts</emphasis> can be found
+ in <systemitem>/app/modest/server_accounts</systemitem>.
+ </para>
+
+ <para>
+ The following image show an
+ account <systemitem>accountstest</systemitem> with server accounts
+ <systemitem>mystore</systemitem>
+ and <systemitem>mytransport</systemitem>.
+ <imagedata fileref="modest-account-mgr.png"/>
+ </para>
+
+ <para>
+ For each of the stores, there are number of parameters specified:
+ <itemizedlist>
+ <listitem><emphasis>hostname</emphasis> - the place where the server resides;</listitem>
+ <listitem><emphasis>username</emphasis> - the username;</listitem>
+ <listitem><emphasis>password</emphasis> - the password;</listitem>
+ <listitem><emphasis>proto</emphasis> - the protocal for communication with this server - for
+ now these are the following valid values (literal strings):
+ <itemizedlist>
+ <listitem><emphasis>sendmail</emphasis>;</listitem>
+ <listitem><emphasis>smtp</emphasis>;</listitem>
+ <listitem><emphasis>pop</emphasis></listitem>
+ <listitem><emphasis>imap</emphasis>.</listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>In the <filename>modest-proto.[ch]</filename> there are
+ various functions to check whether something is a valid protocol, and whether
+ it is a transport of a store.
+ </para>
+
+ <para>Note that server accounts and accounts are relatively independent. While
+ accounts refer to two server accounts, these server accounts can be
+ used by other accounts as well.
+ </para>
+
+ <para>The reason two keep accounts and server accounts separately, is a bit of
+ flexibility. In mobile use-cases, quite often it's desirable to use a
+ network-specific smtp-server. The chosen structure makes it easy to iterate
+ over all smtp-servers and find the right one.
+ </para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Finding the right transport</title>
+ <para>
+ One of the interesting topics in designing a mobile e-mail client is
+ to deal with transports (in
+ particular, <acronym>SMTP</acronym>). The reason for that is that
+ the majority of <acronym>SMTP</acronym>-servers only allow e-mail
+ from the same network. That means that for example <systemitem>
+ smtp.some-isp.com</systemitem> will only accept mail from
+ (<command>MAIL FROM:</command>) <systemitem>
+ user@some-isp.com</systemitem>, and refuse mail
+ from <systemitem>user@some-other-isp.com</systemitem>, unless the
+ recipient (<command>RCPT TO:</command>) is on the same network.
+ </para>
+ </chapter>
+ </part>
+
+ <chapter>
+ <title>Coding guidelines</title>
+ <para>
+ When hacking on \modest, please honour these time-tested coding guidelines.
+ First, please follow the <emphasis>Linux CodingStyle guidelines</emphasis>
+ (<filename>/usr/src/linux/Documentation/CodingStyle</filename>).
+ </para>
+
+ <para>
+ Here are only some additional notes.
+ </para>
+
+ <para>
+ Your editor may help you with this, for example for <application>emacs</application>:
+ <programlisting>
+ (c-set-style "K&R")
+ (setq tab-width 8)
+ (setq indent-tabs-mode t)
+ (setq c-basic-offset 8)
+ </programlisting>
+ </para>
+
+ <para>
+ Or the equivalent in your favourite editor.
+ </para>
+
+ <para>
+ Lines should not exceed 100 characters.
+ </para>
+
+ <para>Global functions (the ones in <filename>.h</filename>-files) should
+ be commented using
+ <systemitem>gtk-doc</systemitem>.
+ </para>
+
+ <para>
+ Furthermore, please follow 'conventional wisdom' for programming with
+ GLib/GTK+/GObject. Some things to remember:
+ <itemizedlist>
+ <listitem> <function>g_new</function>, <function>g_malloc</function> and
+ friends <emphasis>never</emphasis> return <function>NULL</function>. They terminate
+ the application if it happens (normally). No need to check
+ for <function>NULL</function> returns;</listitem>
+ <listitem> <function>g_return_if_fail</function> and friends may be
+ 'turned off', ie. they are to be used for error checking,
+ but <emphasis>not</emphasis> for your programming logic
+ </listitem>
+ </itemizedlist>
+ </para>
+ </chapter>
<chapter>
<title>Object Index</title>
projects / modest / commitdiff
