1 files changed, 196 insertions, 0 deletions
diff --git a/trunk/doc/tex/imapstorage.tex b/trunk/doc/tex/imapstorage.tex
new file mode 100644
index 000000000..3a952ce54
--- /dev/null
+++ b/trunk/doc/tex/imapstorage.tex
@@ -0,0 +1,196 @@
+By enabling IMAP Storage,  Asterisk will use native IMAP as the storage
+mechanism for voicemail messages instead of using the standard file structure.
+
+Tighter integration of Asterisk voicemail and IMAP email services allows
+additional voicemail functionality, including:
+
+\begin{itemize}
+ \item Listening to a voicemail on the phone will set its state to "read" in
+   a user's mailbox automatically.
+ \item Deleting a voicemail on the phone will delete it from the user's
+   mailbox automatically.
+ \item Accessing a voicemail recording email message will turn off the message
+   waiting indicator (MWI) on the user's phone.
+ \item Deleting a voicemail recording email will also turn off the message
+   waiting indicator, and delete the message from the voicemail system.
+\end{itemize}
+
+\subsection{Installation Notes}
+
+\subsubsection{University of Washington IMAP C-Client}
+
+If you do not have the University of Washington's IMAP c-client
+installed on your system, you will need to download the c-client
+source distribution (\url{http://www.washington.edu/imap/}) and compile it.
+Asterisk supports both the 2004 and 2006 versions of c-client, however
+mail\_expunge\_full is enabled in the 2006 version.
+
+Note that Asterisk only uses the 'client' portion of the UW IMAP toolkit,
+but building it also builds an IMAP server and various other utilities.
+Because of this, the build instructions for the IMAP toolkit are somewhat
+complicated and can lead to confusion about what is needed.
+
+If you are going to be connecting Asterisk to an existing IMAP server,
+then you don't need to care about the server or utilities in the IMAP
+toolkit at all. If you want to also install the UW IMAPD server, that
+is outside the scope of this document.
+
+Building the c-client library is fairly straightforward; for example, on a
+Debian system there are two possibilities:
+
+\begin{enumerate}
+    \item If you will not be using SSL to connect to the IMAP server:
+   \begin{verbatim}
+        $ make slx SSLTYPE=none!
+   \end{verbatim}
+    \item If you will be using SSL to connect to the IMAP server:
+   \begin{verbatim}
+   $ make slx EXTRACFLAGS="-I/usr/include/openssl"
+   \end{verbatim}
+\end{enumerate}
+
+Once this completes you can proceed with the Asterisk build; there is no
+need to run 'make install'.
+
+\subsubsection{Compiling Asterisk}
+
+To use the system c-client library, configure Asterisk with
+./configure --with-imap=system. If you downloaded the c-client source
+and compiled it according to the above instructions, configure
+Asterisk with with ./configure --with-imap=/usr/src/imap or where ever
+you built the UWashington IMAP Toolkit. When you run 'make
+menuselect', choose 'Voicemail Build Options' and the IMAP\_STORAGE
+option should be available for selection.
+
+After selecting the IMAP\_STORAGE option, use the 'x' key to exit
+menuselect and save your changes, and the build/install Asterisk
+normally.
+
+\subsection{Modify voicemail.conf}
+
+The following directives have been added to voicemail.conf:
+\begin{astlisting}
+\begin{verbatim}
+imapserver=<name or IP address of IMAP mail server>
+imapport=<IMAP port, defaults to 143>
+imapflags=<IMAP flags, "novalidate-cert" for example>
+imapfolder=<IMAP folder to store messages to>
+imapgreetings=<yes or no>
+greetingsfolder=<IMAP folder to store greetings in if imapgreetings is enabled>
+expungeonhangup=<yes or no>
+authuser=<username>
+authpassword=<password>
+opentimeout=<TCP open timeout in seconds>
+closetimeout=<TCP close timeout in seconds>
+readtimeout=<TCP read timeout in seconds>
+writetimeout=<TCP write timeout in seconds>
+\end{verbatim}
+\end{astlisting}
+
+The "imapfolder" can be used to specify an alternative folder on your IMAP server
+to store voicemails in. If not specified, the default folder 'INBOX' will be used.
+
+The "imapgreetings" parameter can be enabled in order to store voicemail greetings
+on the IMAP server. If disabled, then they will be stored on the local file system
+as normal.
+
+The "greetingsfolder" can be set to store greetings on the IMAP server when
+"imapgreetings" is enabled in an alternative folder than that set by "imapfolder"
+or the default folder for voicemails.
+
+The "expungeonhangup" flag is used to determine if the voicemail system should
+expunge all messages marked for deletion when the user hangs up the phone.
+
+Each mailbox definition should also have imapuser=$<$imap username$>$.
+For example:
+\begin{astlisting}
+\begin{verbatim}
+4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar
+\end{verbatim}
+\end{astlisting}
+
+The directives "authuser" and "authpassword" are not needed when using
+Kerberos. They are defined to allow Asterisk to authenticate as a single
+user that has access to all mailboxes as an alternative to Kerberos.
+
+
+\subsection{IMAP Folders}
+
+Besides INBOX, users should create "Old", "Work", "Family" and "Friends"
+IMAP folders at the same level of hierarchy as the INBOX.  These will be
+used as alternate folders for storing voicemail messages to mimic the
+behavior of the current (file-based) voicemail system.
+
+
+\subsection{Separate vs. Shared Email Accounts}
+
+As administrator you will have to decide if you want to send the voicemail
+messages to a separate IMAP account or use each user's existing IMAP mailbox
+for voicemail storage.  The IMAP storage mechanism will work either way.
+
+By implementing a single IMAP mailbox, the user will see voicemail messages
+appear in the same INBOX as other messages.  The disadvantage of this method
+is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will
+expunge ALL messages marked for deletion when the user exits the voicemail
+system, not just the VOICEMAIL messages marked for deletion.
+
+By implementing separate IMAP mailboxes for voicemail and email, voicemail
+expunges will not remove regular email flagged for deletion.
+
+
+\subsection{IMAP Server Implementations}
+
+There are various IMAP server implementations, each supports a potentially
+different set of features.
+
+
+\subsubsection{UW IMAP-2005 or earlier}
+
+UIDPLUS is currently NOT supported on these versions of UW-IMAP.  Please note
+that without UID\_EXPUNGE, Asterisk voicemail will expunge ALL messages marked
+for deletion when a user exits the voicemail system (hangs up the phone).
+
+\subsubsection{UW IMAP-2006 Development Branch}
+
+This version supports UIDPLUS, which allows UID\_EXPUNGE capabilities.  This
+feature allow the system to expunge ONLY pertinent messages, instead of the
+default behavior, which is to expunge ALL messages marked for deletion when
+EXPUNGE is called.  The IMAP storage mechanism is this version of Asterisk
+will check if the UID\_EXPUNGE feature is supported by the server, and use it
+if possible.
+
+\subsubsection{Cyrus IMAP}
+
+Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'.
+
+
+\subsection{Quota Support}
+
+If the IMAP server supports quotas, Asterisk will check the quota when
+accessing voicemail.  Currently only a warning is given to the user that
+their quota is exceeded.
+
+
+\subsection{Application Notes}
+
+Since the primary storage mechanism is IMAP, all message information that
+was previously stored in an associated text file, AND the recording itself,
+is now stored in a single email message.  This means that the .gsm recording
+will ALWAYS be attached to the message (along with the user's preference of
+recording format if different - ie. .WAV).  The voicemail message information
+is stored in the email message headers.  These headers include:
+
+\begin{verbatim}
+X-Asterisk-VM-Message-Num
+X-Asterisk-VM-Server-Name
+X-Asterisk-VM-Context
+X-Asterisk-VM-Extension
+X-Asterisk-VM-Priority
+X-Asterisk-VM-Caller-channel
+X-Asterisk-VM-Caller-ID-Num
+X-Asterisk-VM-Caller-ID-Name
+X-Asterisk-VM-Duration
+X-Asterisk-VM-Category
+X-Asterisk-VM-Orig-date
+X-Asterisk-VM-Orig-time
+\end{verbatim}