diff options
Diffstat (limited to 'doc/OLD/HTML/bincimap-tech.html')
| -rw-r--r-- | doc/OLD/HTML/bincimap-tech.html | 503 |
1 files changed, 503 insertions, 0 deletions
diff --git a/doc/OLD/HTML/bincimap-tech.html b/doc/OLD/HTML/bincimap-tech.html new file mode 100644 index 0000000..e5fce32 --- /dev/null +++ b/doc/OLD/HTML/bincimap-tech.html @@ -0,0 +1,503 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<HTML> + +<HEAD> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> + <META HTTP-EQUIV="Content-Language" CONTENT="en"> + + <TITLE>Binc IMAP - Technical Documentation</TITLE> + <META NAME="revisit-after" CONTENT="14 days"> + <META NAME="keywords" CONTENT="Binc IMAP technical documentation checkpassword daemontools tcpserver xinetd Maildir qmail"> + <META NAME="description" CONTENT="Andreas Aardal Hanssen"> + <META NAME="copyright" CONTENT="Copyright Andreas Aardal Hanssen 2002, 2003"> + <META NAME="distribution" CONTENT="global"> + <META NAME="author" CONTENT="Andreas Aardal Hanssen"> + <LINK REL="stylesheet" HREF="bincimap.css" TYPE="text/css"> + <LINK REL="icon" HREF="/favicon.ico" TYPE="image/ico"> + <LINK REL="shortcut icon" HREF="/favicon.ico"> + +</HEAD> + +<BODY BGCOLOR="#000000"> + +<TABLE WIDTH="95%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> +<TR> +<TD BGCOLOR="#004444"> + +<TABLE WIDTH="99%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> + <TR> + <TD CLASS="headtext" BGCOLOR="#226666" ALIGN="LEFT"> + <TABLE> + <TR> + <TD ALIGN="center" VALIGN="middle"><IMG ALT="Binc IMAP logo" SRC="b-button64.png" BORDER="0"></TD> + <TD ALIGN="center" VALIGN="middle">Binc IMAP - Technical Documentation</TD> + </TR> + </TABLE> + </TD> + <TD CLASS="bodytext" BGCOLOR="#226666" ALIGN="RIGHT"> + <A HREF="http://www.gnu.org/licenses/gpl.html">GNU General Public License</A><BR> + Andreas Aardal Hanssen <andreas@hanssen.name> + </TD> + </TR> + <TR> + <TD CLASS="bodytext" BGCOLOR="#FFFFFF" COLSPAN="2"></TD> + </TR> +</TABLE> + +<DIV CLASS="bodytext"> + +<P><U><B>Binc in my home area, IMAPdir and cousins</B></U></P> + +<BLOCKQUOTE> + +<P>Binc IMAP uses either <A +HREF="http://www.inter7.com/courierimap/README.maildirquota.html">Maildir++</A> +or a structure called <A HREF="bincimap-imapdir.html">IMAPdir</A> to +store its set of mailboxes. <A +HREF="bincimap-imapdir.html">IMAPdir</A> is more or less similar to <A +HREF="http://www.inter7.com/courierimap/README.maildirquota.html">Maildir++</A>, +but it provides more flexibility with regards to mailbox names and +hierarchy structure.</P> + +<P>In a sense, <A HREF="bincimap-imapdir.html">IMAPdir</A> takes all +the goods from <A +HREF="http://cr.yp.to/proto/maildir.html">Maildir</A> and adds root +level mailboxes, submailboxes both of regular root level mailboxes and +of the special mailbox INBOX, mail in mailboxes of any level, and with +no restrictions.</P> + +<P>In the root of the <A HREF="bincimap-imapdir.html">IMAPdir</A> +structure, Binc IMAP stores the list of a user's subscribed folders in +a file called +<B>bincimap-subscribed</B>. This file should only be edited manually +if you are confident with <B>Binc::Storage</B>. Normally the +administrator and the IMAP user will leave this to Binc IMAP.</P> + +<P>Binc IMAP's <A +HREF="http://cr.yp.to/proto/maildir.html">Maildir</A> backend +(default) will temporarily create a lock file called +<B>bincimap-scan-lock</B> inside a <A +HREF="http://cr.yp.to/proto/maildir.html">Maildir</A> when it is +scanning for mailbox changes and delegating unique message +identifiers. This is to ensure that UIDs are delegated exactly once to +every message that has been detected by any one Binc IMAP server +instance.</P> + +<P>Inside each <A +HREF="http://cr.yp.to/proto/maildir.html">Maildir</A>, Binc IMAP +stores two files that allow multiple instances of the server to +communicate the state and changes of the mailbox: +<B>bincimap-uidvalidity</B> and +<B>bincimap-cache</B>. These files are safe to delete, although that +will trigger UIDVALIDITY to bounce and clients may have to +resynchronize their local state.</P> + +</BLOCKQUOTE> + +<P><U><B>Object Oriented Design: Brokers, Depots, Operators.</B></U></P> + +<BLOCKQUOTE> + +<TABLE WIDTH="100%"> + <TR> + <TD VALIGN="TOP"> + <P>Binc IMAP's design is <I>simple</I> and <I>modular</I>. This + makes it <I>easy</I> to maintain and extend.</P> + + <P>Although the IMAP protocol is relatively complex, you will + find that Binc IMAP's solution is surprisingly easy to + grasp.</P> + + <P>At the heart of Binc IMAP's implementation lies the basic + functionality for Object Oriented Design provided by the ISO C++ + standard and general knowledge in the area of standard Design + Patterns.</P> + + <P>The main components are:</P> + + <UL> + <LI>The <A HREF="#Broker">Broker</A></LI> + <LI>The <A HREF="#BrokerFactory">BrokerFactory</A></LI> + <LI>The <A HREF="#Command">Command</A></LI> + <LI>The <A HREF="#Depot">Depot</A></LI> + <LI>The <A HREF="#DepotFactory">DepotFactory</A></LI> + <LI>The <A HREF="#Mailbox">Mailbox</A></LI> + <LI>The <A HREF="#Operator">Operator</A></LI> + <LI>The <A HREF="#Session">Session</A></LI> + <LI>The <A HREF="#IO">IO</A></LI> + </UL> + </TD> + <TD> + <IMG BORDER="0" SRC="bincimap-design-tiny.png" ALT="Binc IMAP, Object Oriented Design"> + </TD> + </TR> +</TABLE> + +<HR> +<A NAME="Broker"><B>Broker</B></A> + + <P>One <A HREF="#Broker">Broker</A> holds a set of <A + HREF="#Operator">Operators</A>. For each + <I>state</I> Binc IMAP is in, the <A + HREF="#BrokerFactory">BrokerFactory</A> delegates exactly one <A + HREF="#Broker">Broker</A> to hold the relevant <A + HREF="#Operator">Operator</A> objects.</P> + + <P>Typically, an <A HREF="#Operator">Operator</A> can be assigned to + more than one <A HREF="#Broker">Broker</A>. For example, the <A + HREF="#Operator">Operator</A> that serves the IMAP command "NOOP" (a + command that is available in all three IMAP <I>states</I>), + <B>NoopOperator</B>, is available in all <A + HREF="#Broker">Broker</A> objects.</P> + + <P>The <A HREF="#Broker">Broker</A> is responsible for first passing + the <A HREF="#Depot">Depot</A> and the <A HREF="#IO">IO</A> + singleton to the appropriate <A HREF="#Operator">Operator</A>, + generating a <A HREF="#Command">Command</A> object.</P> + + <P>The <A HREF="#Broker">Broker</A> is also responsible for passing + the resulting <A HREF="#Command">Command</A> object to the <A + HREF="#Operator">Operator</A> together with the <A + HREF="#Depot">Depot</A>, generating the <I>untagged responses</I> + that come as a result of the processing.</P> + + <BR> + <TABLE> + <TR> + <TD BGCOLOR="#555555"> + <PRE> +Broker *broker = BrokerFactory.getBroker(STATE_SELECTED); +if (broker != NULL) + throw CriticalException("no broker for selected state"); + +Command command; + +try { + broker.parse(com, command); + broker.process(depot, command); +} catch (... + </PRE> + </TD> + </TR> + </TABLE> + +<HR> +<A NAME="BrokerFactory"><B>BrokerFactory</B></A> + + <P>The <A HREF="#BrokerFactory">BrokerFactory</A> manages the <A + HREF="#Broker">Broker</A> objects.</P> + + <P>Given a <I>state</I>, the <A + HREF="#BrokerFactory">BrokerFactory</A> provides a <A + HREF="#Broker">Broker</A> that holds all the <A + HREF="#Operator">Operator</A> objects available to the client.</P> + + <P>This provides a modular and safe separation of the priviledges + available at the different <I>states</I> in the IMAP session.</P> + + <P>The <I>preauthenticate stub</I> has a <A + HREF="#BrokerFactory">BrokerFactory</A> that can only generate <A + HREF="#Broker">Broker</A> objects for the <I>non-authenticated</I> + state.</P> + +<HR> +<A NAME="Command"><B>Command</B></A> + + <P>A <A HREF="#Command">Command</A> object holds all information + that was passed to the <A HREF="#Operator">Operator</A> that served + a specific IMAP command.</P> + + <P><A HREF="#Command">Command</A> objects are named. Examples of + such names are "CHECK", "SUBSCRIBE" and "LOGOUT".</P> + + <P>For the name "FETCH", the <A HREF="#Command">Command</A> object + is decorated with + <I>sequence set</I>, optionally a <I>section</I> and so on. The + <B>parse()</B> method in each <A HREF="#Operator">Operator</A> is + responsible for decorating the <A HREF="#Command">Command</A> + object.</P> + + <P>The <A HREF="#Command">Command</A> object is + <I>short-lived</I>. It is created, decorated, passed on to the <A + HREF="#Operator">Operator</A>, then discarded.</P> + +<HR> +<A NAME="Depot"><B>Depot</B></A> + + <P>A <A HREF="#Depot">Depot</A> is responsible for handling the + different <A HREF="#Mailbox">Mailbox</A> objects, and it is the + mailbox structure authority.</P> + + <P>Given an IMAP mailbox path as input, a <A HREF="#Depot">Depot</A> + can give the caller a corresponding <A HREF="#Mailbox">Mailbox</A> + object if it finds one that successfully identifies the type of <A + HREF="#Mailbox">Mailbox</A>. + + <P>The <A HREF="#Depot">Depot</A> is also aware of what the + <I>default</I> <A HREF="#Mailbox">Mailbox</A> type object is. This + <A HREF="#Mailbox">Mailbox</A> object is used when creating new IMAP + mailboxes.</P> + + <P>Finally, the <A HREF="#Depot">Depot</A> is used to translate + mailbox names to a representation on the file system and back. There + are currently two specializations of the <A HREF="#Depot">Depot</A> + object available: one for <A + HREF="http://www.inter7.com/courierimap/README.maildirquota.html">Maildir++</A> + and one for <A HREF="bincimap-imapdir.html">IMAPdir</A>. Each has + its own characteristics in how do translate the mailbox hierarchy to + the file system.</P> + + <TABLE> + <TR> + <TD BGCOLOR="#555555"> + <PRE> +Mailbox *mailbox = depot.getDefaultMailbox(); +if (mailbox == NULL) + throw CriticalException("no default mailbox provided"); + +try { + mailbox->imapCreate("work/2003/07/todo"); +} catch (... + </PRE> + </TD> + </TR> + </TABLE> + +<HR> +<A NAME="DepotFactory"><B>DepotFactory</B></A> + + <P>The <A NAME="DepotFactory">DepotFactory</A> manages the <A + HREF="#Depot">Depot</A> objects.</P> + + <P>New <A HREF="#Depot">Depot</A> objects are assigned to the <A + NAME="DepotFactory">DepotFactory</A> in runtime. This makes it easy + to add new <A HREF="#Depot">Depot</A> objects using loadable + modules. The <A HREF="#Depot">Depot</A> objects are registered and + accessed via their <I>names</I>, such as "<A + HREF="http://www.inter7.com/courierimap/README.maildirquota.html">Maildir++</A>" + or "<A HREF="bincimap-imapdir.html">IMAPdir</A>".</P> + + <P>The <A NAME="DepotFactory">DepotFactory</A> gives individual + users of Binc IMAP the option to choose the <A + HREF="#Depot">Depot</A> object that suits their needs the best.</P> + +<HR> +<A NAME="IO"><B>IO</B></A> + + <P>The <A HREF="#IO">IO</A> is a <I>global</I>. It consists of two instances - + <U>com</U> and <U>logger</U>.</P> + + <P><U>com</U> reads and writes characters to and from the client, + and hides the optional SSL encryption.</P> + + <P><U>logger</U> writes characters to Binc IMAP's log files. It + hides the method used to log data. Currently it supports logging to + stderr and syslog.</P> + +<HR> +<A NAME="Mailbox"><B>Mailbox</B></A> + + <P>The <A HREF="#Mailbox">Mailbox</A> is an abstract for Binc IMAP's different + <I>backends</I>. Bundled with Binc is a backend for <A + HREF="http://cr.yp.to/proto/maildir.html">Maildir</A>. The class + Maildir <I>inherits</I> <A HREF="#Mailbox">Mailbox</A>.</P> + + <P>In short, a <A HREF="#Mailbox">Mailbox</A> contains all methods needed for Binc + IMAP to serve a specific backend. It also holds a method to identify + a <A HREF="#Mailbox">Mailbox</A> of its own kind.</P> + + <P>All registered <A HREF="#Mailbox">Mailbox</A> objects are held by the + <A HREF="#Depot">Depot</A>.</P> + + <BR> + <TABLE> + <TR> + <TD BGCOLOR="#555555"> + <PRE> +Mailbox *mailbox = depot.getSelectedMailbox(); +if (mailbox == NULL) + throw CriticalException("no selected mailbox in selected state"); + +mailbox->imapExpunge(); +mailbox->imapClose(); + </PRE> + </TD> + </TR> + </TABLE> + +<HR> +<A NAME="Operator"><B>Operator</B></A> + + <P>An <A HREF="#Operator">Operator</A> is associated with an IMAP command such as + "SEARCH" or "AUTHENTICATE". In short, the <A HREF="#Operator">Operator</A> is used to + perform an arbitrary operation on a <A HREF="#Mailbox">Mailbox</A>.<P> + + <P>Typically, an <A HREF="#Operator">Operator</A> can be assigned to one or more + <A HREF="#Broker">Broker</A> objects. + + <P>Operators contain, among others, the two public methods: + <B>parse()</B> and <B>process()</B>.</P> + + <P>When given the <B>IO singleton</B> as input, the <B>parse()</B> + method generates a <A HREF="#Command">Command</A> object. This object can then be + fed to <B>process()</B> together with a <A HREF="#Depot">Depot</A>.</P> + + <P>When processing its command, an <A HREF="#Operator">Operator</A> is allowed to + generate <I>untagged responses</I> and it can also update the + <I>state</I> of a <A HREF="#Mailbox">Mailbox</A>, the <A HREF="#Depot">Depot</A> or the + <A HREF="#Session">Session</A> singleton.</P> + + <P><A HREF="#Operator">Operator</A> objects are assigned + <I>dynamically</I> to each <A HREF="#Broker">Broker</A>, making it + very easy to write + <I>extensions</I> that add or replace existing <A + HREF="#Operator">Operator</A> objects using Binc IMAP's <I>loadable + module support.</I></P> + +<HR> +<A NAME="Session"><B>Session</B></A> + + <P>The <A HREF="#Session">Session</A> is a <I>singleton</I> object that holds + information that is relevant to the current IMAP session.</P> + + <P>Currently, the <A HREF="#Session">Session</A> contains information about:</P> + + <UL> + <LI>Global configuration (administrator settings)</LI> + <LI>Local configuration (user settings)</LI> + <LI>Command line arguments</LI> + <LI>Folder subscription list</LI> + </UL> + +<HR> + +<P>Last updated on <B>2003-03-20</B>.</P> + +<P>Please direct comments on this document to the <A +HREF="/#mailinglist">Binc IMAP mailing list</A>. Remember to <I>search +the archives</I> first.</P> + +</BLOCKQUOTE> + +<TABLE WIDTH="99%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> + <TR> + <TD CLASS="bodytext" BGCOLOR="#FFFFFF"></TD> + </TR> + <TR> + <TD CLASS="headtext" BGCOLOR="#226666"> + <A HREF="http://validator.w3.org/check/referer"> + <IMG BORDER="0" SRC="http://www.w3.org/Icons/valid-html401" + ALT="Valid HTML 4.01!" HEIGHT="31" WIDTH="88"> + </A> + <A HREF="http://cr.yp.to/djbdns.html"><IMG BORDER="0" WIDTH="88" + HEIGHT="31" SRC="djbdns.jpg" ALT="Powered by djbdns!"></A> + <IMG BORDER="0" WIDTH="88" HEIGHT="30" SRC="binclogo.gif" + ALT="Powered by Binc IMAP"> + </TD> + </TR> +</TABLE> + +</DIV> +</TD> +</TR> +</TABLE> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> + +</BODY> +</HTML> +style with only LF. The MaildirMessage is an + implementation of Message used in Maildir. When using a Maildir + mailbox, Mailbox::iterator will return a reference to a + MaildirMessage. MaildirMessage also uses a MaildirMessageCache + singleton to handle cacheing of messages.</P> + + <P>Although the inside of MaildirMessage both deals with files, + cacheing and MIME, the Operator needs not think about this.</P> + +</BLOCKQUOTE> + +<HR> +<A NAME="Operator"><B>Operator</B></A> +<BLOCKQUOTE> + + <P>An <A HREF="#Operator">Operator</A> is associated with an IMAP command such as + "SEARCH" or "AUTHENTICATE". In short, the <A HREF="#Operator">Operator</A> is used to + perform an arbitrary operation on a <A HREF="#Mailbox">Mailbox</A>.<P> + + <P>Typically, an <A HREF="#Operator">Operator</A> can be assigned to one or more + <A HREF="#Broker">Broker</A> objects. + + <P>Operators contain, among others, the two public methods: + <B>parse()</B> and <B>process()</B>.</P> + + <P>The <B>parse()</B> method decorates a <A + HREF="#Request">Request</A> object. This object can then be fed to + <B>process()</B> together with a <A HREF="#Depot">Depot</A>.</P> + + <P>When processing its request, an <A HREF="#Operator">Operator</A> + is allowed to generate <I>untagged responses</I> and it can also + update the <I>state</I> of a <A HREF="#Mailbox">Mailbox</A>, the <A + HREF="#Depot">Depot</A> or the <A HREF="#Session">Session</A> + singleton.</P> + + <P><A HREF="#Operator">Operator</A> objects are assigned + <I>dynamically</I> to each <A HREF="#Broker">Broker</A>, making it + very easy to write <I>extensions</I> that add or replace existing <A + HREF="#Operator">Operator</A> objects using Binc IMAP's <I>loadable + module support.</I></P> +</BLOCKQUOTE> + +<HR> +<A NAME="Session"><B>Session</B></A> +<BLOCKQUOTE> + <P>The <A HREF="#Session">Session</A> is a <I>singleton</I> object that holds + information that is relevant to the current IMAP session.</P> + + <P>Currently, the <A HREF="#Session">Session</A> contains information about:</P> + + <UL> + <LI>Global configuration (administrator settings)</LI> + <LI>Local configuration (user settings)</LI> + <LI>Command line arguments</LI> + <LI>Folder subscription list</LI> + </UL> +</BLOCKQUOTE> + +<HR> + +<P>Last updated on <B>2003-07-31</B>.</P> + +<P>Please direct comments on this document to the <A +HREF="/#mailinglist">Binc IMAP mailing list</A>. Remember to <I>search +the archives</I> first.</P> + +</BLOCKQUOTE> + +<TABLE WIDTH="99%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> + <TR> + <TD CLASS="bodytext" BGCOLOR="#FFFFFF"></TD> + </TR> + <TR> + <TD CLASS="headtext" BGCOLOR="#226666"> + <A HREF="http://validator.w3.org/check/referer"> + <IMG BORDER="0" SRC="http://www.w3.org/Icons/valid-html401" + ALT="Valid HTML 4.01!" HEIGHT="31" WIDTH="88"> + </A> + <A HREF="http://cr.yp.to/djbdns.html"><IMG BORDER="0" WIDTH="88" + HEIGHT="31" SRC="djbdns.jpg" ALT="Powered by djbdns!"></A> + <IMG BORDER="0" WIDTH="88" HEIGHT="30" SRC="binclogo.gif" + ALT="Powered by Binc IMAP"> + </TD> + </TR> +</TABLE> + +</DIV> +</TD> +</TR> +</TABLE> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> + +</BODY> +</HTML> |