From 32646815a482886c48a779690acefdcf0e7f5980 Mon Sep 17 00:00:00 2001 From: Dan Winship Date: Mon, 28 Feb 2000 05:36:24 +0000 Subject: beginnings of a Camel white paper svn path=/trunk/; revision=1971 --- help/white-papers/mail/ChangeLog | 4 + help/white-papers/mail/camel.sgml | 268 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 272 insertions(+) create mode 100644 help/white-papers/mail/ChangeLog create mode 100644 help/white-papers/mail/camel.sgml (limited to 'help') 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 + + * 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 @@ +Evolution"> + +]> + +
+ + + The &Camel; Messaging Library + + + + Dan + Winship + +
+ danw@helixcode.com +
+ + + + + + 2000 + Helix Code, Inc. + + + + + + Introduction + + + &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. + + + + &Camel;'s initial design is heavily based on Sun's + JavaMail 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. + + + + + Overview + + + To begin using &Camel;, an application first creates a + CamelSession object. This object is used + to store application defaults, and to coordinate communication + between providers and the application. + + + + A CamelProvider 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. + + + + CamelService is an abstract class for + describing a connection to a local or remote service. It + currently has two subclasses: CamelStore, + for services that store messages (such as IMAP servers and mbox + files), and CamelTransport, 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. + + + + A CamelStore contains some number of + CamelFolder objects, which in turn + contain messages. A CamelFolder provides + a CamelFolderSummary 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 CamelMedium. + + + + Email messages are represented by the + CamelMimeMessage class, a subclass of + CamelMedium. This class includes + operations for accessing RFC822 and MIME headers, accessing + subparts of MIME messages, encoding and decoding Base64 and + Quoted-Printable, etc. + + + + CamelTransport includes methods for + delivering messages. While the abstract + CamelTransport::send method takes a + CamelMedium, its subclasses may only be + able to deliver messages of specific + CamelMedium subclasses. For instance, + CamelSendmailTransport requires a + CamelMimeMessage, because it needs a + message that includes a "To:" header. A hypothetical + CamelNNTPTransport would need a + CamelNewsMessage, which would have a + "Newsgroups:" header. + + + + The content of messages are referred to using + CamelStream and its subclasses. In the + case of an mbox-based store, the + CamelStream would abstract the operation + of reading the correct section of the mbox file. For IMAP, + reading off the CamelStream might result + in commands being issued to the remote IMAP server and data + being read off a socket. + + + + The final major class in &Camel; is + CamelException, which is used to + propagate information about errors. Many methods take a + CamelException 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. + + + + + Major Subcomponents + + + XXX + + + + The Message Store + + + A CamelStore inherits the ability to + connect and authenticate to a service from its parent class, + CamelService. It then adds the ability + to retrieve folders. A store must contain at least one folder, + which can be retrieved with + CamelStore::get_default_folder. There are + also methods to retrieve the "top-level" folder (for + hieararchical stores), and to retrieve an arbitrary folder by + name. + + + + All CamelFolders must implement certain + core operations, most notably generating a summary and + retrieving and deleting messages. A + CamelFolder must assign a permanently + unique identifier to each message it contains. Messages can + then be retrieved via + CamelFolder::get_message_by_uid. Alternately, + within a single mail-reading session, messages can be referred + to by their linear position within the store using + CamelFolder::get_message_by_number. + + + + Folders must also implement the + get_parent_folder and + list_subfolders 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). + + + + Folders that support searching can define the + search_by_expression 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. + + + + + Messages + + + As mentioned before, messages are represented by subclasses of + CamelMedium. + CamelMedium itself is a subclass of + CamelDataWrapper, a generic class for + connecting a typed data source to a data sink. + CamelMedium adds the concept of message + headers versus message body. + (CamelDataWrapper has one other + important subclass, CamelMultipart, + which is used to provide separate access to the multiple + independent parts of a multipart MIME type.) + CamelMedium's subclasses provide more + specialized handling of various headers: + CamelMimePart adds special handling for + the &ldquot;Content-*&rdquot; headers in MIME messages, and + its subclass CamelMimeMessage adds + handling for the RFC822 headers. + + + + Consider a message with two parts: a text part (in both plain + text and HTML), and an attached image: + + + + From: Dan Winship <danw@helixcode.com> + To: Matt Loper <matt@helixcode.com> + 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<br> + <br> + Check out this graphic and tell me if you think it works.<br> + <br> + -- Dan<br> + <br> + --sFSenbAFDSgDfg-- + + --jhTYrnsRrdhDFGa + Content-Type: image/png + Content-Transfer-Encoding: base64 + + F4JLw0ORrkRa8AwAMQJLAaI3UDIGsco9RAaB92... + --jhTYrnsRrdhDFGa-- + + + + In &Camel;, this would be represented as follows: + + + + + +
-- cgit