[svn-commits] mjordan: branch mjordan/voicemail_refactor_01_08_11 r330574 - /team/mjordan/v...
SVN commits to the Digium repositories
svn-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 svn-commits
mailing list