support for imap in app_voicemail as well as some

credits fixed.


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@39404 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 190 insertions, 0 deletions

diff --git a/doc/imapstorage.txt b/doc/imapstorage.txt
new file mode 100644
index 000000000..401fee973
--- /dev/null
+++ b/doc/imapstorage.txt
@@ -0,0 +1,190 @@
+======================
+IMAP Voicemail Storage
+======================
+
+03-01-2006 - James Rothenberger <jar@onebiztone.com>
+
+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:
+
+ - Listening to a voicemail on the phone will set its state to "read" in
+   a user's mailbox automatically.
+ - Deleting a voicemail on the phone will delete it from the user's
+   mailbox automatically.
+ - Accessing a voicemail recording email message will turn off the message
+   waiting indicator (MWI) on the user's phone.
+ - Deleting a voicemail recording email will also turn off the message 
+   waiting indicator, and delete the message from the voicemail system.
+
+=====================
+Contents of this file
+=====================
+
+ - Installation Notes
+ - Separate vs. Shared Email Accounts
+ - IMAP Server Implementations
+ - Quota Support
+ - Application Notes
+ - Known Issues
+
+
+==================
+Installation Notes
+==================
+
+--------------------------------------
+University of Washington IMAP C-Client
+--------------------------------------
+You will need a source distribution of University of Washington's IMAP
+c-client (http://www.washington.edu/imap/).  You will want to make the
+appropriate changes to the c-client Makefile, for instance:
+
+EXTRAAUTHENTICATORS=gss
+EXTRADRIVERS=mbox
+
+In src/osdep/unix/Makefile, set CREATEPROTO to mbxproto.  This is done
+to utilize mbx mailbox format (see below).
+
+Compile c-client and verify that a c-client.a file has been generated.
+
+------------------
+Compiling Asterisk 
+------------------
+Uncomment the following lines in apps/Makefile:
+
+USE_IMAP_VM_INTERFACE=1
+UWCLIENT_HOME=/usr/src/imap/c-client <- path to c-client.a (above)
+CFLAGS+=-DUSE_IMAP_STORAGE
+
+Type "make" in the asterisk directory.  Do not attempt to make from the
+asterisk/apps directory.
+
+---------------------
+Modify voicemail.conf
+---------------------
+The following directives have been added to voicemail.conf:
+
+imapserver=<name or IP address of IMAP mail server>
+imapport=<IMAP port, defaults to 143>
+imapflags=<IMAP flags, "novalidate-cert" for example>
+expungeonhangup=<yes or no>
+authuser=<username>
+authpassword=<password>
+
+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:
+
+4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar
+
+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.
+
+--------------
+Mailbox Format
+--------------
+Mailboxes should use the "mbx" mailbox format.  The "mbox" format does not
+support concurrent access to mailboxes, which can cause deadlock or strange
+behaviors. You can convert mailboxes from mbox to mbx using mailutil:
+
+mailutil copy INBOX #driver.mbx/INBOX
+
+--------------
+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.
+
+
+==================================
+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.
+
+===========================
+IMAP Server Implementations
+===========================
+There are various IMAP server implementations, each supports a potentially
+different set of features.  
+
+-----------------------
+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).
+
+-------------------------------
+UW IMAP-2006 Development Branch
+-------------------------------
+This version supports UIDPLUS, which allows UID_EXPUNGE capabilities.  This
+feature allow the system to expunge ONLY pretainent 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. 
+
+----------
+Cyrus IMAP
+----------
+Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'.  
+
+
+=============
+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. 
+
+
+=================
+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:
+
+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
+
+=================
+Known Issues
+=================
+
+ - Forward With Comment advanced option is not currently supported.
+   This feature will be added in the near future.
+ - Message Waiting Indicator blinks off and back on when a message arrives.
+   This should be fixed soon.