aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/white-papers/mail/ChangeLog4
-rw-r--r--doc/white-papers/mail/camel.sgml268
-rw-r--r--help/white-papers/mail/ChangeLog4
-rw-r--r--help/white-papers/mail/camel.sgml268
4 files changed, 544 insertions, 0 deletions
diff --git a/doc/white-papers/mail/ChangeLog b/doc/white-papers/mail/ChangeLog
new file mode 100644
index 0000000000..93bc1fd755
--- /dev/null
+++ b/doc/white-papers/mail/ChangeLog
@@ -0,0 +1,4 @@
+2000-02-28 Dan Winship <danw@helixcode.com>
+
+ * camel.sgml: Beginnings of a Camel white paper
+
diff --git a/doc/white-papers/mail/camel.sgml b/doc/white-papers/mail/camel.sgml
new file mode 100644
index 0000000000..c3471059b1
--- /dev/null
+++ b/doc/white-papers/mail/camel.sgml
@@ -0,0 +1,268 @@
+<!doctype article PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+<!entity Evolution "<application>Evolution</application>">
+<!entity Camel "Camel">
+]>
+
+<article class="whitepaper" id="camel">
+
+ <artheader>
+ <title>The &Camel; Messaging Library</title>
+
+ <authorgroup>
+ <author>
+ <firstname>Dan</firstname>
+ <surname>Winship</surname>
+ <affiliation>
+ <address>
+ <email>danw@helixcode.com</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ <copyright>
+ <year>2000</year>
+ <holder>Helix Code, Inc.</holder>
+ </copyright>
+
+ </artheader>
+
+ <sect1 id="introduction">
+ <title>Introduction</title>
+
+ <para>
+ &Camel; is a generic messaging library. It is being used as the
+ back end for the mail component of &Evolution;. The name
+ "&Camel;" is not an acronym; it refers to the fact that the
+ library is capable of going several days without food or water.
+ </para>
+
+ <para>
+ &Camel;'s initial design is heavily based on Sun's
+ <trademark>JavaMail</trademark> API. It uses the Gtk+ object
+ system, and many of its classes are direct analags of JavaMail
+ classes. Its design has also been influenced by the features of
+ IMAP, and the limitations of the standard UNIX mbox mail store,
+ which set some of the boundaries on its requirements and
+ extensibility.
+ </para>
+ </sect1>
+
+ <sect1 id="overview">
+ <title>Overview</title>
+
+ <para>
+ To begin using &Camel;, an application first creates a
+ <classname>CamelSession</classname> object. This object is used
+ to store application defaults, and to coordinate communication
+ between providers and the application.
+ </para>
+
+ <para>
+ A <classname>CamelProvider</classname> is a dynamically-loadable
+ module that provides functionality associated with a specific
+ service. Examples of providers are IMAP and SMTP. Providers
+ include subclasses of the various other &Camel; classes for
+ accessing and manipulating messages.
+ </para>
+
+ <para>
+ <classname>CamelService</classname> is an abstract class for
+ describing a connection to a local or remote service. It
+ currently has two subclasses: <classname>CamelStore</classname>,
+ for services that store messages (such as IMAP servers and mbox
+ files), and <classname>CamelTransport</classname>, for services
+ that deliver messages (such as SMTP, or a local MTA). A provider
+ could also be both a store and a transport, as in the case of
+ NNTP.
+ </para>
+
+ <para>
+ A <classname>CamelStore</classname> contains some number of
+ <classname>CamelFolder</classname> objects, which in turn
+ contain messages. A <classname>CamelFolder</classname> provides
+ a <classname>CamelFolderSummary</classname> object, which
+ includes details about the subject, date, and sender of each
+ message in the folder. The folder also includes the messages
+ themselves, as subclasses of <classname>CamelMedium</classname>.
+ </para>
+
+ <para>
+ Email messages are represented by the
+ <classname>CamelMimeMessage</classname> class, a subclass of
+ <classname>CamelMedium</classname>. This class includes
+ operations for accessing RFC822 and MIME headers, accessing
+ subparts of MIME messages, encoding and decoding Base64 and
+ Quoted-Printable, etc.
+ </para>
+
+ <para>
+ <classname>CamelTransport</classname> includes methods for
+ delivering messages. While the abstract
+ <function>CamelTransport::send</function> method takes a
+ <classname>CamelMedium</classname>, its subclasses may only be
+ able to deliver messages of specific
+ <classname>CamelMedium</classname> subclasses. For instance,
+ <classname>CamelSendmailTransport</classname> requires a
+ <classname>CamelMimeMessage</classname>, because it needs a
+ message that includes a "To:" header. A hypothetical
+ <classname>CamelNNTPTransport</classname> would need a
+ <classname>CamelNewsMessage</classname>, which would have a
+ "Newsgroups:" header.
+ </para>
+
+ <para>
+ The content of messages are referred to using
+ <classname>CamelStream</classname> and its subclasses. In the
+ case of an mbox-based store, the
+ <classname>CamelStream</classname> would abstract the operation
+ of reading the correct section of the mbox file. For IMAP,
+ reading off the <classname>CamelStream</classname> might result
+ in commands being issued to the remote IMAP server and data
+ being read off a socket.
+ </para>
+
+ <para>
+ The final major class in &Camel; is
+ <classname>CamelException</classname>, which is used to
+ propagate information about errors. Many methods take a
+ <classname>CamelException</classname> as an argument, which the
+ caller can then check if an error occurs. It includes both a
+ numeric error code which can be interpreted by the program, and
+ a text error message that can be displayed to the user.
+ </para>
+ </sect1>
+
+ <sect1 id="classes">
+ <title>Major Subcomponents</title>
+
+ <para>
+ XXX
+ </para>
+
+ <sect2 id="store">
+ <title>The Message Store</title>
+
+ <para>
+ A <classname>CamelStore</classname> inherits the ability to
+ connect and authenticate to a service from its parent class,
+ <classname>CamelService</classname>. It then adds the ability
+ to retrieve folders. A store must contain at least one folder,
+ which can be retrieved with
+ <function>CamelStore::get_default_folder</function>. There are
+ also methods to retrieve the "top-level" folder (for
+ hieararchical stores), and to retrieve an arbitrary folder by
+ name.
+ </para>
+
+ <para>
+ All <classname>CamelFolder</classname>s must implement certain
+ core operations, most notably generating a summary and
+ retrieving and deleting messages. A
+ <classname>CamelFolder</classname> must assign a permanently
+ unique identifier to each message it contains. Messages can
+ then be retrieved via
+ <function>CamelFolder::get_message_by_uid</function>. Alternately,
+ within a single mail-reading session, messages can be referred
+ to by their linear position within the store using
+ <function>CamelFolder::get_message_by_number</function>.
+ </para>
+
+ <para>
+ Folders must also implement the
+ <function>get_parent_folder</function> and
+ <function>list_subfolders</function> methods. For stores that
+ don't allow multiple folders, they would return NULL and an
+ empty list, respectively. Stores that do allow multiple
+ folders will also define methods for creating and deleting
+ folders, and for moving messages between them (assuming the
+ folders are writable).
+ </para>
+
+ <para>
+ Folders that support searching can define the
+ <function>search_by_expression</function> method. For mbox
+ folders, this is implemented by indexing the messages with the
+ ibex library and using that to search them later. For IMAP
+ folders, this uses the IMAP SEARCH command. Other folder types
+ might not be able to implement this functionality, in which
+ case users would not be able to do full-content searches on
+ them.
+ </para>
+ </sect2>
+
+ <sect2 id="messages">
+ <title>Messages</title>
+
+ <para>
+ As mentioned before, messages are represented by subclasses of
+ <classname>CamelMedium</classname>.
+ <classname>CamelMedium</classname> itself is a subclass of
+ <classname>CamelDataWrapper</classname>, a generic class for
+ connecting a typed data source to a data sink.
+ <classname>CamelMedium</classname> adds the concept of message
+ headers versus message body.
+ (<classname>CamelDataWrapper</classname> has one other
+ important subclass, <classname>CamelMultipart</classname>,
+ which is used to provide separate access to the multiple
+ independent parts of a multipart MIME type.)
+ <classname>CamelMedium</classname>'s subclasses provide more
+ specialized handling of various headers:
+ <classname>CamelMimePart</classname> adds special handling for
+ the &ldquot;Content-*&rdquot; headers in MIME messages, and
+ its subclass <classname>CamelMimeMessage</classname> adds
+ handling for the RFC822 headers.
+ </para>
+
+ <para>
+ Consider a message with two parts: a text part (in both plain
+ text and HTML), and an attached image:
+
+ <programlisting>
+
+ From: Dan Winship &lt;danw@helixcode.com&gt;
+ To: Matt Loper &lt;matt@helixcode.com&gt;
+ Subject: the Camel white paper
+ MIME-Version: 1.0
+ Content-Type: multipart/mixed; boundary="jhTYrnsRrdhDFGa"
+
+ This is a multi-part message in MIME format.
+ --jhTYrnsRrdhDFGa
+ Content-Type: multipart/alternative; boundary="sFSenbAFDSgDfg"
+
+ --sFSenbAFDSgDfg
+ Content-Type: text/plain
+
+ Hey, Matt
+
+ Check out this graphic and tell me if you think it works.
+
+ -- Dan
+
+ --sFSenbAFDSgDfg
+ Content-Type: text/html
+
+ Hey, Matt&lt;br&gt;
+ &lt;br&gt;
+ Check out this graphic and tell me if you think it works.&lt;br&gt;
+ &lt;br&gt;
+ -- Dan&lt;br&gt;
+ &lt;br&gt;
+ --sFSenbAFDSgDfg--
+
+ --jhTYrnsRrdhDFGa
+ Content-Type: image/png
+ Content-Transfer-Encoding: base64
+
+ F4JLw0ORrkRa8AwAMQJLAaI3UDIGsco9RAaB92...
+ --jhTYrnsRrdhDFGa--
+ </programlisting>
+
+ <para>
+ In &Camel;, this would be represented as follows:
+ </para>
+
+ <graphic fileref="samplemsg"></graphic>
+ </sect2>
+
+</article>
diff --git a/help/white-papers/mail/ChangeLog b/help/white-papers/mail/ChangeLog
new file mode 100644
index 0000000000..93bc1fd755
--- /dev/null
+++ b/help/white-papers/mail/ChangeLog
@@ -0,0 +1,4 @@
+2000-02-28 Dan Winship <danw@helixcode.com>
+
+ * camel.sgml: Beginnings of a Camel white paper
+
diff --git a/help/white-papers/mail/camel.sgml b/help/white-papers/mail/camel.sgml
new file mode 100644
index 0000000000..c3471059b1
--- /dev/null
+++ b/help/white-papers/mail/camel.sgml
@@ -0,0 +1,268 @@
+<!doctype article PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+<!entity Evolution "<application>Evolution</application>">
+<!entity Camel "Camel">
+]>
+
+<article class="whitepaper" id="camel">
+
+ <artheader>
+ <title>The &Camel; Messaging Library</title>
+
+ <authorgroup>
+ <author>
+ <firstname>Dan</firstname>
+ <surname>Winship</surname>
+ <affiliation>
+ <address>
+ <email>danw@helixcode.com</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ <copyright>
+ <year>2000</year>
+ <holder>Helix Code, Inc.</holder>
+ </copyright>
+
+ </artheader>
+
+ <sect1 id="introduction">
+ <title>Introduction</title>
+
+ <para>
+ &Camel; is a generic messaging library. It is being used as the
+ back end for the mail component of &Evolution;. The name
+ "&Camel;" is not an acronym; it refers to the fact that the
+ library is capable of going several days without food or water.
+ </para>
+
+ <para>
+ &Camel;'s initial design is heavily based on Sun's
+ <trademark>JavaMail</trademark> API. It uses the Gtk+ object
+ system, and many of its classes are direct analags of JavaMail
+ classes. Its design has also been influenced by the features of
+ IMAP, and the limitations of the standard UNIX mbox mail store,
+ which set some of the boundaries on its requirements and
+ extensibility.
+ </para>
+ </sect1>
+
+ <sect1 id="overview">
+ <title>Overview</title>
+
+ <para>
+ To begin using &Camel;, an application first creates a
+ <classname>CamelSession</classname> object. This object is used
+ to store application defaults, and to coordinate communication
+ between providers and the application.
+ </para>
+
+ <para>
+ A <classname>CamelProvider</classname> is a dynamically-loadable
+ module that provides functionality associated with a specific
+ service. Examples of providers are IMAP and SMTP. Providers
+ include subclasses of the various other &Camel; classes for
+ accessing and manipulating messages.
+ </para>
+
+ <para>
+ <classname>CamelService</classname> is an abstract class for
+ describing a connection to a local or remote service. It
+ currently has two subclasses: <classname>CamelStore</classname>,
+ for services that store messages (such as IMAP servers and mbox
+ files), and <classname>CamelTransport</classname>, for services
+ that deliver messages (such as SMTP, or a local MTA). A provider
+ could also be both a store and a transport, as in the case of
+ NNTP.
+ </para>
+
+ <para>
+ A <classname>CamelStore</classname> contains some number of
+ <classname>CamelFolder</classname> objects, which in turn
+ contain messages. A <classname>CamelFolder</classname> provides
+ a <classname>CamelFolderSummary</classname> object, which
+ includes details about the subject, date, and sender of each
+ message in the folder. The folder also includes the messages
+ themselves, as subclasses of <classname>CamelMedium</classname>.
+ </para>
+
+ <para>
+ Email messages are represented by the
+ <classname>CamelMimeMessage</classname> class, a subclass of
+ <classname>CamelMedium</classname>. This class includes
+ operations for accessing RFC822 and MIME headers, accessing
+ subparts of MIME messages, encoding and decoding Base64 and
+ Quoted-Printable, etc.
+ </para>
+
+ <para>
+ <classname>CamelTransport</classname> includes methods for
+ delivering messages. While the abstract
+ <function>CamelTransport::send</function> method takes a
+ <classname>CamelMedium</classname>, its subclasses may only be
+ able to deliver messages of specific
+ <classname>CamelMedium</classname> subclasses. For instance,
+ <classname>CamelSendmailTransport</classname> requires a
+ <classname>CamelMimeMessage</classname>, because it needs a
+ message that includes a "To:" header. A hypothetical
+ <classname>CamelNNTPTransport</classname> would need a
+ <classname>CamelNewsMessage</classname>, which would have a
+ "Newsgroups:" header.
+ </para>
+
+ <para>
+ The content of messages are referred to using
+ <classname>CamelStream</classname> and its subclasses. In the
+ case of an mbox-based store, the
+ <classname>CamelStream</classname> would abstract the operation
+ of reading the correct section of the mbox file. For IMAP,
+ reading off the <classname>CamelStream</classname> might result
+ in commands being issued to the remote IMAP server and data
+ being read off a socket.
+ </para>
+
+ <para>
+ The final major class in &Camel; is
+ <classname>CamelException</classname>, which is used to
+ propagate information about errors. Many methods take a
+ <classname>CamelException</classname> as an argument, which the
+ caller can then check if an error occurs. It includes both a
+ numeric error code which can be interpreted by the program, and
+ a text error message that can be displayed to the user.
+ </para>
+ </sect1>
+
+ <sect1 id="classes">
+ <title>Major Subcomponents</title>
+
+ <para>
+ XXX
+ </para>
+
+ <sect2 id="store">
+ <title>The Message Store</title>
+
+ <para>
+ A <classname>CamelStore</classname> inherits the ability to
+ connect and authenticate to a service from its parent class,
+ <classname>CamelService</classname>. It then adds the ability
+ to retrieve folders. A store must contain at least one folder,
+ which can be retrieved with
+ <function>CamelStore::get_default_folder</function>. There are
+ also methods to retrieve the "top-level" folder (for
+ hieararchical stores), and to retrieve an arbitrary folder by
+ name.
+ </para>
+
+ <para>
+ All <classname>CamelFolder</classname>s must implement certain
+ core operations, most notably generating a summary and
+ retrieving and deleting messages. A
+ <classname>CamelFolder</classname> must assign a permanently
+ unique identifier to each message it contains. Messages can
+ then be retrieved via
+ <function>CamelFolder::get_message_by_uid</function>. Alternately,
+ within a single mail-reading session, messages can be referred
+ to by their linear position within the store using
+ <function>CamelFolder::get_message_by_number</function>.
+ </para>
+
+ <para>
+ Folders must also implement the
+ <function>get_parent_folder</function> and
+ <function>list_subfolders</function> methods. For stores that
+ don't allow multiple folders, they would return NULL and an
+ empty list, respectively. Stores that do allow multiple
+ folders will also define methods for creating and deleting
+ folders, and for moving messages between them (assuming the
+ folders are writable).
+ </para>
+
+ <para>
+ Folders that support searching can define the
+ <function>search_by_expression</function> method. For mbox
+ folders, this is implemented by indexing the messages with the
+ ibex library and using that to search them later. For IMAP
+ folders, this uses the IMAP SEARCH command. Other folder types
+ might not be able to implement this functionality, in which
+ case users would not be able to do full-content searches on
+ them.
+ </para>
+ </sect2>
+
+ <sect2 id="messages">
+ <title>Messages</title>
+
+ <para>
+ As mentioned before, messages are represented by subclasses of
+ <classname>CamelMedium</classname>.
+ <classname>CamelMedium</classname> itself is a subclass of
+ <classname>CamelDataWrapper</classname>, a generic class for
+ connecting a typed data source to a data sink.
+ <classname>CamelMedium</classname> adds the concept of message
+ headers versus message body.
+ (<classname>CamelDataWrapper</classname> has one other
+ important subclass, <classname>CamelMultipart</classname>,
+ which is used to provide separate access to the multiple
+ independent parts of a multipart MIME type.)
+ <classname>CamelMedium</classname>'s subclasses provide more
+ specialized handling of various headers:
+ <classname>CamelMimePart</classname> adds special handling for
+ the &ldquot;Content-*&rdquot; headers in MIME messages, and
+ its subclass <classname>CamelMimeMessage</classname> adds
+ handling for the RFC822 headers.
+ </para>
+
+ <para>
+ Consider a message with two parts: a text part (in both plain
+ text and HTML), and an attached image:
+
+ <programlisting>
+
+ From: Dan Winship &lt;danw@helixcode.com&gt;
+ To: Matt Loper &lt;matt@helixcode.com&gt;
+ Subject: the Camel white paper
+ MIME-Version: 1.0
+ Content-Type: multipart/mixed; boundary="jhTYrnsRrdhDFGa"
+
+ This is a multi-part message in MIME format.
+ --jhTYrnsRrdhDFGa
+ Content-Type: multipart/alternative; boundary="sFSenbAFDSgDfg"
+
+ --sFSenbAFDSgDfg
+ Content-Type: text/plain
+
+ Hey, Matt
+
+ Check out this graphic and tell me if you think it works.
+
+ -- Dan
+
+ --sFSenbAFDSgDfg
+ Content-Type: text/html
+
+ Hey, Matt&lt;br&gt;
+ &lt;br&gt;
+ Check out this graphic and tell me if you think it works.&lt;br&gt;
+ &lt;br&gt;
+ -- Dan&lt;br&gt;
+ &lt;br&gt;
+ --sFSenbAFDSgDfg--
+
+ --jhTYrnsRrdhDFGa
+ Content-Type: image/png
+ Content-Transfer-Encoding: base64
+
+ F4JLw0ORrkRa8AwAMQJLAaI3UDIGsco9RAaB92...
+ --jhTYrnsRrdhDFGa--
+ </programlisting>
+
+ <para>
+ In &Camel;, this would be represented as follows:
+ </para>
+
+ <graphic fileref="samplemsg"></graphic>
+ </sect2>
+
+</article>