[asterisk-commits] mjordan: branch mjordan/voicemail_refactor_01_08_11 r330574 - /team/mjordan/v...

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Tue Aug 2 09:49:02 CDT 2011


Author: mjordan
Date: Tue Aug  2 09:49:00 2011
New Revision: 330574

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=330574
Log: (empty)

Added:
    team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/
    team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/test_voicemail.h   (with props)
    team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/voicemail.h   (with props)

Added: team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/test_voicemail.h
URL: http://svnview.digium.com/svn/asterisk/team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/test_voicemail.h?view=auto&rev=330574
==============================================================================
--- team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/test_voicemail.h (added)
+++ team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/test_voicemail.h Tue Aug  2 09:49:00 2011
@@ -1,0 +1,66 @@
+/*
+ * test_voicemail.h
+ *
+ *  Created on: Jul 11, 2011
+ *      Author: mjordan
+ */
+
+#ifndef TEST_VOICEMAIL_H_
+#define TEST_VOICEMAIL_H_
+
+#include "asterisk.h"
+#include "asterisk/test.h"
+
+#define VM_TEST_MEM_EQUAL(expected, actual, upperlimit) \
+	do { \
+	  int i = 0; \
+	  for (; i < upperlimit; i++) { \
+		  if (memcmp(&(expected[i]), &(actual[i]), 1)) { \
+			  ast_test_status_update(test, "Test failed for parameter %s: Expected [%02X], Actual [%02X] (Position %d)\n", #actual, expected[i], actual[i], i); \
+			  result = AST_TEST_FAIL; \
+			  break; \
+		  }}} while (0)
+
+#define VM_TEST_STRING_EQUAL(expected, actual) \
+	do { \
+		if (strncmp(expected, actual, sizeof(expected))) { \
+			ast_test_status_update(test, "Test failed for parameter %s: Expected [%s], Actual [%s]\n", #actual, expected, actual); \
+			result = AST_TEST_FAIL; \
+		} } while (0)
+
+#define VM_TEST_STRING_NOT_EQUAL(expected, actual) \
+	do { \
+		if (!strncmp(expected, actual, sizeof(expected))) { \
+			ast_test_status_update(test, "Test failed for parameter %s: Expected NOT [%s], Actual [%s]\n", #actual, expected, actual); \
+			result = AST_TEST_FAIL; \
+		} } while (0)
+
+#define VM_TEST_NUMERIC_NOT_EQUAL(expected, actual) \
+	do { \
+		if (expected == actual) { \
+			ast_test_status_update(test, "Test failed for parameter %s: Expected NOT [%d], Actual [%d]\n", #actual, (int)expected, (int)actual); \
+			result = AST_TEST_FAIL; \
+		} } while (0)
+
+#define VM_TEST_NUMERIC_EQUAL(expected, actual) \
+	do { \
+		if (expected != actual) { \
+			ast_test_status_update(test, "Test failed for parameter %s: Expected [%d], Actual [%d]\n", #actual, (int)expected, (int)actual); \
+			result = AST_TEST_FAIL; \
+		} } while (0)
+
+/* TODO: eventually, if the test_vm_* files are modules, this header should be unnecessary.  For now,
+ * it exists to give app_voicemail a mechanism for registering the tests.
+ */
+
+void vm_register_fs_tests(void);
+
+void vm_unregister_fs_tests(void);
+
+void vm_register_config_tests(void);
+
+void vm_unregister_config_tests(void);
+
+/* TODO: add other backends / test entry points */
+
+#endif /* TEST_VOICEMAIL_H_ */

Propchange: team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/test_voicemail.h
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/test_voicemail.h
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision

Propchange: team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/test_voicemail.h
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/voicemail.h
URL: http://svnview.digium.com/svn/asterisk/team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/voicemail.h?view=auto&rev=330574
==============================================================================
--- team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/voicemail.h (added)
+++ team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/voicemail.h Tue Aug  2 09:49:00 2011
@@ -1,0 +1,650 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 1999 - 2006, Digium, Inc.
+ *
+ * Mark Spencer <markster at digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+/*!
+ * \file
+ * \author Matt Jordan <mjordan at digium.com>
+ * \brief Comedian Mail - Voicemail System
+ *
+ */
+
+#ifndef VOICEMAIL_H_
+#define VOICEMAIL_H_
+
+#include "asterisk.h"
+#include "asterisk/channel.h"
+#include "asterisk/file.h"
+
+#define	VOICEMAIL_DIR_MODE	0777
+
+#define	VOICEMAIL_FILE_MODE	0666
+
+#define MAX_DTMF_LENGTH 16
+
+#define MAX_FORMAT_LENGTH 64
+
+#define MAX_NUM_CID_CONTEXTS 10
+
+#define MAX_ADSI_FIELDS 4
+
+static const char * const default_busy_folder_name = "busy";
+
+static const char * const default_unavailable_folder_name = "unavail";
+
+enum vm_global_flags {
+	VM_REVIEW		 = (1 << 0),   /*!< After recording, permit the caller to review the recording before saving */
+	VM_OPERATOR      = (1 << 1),   /*!< Allow 0 to be pressed to go to 'o' extension */
+	VM_SAYCID        = (1 << 2),   /*!< Repeat the CallerID info during envelope playback */
+	VM_SVMAIL        = (1 << 3),   /*!< Allow the user to compose a new VM from within VoicemailMain */
+	VM_ENVELOPE      = (1 << 4),   /*!< Play the envelope information (who-from, time received, etc.) */
+	VM_SAYDURATION   = (1 << 5),   /*!< Play the length of the message during envelope playback */
+	VM_SKIPAFTERCMD  = (1 << 6),   /*!< After deletion, assume caller wants to go to the next message */
+	VM_FORCENAME     = (1 << 7),   /*!< Have new users record their name */
+	VM_FORCEGREET    = (1 << 8),   /*!< Have new users record their greetings */
+	VM_PBXSKIP       = (1 << 9),   /*!< Skip the [PBX] preamble in the Subject line of emails */
+	VM_DIRECFORWARD  = (1 << 10),  /*!< Permit caller to use the Directory app for selecting to which mailbox to forward a VM */
+	VM_ATTACH        = (1 << 11),  /*!< Attach message to voicemail notifications? */
+	VM_DELETE        = (1 << 12),  /*!< Delete message after sending notification */
+	VM_ALLOCED       = (1 << 13),  /*!< Structure was malloc'ed, instead of placed in a return (usually static) buffer */
+	VM_SEARCH        = (1 << 14),  /*!< Search all contexts for a matching mailbox */
+	VM_TEMPGREETWARN = (1 << 15),  /*!< Remind user tempgreeting is set */
+	VM_MOVEHEARD     = (1 << 16),  /*!< Move a "heard" message to Old after listening to it */
+	VM_MESSAGEWRAP   = (1 << 17),  /*!< Wrap around from the last message to the first, and vice-versa */
+	VM_FWDURGAUTO    = (1 << 18),  /*!< Autoset of Urgent flag on forwarded Urgent messages set globally */
+	VM_POLLMAILBOXES = (1 << 19)   /*!< If set, poll mailboxes for changes */
+};
+
+enum vm_message_flags {
+	VM_MSG_NEW	    = (1 << 0),
+	VM_MSG_TMP      = (1 << 1),
+	VM_MSG_OLD      = (1 << 2)
+};
+
+enum vm_passwordlocation {
+	OPT_PWLOC_VOICEMAILCONF = 0,
+	OPT_PWLOC_SPOOLDIR      = 1,
+	OPT_PWLOC_USERSCONF     = 2,
+};
+
+enum vm_message_priorities {
+	VM_PRIORITY_URGENT		= 0,
+	VM_PRIORITY_PRIORITY 	= 1,
+	VM_PRIORITY_NORMAL		= 100,
+	VM_PRIORITY_LOW			= INT_MAX
+};
+
+enum vm_password_options {
+	VM_PWD_CHANGE_EXTERNAL = (1 << 0),
+	VM_PWD_CHANGE_INTERNAL = (1 << 1)
+};
+
+/* TODO: not sure about all the char * */
+struct vm_msg_info {
+	char origmailbox[AST_MAX_EXTENSION];
+	char context[AST_MAX_CONTEXT];
+	char macrocontext[AST_MAX_CONTEXT];
+	char exten[AST_MAX_EXTENSION];
+	char * rdnis;
+	int exten_priority;							/*!< The channel extension priority (NOT the message */
+	struct ast_flags msg_flags;						/*!< Flags on the message */
+	enum vm_message_priorities msg_priority;		/*!< The message priority */
+	char callerchan[AST_CHANNEL_NAME];
+	char * callerid;
+	char * origdate;
+	long origtime;
+	const char * category;
+	int flag;
+	int duration;
+};
+
+struct vm_voicemail_object {
+	char msg_name[32];
+	char msg_location[PATH_MAX];				/*!< The directory path containing the message files */
+	char format[MAX_FORMAT_LENGTH];				/*!< The supported message formats */
+	int msgnum;									/*!< The message number */
+	struct vm_msg_info * msg_info;				/*!< The message envelope information */
+	struct vm_folder * curfolder;   			/*!< The current folder containing the message */
+	struct ast_vm_user * owner;					/*!< The current owner of the voicemail */
+	AST_LIST_ENTRY(vm_voicemail_object) list;
+	/*AST_LIST_HEAD_NOLOCK_STATIC(files, vm_voicemail_file);*/
+};
+
+struct vm_folder {
+	char name[32];
+	char directory[PATH_MAX];
+	int priority;
+	int number_voicemails;
+	int ignore;
+	AST_LIST_HEAD_NOLOCK(voicemails, vm_voicemail_object) voicemails;
+	AST_LIST_ENTRY(vm_folder) list;
+};
+
+/*! Voicemail time zones */
+struct vm_timezone {
+	AST_LIST_ENTRY(vm_zone) list;
+	AST_DECLARE_STRING_FIELDS(
+		AST_STRING_FIELD(name);
+		AST_STRING_FIELD(timezone);
+		AST_STRING_FIELD(msg_format);
+	);
+};
+
+struct vm_sound_config {
+	AST_DECLARE_STRING_FIELDS(
+		AST_STRING_FIELD(vm_password);
+		AST_STRING_FIELD(vm_newpassword);
+		AST_STRING_FIELD(vm_invalid_password);
+		AST_STRING_FIELD(vm_password_changed);
+		AST_STRING_FIELD(vm_reenter_password);
+		AST_STRING_FIELD(vm_mismatch);
+		AST_STRING_FIELD(vm_pls_try_again);
+	);
+};
+
+struct vm_listen_control_config {
+	char listen_control_forward_key[MAX_DTMF_LENGTH];
+	char listen_control_reverse_key[MAX_DTMF_LENGTH];
+	char listen_control_pause_key[MAX_DTMF_LENGTH];
+	char listen_control_restart_key[MAX_DTMF_LENGTH];
+	char listen_control_stop_key[MAX_DTMF_LENGTH];
+};
+
+struct vm_smdi_config {
+	unsigned int enabled;
+	AST_DECLARE_STRING_FIELDS(
+		AST_STRING_FIELD(smdi_interface);
+	);
+};
+
+struct vm_adsi_config {
+	unsigned char adsifdn[MAX_ADSI_FIELDS];
+	unsigned char adsisec[MAX_ADSI_FIELDS];
+	unsigned int adsiver;
+};
+
+struct vm_config {
+	double volgain;
+	unsigned int max_silence;
+	unsigned int max_deleted_messages;
+	unsigned int max_messages;
+	unsigned int min_say_duration;
+	unsigned int min_message_duration;
+	unsigned int max_message_duration;
+	unsigned int max_message_greeting_length;
+	unsigned int skip_ms;
+	unsigned int min_password_length;
+	unsigned int silence_threshold;
+	unsigned int poll_frequency;
+	unsigned int max_logins;
+	enum vm_passwordlocation password_location;
+	char attach_format[MAX_FORMAT_LENGTH];
+	char format[MAX_FORMAT_LENGTH];
+	char dial_out_context[AST_MAX_CONTEXT];
+	char callback_context[AST_MAX_CONTEXT];
+	char op_exit_context[AST_MAX_CONTEXT];
+	char default_users_context[AST_MAX_CONTEXT];
+	char cid_internal_contexts[MAX_NUM_CID_CONTEXTS][AST_MAX_CONTEXT];
+	char extern_notify_cmd[PATH_MAX];
+	char extern_pass_cmd[PATH_MAX];
+	char extern_pass_check_cmd[PATH_MAX];
+	char directory_intro_path[PATH_MAX];
+	char folder_path[PATH_MAX];								/*!< The path to the location of the folders on the local disk*/
+	struct vm_sound_config * sound_config;
+	struct vm_listen_control_config * listen_control_config;
+	struct vm_smdi_config * smdi_config;
+	struct vm_adsi_config * adsi_config;
+	struct ast_flags globalflags;
+	struct ast_flags passwordflags;
+	AST_DECLARE_STRING_FIELDS(
+		AST_STRING_FIELD(mail_command);
+		AST_STRING_FIELD(email_from_string);
+		AST_STRING_FIELD(email_server);
+		AST_STRING_FIELD(email_date_format);
+		AST_STRING_FIELD(email_subject);
+		AST_STRING_FIELD(email_body);
+		AST_STRING_FIELD(pager_from_string);
+		AST_STRING_FIELD(pager_date_format);
+		AST_STRING_FIELD(pager_subject);
+		AST_STRING_FIELD(pager_body);
+		AST_STRING_FIELD(zonetag);
+		AST_STRING_FIELD(locale);
+		AST_STRING_FIELD(charset);
+	);
+	AST_LIST_HEAD_NOLOCK(folder_defs, vm_folder) folder_defs;
+};
+
+/*! Voicemail mailbox state */
+struct vm_state {
+	/* TODO: get rid of whatever we can out of here.  This is nuts */
+	char curbox[80];
+	char username[80];
+	char context[80];
+	char curdir[PATH_MAX];
+	char vmbox[PATH_MAX];
+	char fn[PATH_MAX];
+	char intro[PATH_MAX];
+	struct vm_folder * curfolder;
+	int *deleted;
+	int *heard;
+	int dh_arraysize; /* used for deleted / heard allocation */
+	int curmsg;
+	int lastmsg;
+	int newmessages;
+	int oldmessages;
+	int urgentmessages;
+	int starting;
+	int repeats;
+	AST_LIST_HEAD_NOLOCK(folders, vm_folder) folders;
+/*#ifdef IMAP_STORAGE
+	ast_mutex_t lock;
+	int updated;                        */ /*!< decremented on each mail check until 1 -allows delay */
+/*	long msgArray[VMSTATE_MAX_MSG_ARRAY];
+	MAILSTREAM *mailstream;
+	int vmArrayIndex;
+	char imapuser[80];                   *//*!< IMAP server login */
+/*	char imapfolder[64];                 *//*!< IMAP voicemail folder */
+/*	int imapversion;
+	int interactive;
+	char introfn[PATH_MAX];              *//*!< Name of prepended file */
+/*	unsigned int quota_limit;
+	unsigned int quota_usage;
+	struct vm_state *persist_vms;
+#endif*/
+};
+
+/*! Structure for linked list of users
+ * Use ast_vm_user_destroy() to free one of these structures. */
+struct ast_vm_user {
+	char context[AST_MAX_CONTEXT];   /*!< Voicemail context */
+	char mailbox[AST_MAX_EXTENSION]; /*!< Mailbox id, unique within vm context */
+	char password[80];               /*!< Secret pin code, numbers only */
+	char fullname[80];               /*!< Full name, for directory app */
+	char email[80];                  /*!< E-mail address */
+	const char *emailsubject;        /*!< E-mail subject */
+	const char *emailbody;           /*!< E-mail body */
+	char pager[80];                  /*!< E-mail address to pager (no attachment) */
+	char serveremail[80];            /*!< From: Mail address */
+	char mailcmd[160];               /*!< Configurable mail command */
+	char language[MAX_LANGUAGE];     /*!< Config: Language setting */
+	char zonetag[80];                /*!< Time zone */
+	char locale[20];                 /*!< The locale (for presentation of date/time) */
+	char callback[80];
+	char dialout[80];
+	char uniqueid[80];               /*!< Unique integer identifier */
+	char exit[80];
+	char attachfmt[20];              /*!< Attachment format */
+	unsigned int flags;              /*!< VM_ flags */
+	int saydurationm;
+	int minsecs;                     /*!< Minimum number of seconds per message for this mailbox */
+	int maxmsg;                      /*!< Maximum number of msgs per folder for this mailbox */
+	int maxdeletedmsg;               /*!< Maximum number of deleted msgs saved for this mailbox */
+	int maxsecs;                     /*!< Maximum number of seconds per message for this mailbox */
+	int passwordlocation;            /*!< Storage location of the password */
+	double volgain;                  /*!< Volume gain for voicemails sent via email */
+	struct vm_state * vms;
+	AST_LIST_ENTRY(ast_vm_user) list;
+};
+
+#define DATA_EXPORT_VM_USERS(USER)					\
+	USER(ast_vm_user, context, AST_DATA_STRING)			\
+	USER(ast_vm_user, mailbox, AST_DATA_STRING)			\
+	USER(ast_vm_user, password, AST_DATA_PASSWORD)			\
+	USER(ast_vm_user, fullname, AST_DATA_STRING)			\
+	USER(ast_vm_user, email, AST_DATA_STRING)			\
+	USER(ast_vm_user, emailsubject, AST_DATA_STRING)		\
+	USER(ast_vm_user, emailbody, AST_DATA_STRING)			\
+	USER(ast_vm_user, pager, AST_DATA_STRING)			\
+	USER(ast_vm_user, serveremail, AST_DATA_STRING)			\
+	USER(ast_vm_user, mailcmd, AST_DATA_STRING)			\
+	USER(ast_vm_user, language, AST_DATA_STRING)			\
+	USER(ast_vm_user, zonetag, AST_DATA_STRING)			\
+	USER(ast_vm_user, callback, AST_DATA_STRING)			\
+	USER(ast_vm_user, dialout, AST_DATA_STRING)			\
+	USER(ast_vm_user, uniqueid, AST_DATA_STRING)			\
+	USER(ast_vm_user, exit, AST_DATA_STRING)			\
+	USER(ast_vm_user, attachfmt, AST_DATA_STRING)			\
+	USER(ast_vm_user, flags, AST_DATA_UNSIGNED_INTEGER)		\
+	USER(ast_vm_user, saydurationm, AST_DATA_INTEGER)		\
+	USER(ast_vm_user, maxmsg, AST_DATA_INTEGER)			\
+	USER(ast_vm_user, maxdeletedmsg, AST_DATA_INTEGER)		\
+	USER(ast_vm_user, maxsecs, AST_DATA_INTEGER)			\
+	USER(ast_vm_user, volgain, AST_DATA_DOUBLE)
+
+AST_DATA_STRUCTURE(ast_vm_user, DATA_EXPORT_VM_USERS);
+
+struct vm_backend_tech
+{
+	/*!
+	 * \brief The type of storage implementing this interface
+	 */
+	const char * const type;
+
+	/*!
+	 * \brief Store the voiemail object in the backing store
+	 * \param vm_object	The voicemail object to store
+	 *
+	 * \details
+	 * This synchronizes the voicemail object with the backing storage.  If the voicemail object already exists in
+	 * storage, it's properties are updated; otherwise, it is added.
+	 *
+	 * \returns 0 on success, any other value on failure
+	 */
+	int (* const store_voicemail)(const struct vm_voicemail_object * const vm_object);
+
+	/*!
+	 * \brief Retrieve a voicemail object from the backing store
+	 * \param folder	The folder to retrieve from
+	 * \param msgnum	The message numbet to retrieve
+	 * \param vm_object	The voicemail object to populate
+	 *
+	 * \details
+	 * This updates the voicemail vm_object with the values in the backing storage, bringing the voicemail to the local filesystem
+	 * if needed.  The voicemail is allocated and populated if the pointer is NULL; otherwise the contents of the voicemail are replaced
+	 * with the most recent version from the backing storage.
+	 *
+	 * \returns 0 on success, any other value on failure or if the voicemail could not be found
+	 */
+	int (* const retrieve_voicemail)(struct vm_folder * folder, const int msgnum, struct vm_voicemail_object * * vm_object);
+
+	/*!
+	 * \brief Dispose of the voicemail, if the voicemail is a temporary object
+	 * \param vm_object	The voicemail to dispose of
+	 *
+	 * \details
+	 * This method is called upon a voicemail object that is temporary.  A temporary voicemail is defined as either having the
+	 * VM_MSG_TMP flag set on it, or by existing in a folder with the VM_MSG_TMP flag set.  If either condition is true, the
+	 * voicemail should be removed and deleted.  If either condition is not true, the vm_object should be left.
+	 *
+	 * \returns 0 if the vm_object was ignored or successfully dispose of, 1 if an error occurred in disposing of the voicemail.
+	 */
+	int (* const dispose_voicemail)(struct vm_voicemail_object * vm_object);
+
+	/*!
+	 * \brief Check that the voicemail exists in the backing storage
+	 * \param vm_object	The voicemail to check
+	 *
+	 * \details
+	 * A voicemail object can be allocated in memory, but not yet stored to the backing storage.  This method call checks the
+	 * backing storage to determine if the voicemail has been stored previously, using store_voicemail.
+	 *
+	 * \returns 0 if the vm_object does not exist
+	 * \returns 1 if the vm_object does exist
+	 */
+	int (* const voicemail_exists)(const struct vm_voicemail_object * const vm_object);
+
+	/*!
+	 * \brief Determine if a folder exists
+	 * \param name	The name of the folder to check for
+	 * \param vmu	The user that the folder should exist for.  If NULL, check for whether or not the folder can exist for any user
+	 *
+	 * \details
+	 * This method checks for whether or not a folder with the specified name exists in the backing storage.  If the user is also
+	 * specified, then it checks specifically for the user; otherwise, it checks to see if any folder could potentially
+	 * exist for any user.
+	 *
+	 * \returns 0 if the folder does not exist
+	 * \returns 1 if the folder does exist
+	 */
+	int (* const folder_exists)(const char * const name, const struct ast_vm_user * const vmu);
+
+	/*!
+	 * \brief Permanently delete a voicemail
+	 * \param vm_object	The object to delete
+	 *
+	 * \details
+	 * This method deletes a voicemail from the backing storage and deallocates the voicemail.  This also removes it from whatever
+	 * folder the voicemail belongs to.
+	 *
+	 * \note
+	 * This method only returns a failure if an error occurred.  Hence, a voicemail can not exist in the backing storage, but this
+	 * method will still deallocate it and return success.
+	 *
+	 * \returns 0 if the voicemail was successfully removed
+	 * \returns any other value if an error occurred
+	 */
+	int (* const delete_voicemail)(struct vm_voicemail_object * vm_object);
+
+	/*!
+	 * \brief Copy a voicemail to a destination folder
+	 * \param vm_obj_src	The voicemail object to copy
+	 * \param dest_folder	The destination folder
+	 *
+	 * \details
+	 * This method copies the voicemail to the specified folder.
+	 *
+	 * \note
+	 * Copying a voicemail does not necessarily preserve its message number.  The voicemail is reindexed such that it is the 'newest'
+	 * message in the folder, e.g., it has the highest message number.
+	 *
+	 * \returns 0 on success
+	 * \returns any other value on failure
+	 */
+	int (* const copy_voicemail)(struct vm_voicemail_object * vm_obj_src, struct vm_folder * dest_folder);
+
+	/*!
+	 * \brief Renames a voicemail object within a folder
+	 * \param vm_object		The voicemail object to be renamed
+	 * \param msgnum		The new message number for the voicemail object
+	 *
+	 * \details
+	 * This method renumbers a voicemail to the number specified.  This usually includes altering the physical name
+	 * of the voicemail in the backing storage.  Note that while this method can be called to rename a voicemail object,
+	 * other operations may renumber the voicemail to a different message number at a later time (voicemails are renumbered
+	 * sequentially) - hence renumbering a voicemail 'out of order' may only be temporary.  Note that this method does not
+	 * move a voicemail to a different folder; see copy_voicemail for that operation.
+	 *
+	 * \returns 0 on success
+	 * \returns any other value on error
+	 */
+	int (* const rename_voicemail)(struct vm_voicemail_object * vm_object, const int msgnum);
+
+	/*!
+	 * \brief Return the count in the current folder.  If no folder is specified, returns a count across all folders for the user.
+	 * \param vmu		The voicemail user
+	 * \param folder	The folder to check, or NULL if all folders should be checked
+	 *
+	 * \details
+	 * \returns The number of voicemails the user has, either in a folder or cumulative across all folders
+	 */
+	int (* const count_voicemail)(const struct ast_vm_user * const vmu, const struct vm_folder * folder);
+
+	/*!
+	 * \brief Open the voicemail folders for the specified user, loading them and their current voicemails into memory
+	 * \param vmu	The voicemail user
+	 *
+	 * \details
+	 * This method loads the voicemail objects for the specified user into memory.  It should be called whenever a voicemail
+	 * user's mailbox is being manipulated.  This populates the vm_state object for the user, their folders, and the folder's
+	 * voicemails.
+	 *
+	 * \note
+	 * If a user has not been previously opened, this method will also create the folder structure in the backing storage for
+	 * that user.
+	 *
+	 * \returns 0 on success
+	 * \returns any other value on failure
+	 */
+	int (* const open_voicemail)(struct ast_vm_user * vmu);
+
+	/*!
+	 * \brief Initialize the backing storage
+	 * \param cfg	The ast_config object that contains the voicemail configuration parameters
+	 * \param vmcfg	The general voicemail configuration parameters
+	 *
+	 * \details
+	 * This method allows the backing storage to initialize itself using (a) all of the configuration parameters supplied to voicemail,
+	 * and (b) the pre-parsed configuration parameters that are generic for any voicemail.
+	 *
+	 * \note This method is called during module load
+	 *
+	 * \returns 0 on successful intialization
+	 * \returns any other value on error
+	 */
+	int (* const init_backend)(struct ast_config * cfg, struct vm_config * vmcfg);
+};
+
+/* TODO: this is preferable, and each of the backends would be a module.  However, currently they aren't being compiled
+ * as a shared object, so this blows up spectacularly.  For now, we're going to put some methods in here that are called
+ * directly from the app_voicemail to build up the backends.  These should be removed when possible.
+ */
+int vm_register_backend(struct vm_backend_tech * vm_backend);
+
+/* OR */
+struct vm_backend_tech * vm_allocate_filesystem(void);
+
+struct vm_backend_tech * vm_allocate_odbc(void);
+
+struct vm_backend_tech * vm_allocate_imap(void);
+
+
+struct vm_timezone * vm_timezone_new(void);
+
+struct vm_voicemail_object * vm_voicemail_object_new(void);
+
+struct vm_voicemail_object * vm_voicemail_object_copy(const struct vm_voicemail_object * vm_object);
+
+void vm_voicemail_object_destroy(struct vm_voicemail_object * vm_object);
+
+struct vm_msg_info * vm_message_info_new(void);
+
+struct vm_msg_info * vm_message_info_copy(const struct vm_msg_info * msg_info);
+
+void vm_message_info_destroy(struct vm_msg_info * msg_info);
+
+int vm_assign_message_info(const struct ast_channel * chan, struct vm_msg_info * msg_info);
+
+struct vm_folder * vm_folder_new(void);
+
+struct vm_folder * vm_folder_copy(const struct vm_folder * folder);
+
+void vm_folder_destroy(struct vm_folder * folder);
+
+/*!
+ * \brief Send an e-mail message
+ * \param chan			The current channel
+ * \param vmu			The user to send the mail message to
+ * \param vm_object		The voicemail to reference
+ * \param emailserver	The mail server to notify
+ * \param fmt			If specified, the format of the voicemail to attach
+ *
+ * \details
+ * Sends a mail message to an e-mail server, a paging service, etc.  The command used to send the message is specified by the
+ * vm_config object and / or the voicemail user object, where the voicemail user object overrides the settings in vm_config.
+ *
+ * \note
+ * TODO: Eventually, this should probably be its own seperate application and be called through the MWI event.
+ *
+ * \returns 0 on success
+ * \returns any other value on error
+ */
+int vm_send_email_message(struct ast_channel *chan, struct ast_vm_user *src_vmu, struct ast_vm_user *dst_vmu, struct vm_voicemail_object *vm_object, const char *mailserver, const char *fmt);
+
+int vm_send_page_message(struct ast_channel *chan, struct ast_vm_user *src_vmu, struct ast_vm_user *dst_vmu, struct vm_voicemail_object *vm_object, const char *mailserver);
+
+/*!
+ * \brief Finds a timezone by name
+ * \param name	The name of the timezone to retrieve
+ *
+ * \details This finds a configured timezone that was loaded in vm_load_config.  The reference count
+ * is incremented for the timezone object that is returned from this method.
+ *
+ * \note	When the caller of this method is finished with the object, ao2_ref( , -1) should be called on the object
+ *
+ * \returns A valid timezone on success, or NULL if no timezone matching name was found
+ */
+struct vm_timezone * vm_find_timezone(const char * name);
+
+/*!
+ * \brief Find a voicemail user
+ * \param context	The user's context
+ * \param mailbox	The user's mailbox extension
+ *
+ * \details This finds a loaded voicemail user and returns a reference to it.  The reference
+ * count is incremented for the user each time they are returned from this method.
+ *
+ * \note	When the caller of this method is finished with the object, ao2_ref( , -1) should be called on the object
+ *
+ * \returns A valid voicemail user, or NULL if no user was found
+ */
+struct ast_vm_user * vm_find_user(const char * context, const char * mailbox);
+
+/*!
+ * \brief Allocate a new ast_vm_user object
+ * \param context	The user's context
+ * \param mailbox	The user's mailbox
+ *
+ * \details Allocates a new ast_vm_user object.  Note that the object is an astobj2 object,
+ * and is managed by reference counters.  The combination of context and mailbox must be
+ * unique across all ast_vm_users.
+ *
+ * \returns A new user, or NULL on error
+ */
+struct ast_vm_user * vm_voicemail_user_new(const char * context, const char * mailbox);
+
+/*!
+ * \brief Reads the password for a voicemail user from the specified file
+ * \param	secretfn	Full path and filename to read from
+ * \param	password	Buffer to hold the read password
+ * \param	passwordlen	Length of the buffer password
+ *
+ * \details
+ * Reads a voicemail user password from an ast_config compatible file.  This is used
+ * when the configuration calls for the user password to be stored on the local filesystem
+ * but not in voicemail.conf.
+ *
+ * \returns 0 on success, any other value on failure
+ */
+void vm_read_password_from_file(const char *secretfn, char *password, int passwordlen);
+
+/*!
+ * \brief Retrieve the current voicemail configuration
+ *
+ * \details
+ * This returns the currently loaded vm_config object.  Note that modules wishing to use
+ * the vm_config should be loaded after app_voicemail by having a dependency upon it.
+ *
+ * \note This method increases the reference count on the vm_config object
+ *
+ * \returns an allocated and populated vm_config object, or NULL on error
+ */
+struct vm_config * vm_get_config(void);
+
+/*!
+ * \brief load the voicemail.conf file into memory
+ * \param reload		If true, this assumes a reload and the next to parameters will be deallocated
+ * \param base_config	Pointer to the ast_config object to allocate (if reload is false) and populate
+ * \param main_config	Pointer to the vm_config object to allocate (if reload is false) and populate
+ *
+ * \details
+ * Loads the voicemail.conf into memory, both as an unparsed ast_config object and as
+ * the parsed configuration vm_config.  The ast_config object can be used by other
+ * add-ons to the main voicemail application to obtain their specific configurations;
+ * the vm_config object contains voicemail configuration information useful for any
+ * voicemail-based addon.
+ *
+ * \returns 0 on success, any other value on error
+ */
+int vm_load_config(const int reload, struct ast_config ** base_config, struct vm_config ** vm_config);
+
+/*!
+ * \brief dispose of an existing vm_config object
+ * \param obj	The object to dispose
+ */
+void vm_config_destroy(void * obj);
+
+#endif /* VOICEMAIL_H_ */

Propchange: team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/voicemail.h
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/voicemail.h
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision

Propchange: team/mjordan/voicemail_refactor_01_08_11/apps/voicemail/include/voicemail.h
------------------------------------------------------------------------------
    svn:mime-type = text/plain




More information about the asterisk-commits mailing list