From 5401b2bfbf9c31570439c62a3ed7165052610b51 Mon Sep 17 00:00:00 2001 From: Richard Mudgett <rmudgett@digium.com> Date: Fri, 1 Nov 2013 23:20:54 +0000 Subject: [PATCH] voicemail: Simplify callback pointer declarations and add doxygen. * Typedefed and added doxegen for the voicemail callback functions. * Simplified the prototypes for ast_install_vm_functions() and ast_install_vm_test_functions() to use the new function typedefs. * Simplified the voicemail callback function pointer variable declarations to use the new function typedefs. ........ Merged revisions 402398 from http://svn.asterisk.org/svn/asterisk/branches/12 git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@402406 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- include/asterisk/app.h | 305 +++++++++++++++++++++++++++++++++-------- main/app.c | 118 +++++----------- 2 files changed, 278 insertions(+), 145 deletions(-) diff --git a/include/asterisk/app.h b/include/asterisk/app.h index c30290f6ec..c47c4d3795 100644 --- a/include/asterisk/app.h +++ b/include/asterisk/app.h @@ -44,7 +44,7 @@ AST_THREADSTORAGE_EXTERNAL(ast_str_thread_global_buf); /*! \brief Callback function for IVR \return returns 0 on completion, -1 on hangup or digit if interrupted */ -typedef int (*ast_ivr_callback)(struct ast_channel *chan, char *option, void *cbdata); +typedef int (ast_ivr_callback)(struct ast_channel *chan, char *option, void *cbdata); typedef enum { AST_ACTION_UPONE, /*!< adata is unused */ @@ -82,7 +82,7 @@ struct ast_ivr_menu { unsigned int flags; /*!< Flags */ struct ast_ivr_option *options; /*!< All options */ }; - + /*! * \brief Structure used for ast_copy_recording_to_vm in order to cleanly supply * data needed for making the recording from the recorded file. @@ -324,72 +324,257 @@ struct ast_vm_mailbox_snapshot { /*! * \brief Voicemail playback callback function definition * - * \param channel to play the file back on. - * \param location of file on disk + * \param chan Channel to play the file back on. + * \param playfile Location of file on disk * \param duration of file in seconds. This will be zero if msg is very short or * has an unknown duration. */ typedef void (ast_vm_msg_play_cb)(struct ast_channel *chan, const char *playfile, int duration); +/*! + * \brief Determines if the given folder has messages. + * + * \param mailbox The @ delimited string for user@context. If no context is found, uses 'default' for the context. + * \param folder The folder to look in. Default is INBOX if not provided. + * + * \retval 1 if the folder has one or more messages. + * \retval 0 otherwise. + */ +typedef int (ast_has_voicemail_fn)(const char *mailbox, const char *folder); + +/*! + * \brief Gets the number of messages that exist for the mailbox list. + * + * \param mailbox Comma or space deliminated list of mailboxes (user@context). + * \param newmsgs Where to put the count of new messages. (Can be NULL) + * \param oldmsgs Where to put the count of old messages. (Can be NULL) + * + * \details + * Simultaneously determines the count of new + urgent and old + * messages. The total messages would then be the sum of these. + * + * \retval 0 on success + * \retval -1 on failure + */ +typedef int (ast_inboxcount_fn)(const char *mailbox, int *newmsgs, int *oldmsgs); + +/*! + * \brief Gets the number of messages that exist for the mailbox list. + * + * \param mailbox Comma or space deliminated list of mailboxes (user@context). + * \param urgentmsgs Where to put the count of urgent messages. (Can be NULL) + * \param newmsgs Where to put the count of new messages. (Can be NULL) + * \param oldmsgs Where to put the count of old messages. (Can be NULL) + * + * \details + * Simultaneously determines the count of new, old, and urgent + * messages. The total messages would then be the sum of these + * three. + * + * \retval 0 on success + * \retval -1 on failure + */ +typedef int (ast_inboxcount2_fn)(const char *mailbox, int *urgentmsgs, int *newmsgs, int *oldmsgs); + +/*! + * \brief Gets the number of messages that exist in a mailbox folder. + * + * \param context The context part of user@context. Uses 'default' if not provided. + * \param mailbox The user part of user@context. + * \param folder The folder to look in. Default is INBOX if not provided. + * + * \note If requesting INBOX then the returned count is INBOX + + * Urgent. + * + * \return The number of messages in this mailbox folder (zero or more). + */ +typedef int (ast_messagecount_fn)(const char *context, const char *mailbox, const char *folder); + +/*! + * \brief Play a recorded user name for the mailbox. + * + * \param chan Where to play the recorded name file. + * \param mailbox The user part of user@context. + * \param context The context part of user@context. Must be explicit. + * + * \retval 0 Name played without interruption + * \retval dtmf ASCII value of the DTMF which interrupted playback + * \retval -1 on failure + */ +typedef int (ast_sayname_fn)(struct ast_channel *chan, const char *mailbox, const char *context); + +/*! + * \brief Creates a voicemail based on a specified file to a mailbox. + * + * \param vm_rec_data A record containing filename and voicemail txt info. + * + * \retval 0 on success + * \retval -1 on failure + */ +typedef int (ast_copy_recording_to_vm_fn)(struct ast_vm_recording_data *vm_rec_data); + +/*! + * \brief Convert the mailbox folder id to a folder name. + * + * \param id Mailbox folder id to convert. + * + * \deprecated Nothing calls it and nothing ever should. + * + * \return The folder name associated with the id. + */ +typedef const char *(ast_vm_index_to_foldername_fn)(int id); + +/*! + * \brief Create a snapshot of a mailbox which contains information about every msg. + * + * \param mailbox The user part of user@context. + * \param context The context part of user@context. Must be explicit. + * \param folder When not NULL only msgs from the specified folder will be included. + * \param desending list the msgs in descending order rather than ascending order. + * \param sort_val What to sort in the snapshot. + * \param combine_INBOX_and_OLD When this argument is set, The OLD folder will be represented + * in the INBOX folder of the snapshot. This allows the snapshot to represent the + * OLD and INBOX messages in sorted order merged together. + * + * \note Only used by voicemail unit tests. + * + * \retval snapshot on success + * \retval NULL on failure + */ +typedef struct ast_vm_mailbox_snapshot *(ast_vm_mailbox_snapshot_create_fn)(const char *mailbox, + const char *context, const char *folder, int descending, + enum ast_vm_snapshot_sort_val sort_val, int combine_INBOX_and_OLD); + +/*! + * \brief destroy a snapshot + * + * \param mailbox_snapshot The snapshot to destroy. + * + * \note Only used by voicemail unit tests. + * + * \retval NULL + */ +typedef struct ast_vm_mailbox_snapshot *(ast_vm_mailbox_snapshot_destroy_fn)(struct ast_vm_mailbox_snapshot *mailbox_snapshot); + +/*! + * \brief Move messages from one folder to another + * + * \param mailbox The mailbox to which the folders belong + * \param context The voicemail context for the mailbox + * \param num_msgs The number of messages to move + * \param oldfolder The folder from where messages should be moved + * \param old_msg_ids The message IDs of the messages to move + * \param newfolder The folder to which messages should be moved + * new folder. This array must be num_msgs sized. + * + * \note Only used by voicemail unit tests. + * + * \retval -1 Failure + * \retval 0 Success + */ +typedef int (ast_vm_msg_move_fn)(const char *mailbox, const char *context, size_t num_msgs, + const char *oldfolder, const char *old_msg_ids[], const char *newfolder); + +/*! + * \brief Remove/delete messages from a mailbox folder. + * + * \param mailbox The mailbox from which to delete messages + * \param context The voicemail context for the mailbox + * \param num_msgs The number of messages to delete + * \param folder The folder from which to remove messages + * \param msgs The message IDs of the messages to delete + * + * \note Only used by voicemail unit tests. + * + * \retval -1 Failure + * \retval 0 Success + */ +typedef int (ast_vm_msg_remove_fn)(const char *mailbox, const char *context, size_t num_msgs, + const char *folder, const char *msgs[]); + +/*! + * \brief forward a message from one mailbox to another. + * + * \brief from_mailbox The original mailbox the message is being forwarded from + * \brief from_context The voicemail context of the from_mailbox + * \brief from_folder The folder from which the message is being forwarded + * \brief to_mailbox The mailbox to forward the message to + * \brief to_context The voicemail context of the to_mailbox + * \brief to_folder The folder to which the message is being forwarded + * \brief num_msgs The number of messages being forwarded + * \brief msg_ids The message IDs of the messages in from_mailbox to forward + * \brief delete_old If non-zero, the forwarded messages are also deleted from from_mailbox. + * Otherwise, the messages will remain in the from_mailbox. + * + * \note Only used by voicemail unit tests. + * + * \retval -1 Failure + * \retval 0 Success + */ +typedef int (ast_vm_msg_forward_fn)(const char *from_mailbox, const char *from_context, + const char *from_folder, const char *to_mailbox, const char *to_context, + const char *to_folder, size_t num_msgs, const char *msg_ids[], int delete_old); + +/*! + * \brief Play a voicemail msg back on a channel. + * + * \param chan + * \param mailbox msg is in. + * \param context of mailbox. + * \param folder voicemail folder to look in. + * \param msg_num message number in the voicemailbox to playback to the channel. + * \param cb + * + * \note Only used by voicemail unit tests. + * + * \retval 0 success + * \retval -1 failure + */ +typedef int (ast_vm_msg_play_fn)(struct ast_channel *chan, const char *mailbox, + const char *context, const char *folder, const char *msg_num, ast_vm_msg_play_cb *cb); + /*! * \brief Set voicemail function callbacks * - * \param copy_recording_to_vm_func, vm_index_to_foldername, vm_mailbox_snapshot_create - * \param vm_mailbox_snapshot_destroy, vm_msg_move, vm_msg_remove, vm_msg_forward, vm_msg_play - * \param[in] has_voicemail_func set function pointer - * \param[in] inboxcount_func set function pointer - * \param[in] inboxcount2_func set function pointer - * \param[in] messagecount_func set function pointer - * \param[in] sayname_func set function pointer + * \param has_voicemail_func set function pointer + * \param inboxcount_func set function pointer + * \param inboxcount2_func set function pointer + * \param messagecount_func set function pointer + * \param sayname_func set function pointer + * \param copy_recording_to_vm_func set function pointer + * \param vm_index_to_foldername_func set function pointer + * \param vm_mailbox_snapshot_create_func set function pointer + * \param vm_mailbox_snapshot_destroy_func set function pointer + * \param vm_msg_move_func set function pointer + * \param vm_msg_remove_func set function pointer + * \param vm_msg_forward_func set function pointer + * \param vm_msg_play_func set function pointer + * * \version 1.6.1 Added inboxcount2_func, sayname_func */ -void ast_install_vm_functions(int (*has_voicemail_func)(const char *mailbox, const char *folder), - int (*inboxcount_func)(const char *mailbox, int *newmsgs, int *oldmsgs), - int (*inboxcount2_func)(const char *mailbox, int *urgentmsgs, int *newmsgs, int *oldmsgs), - int (*messagecount_func)(const char *context, const char *mailbox, const char *folder), - int (*sayname_func)(struct ast_channel *chan, const char *mailbox, const char *context), - int (*copy_recording_to_vm_func)(struct ast_vm_recording_data *vm_rec_data), - const char *vm_index_to_foldername(int id), - struct ast_vm_mailbox_snapshot *(*vm_mailbox_snapshot_create)(const char *mailbox, - const char *context, - const char *folder, - int descending, - enum ast_vm_snapshot_sort_val sort_val, - int combine_INBOX_and_OLD), - struct ast_vm_mailbox_snapshot *(*vm_mailbox_snapshot_destroy)(struct ast_vm_mailbox_snapshot *mailbox_snapshot), - int (*vm_msg_move)(const char *mailbox, - const char *context, - size_t num_msgs, - const char *oldfolder, - const char *old_msg_ids[], - const char *newfolder), - int (*vm_msg_remove)(const char *mailbox, - const char *context, - size_t num_msgs, - const char *folder, - const char *msgs[]), - int (*vm_msg_forward)(const char *from_mailbox, - const char *from_context, - const char *from_folder, - const char *to_mailbox, - const char *to_context, - const char *to_folder, - size_t num_msgs, - const char *msg_ids[], - int delete_old), - int (*vm_msg_play)(struct ast_channel *chan, - const char *mailbox, - const char *context, - const char *folder, - const char *msg_num, - ast_vm_msg_play_cb cb)); +void ast_install_vm_functions(ast_has_voicemail_fn *has_voicemail_func, + ast_inboxcount_fn *inboxcount_func, + ast_inboxcount2_fn *inboxcount2_func, + ast_messagecount_fn *messagecount_func, + ast_sayname_fn *sayname_func, + ast_copy_recording_to_vm_fn *copy_recording_to_vm_func, + ast_vm_index_to_foldername_fn *vm_index_to_foldername_func, + ast_vm_mailbox_snapshot_create_fn *vm_mailbox_snapshot_create_func, + ast_vm_mailbox_snapshot_destroy_fn *vm_mailbox_snapshot_destroy_func, + ast_vm_msg_move_fn *vm_msg_move_func, + ast_vm_msg_remove_fn *vm_msg_remove_func, + ast_vm_msg_forward_fn *vm_msg_forward_func, + ast_vm_msg_play_fn *vm_msg_play_func); void ast_uninstall_vm_functions(void); #ifdef TEST_FRAMEWORK -void ast_install_vm_test_functions(int (*vm_test_destroy_user)(const char *context, const char *mailbox), - int (*vm_test_create_user)(const char *context, const char *mailbox)); +typedef int (ast_vm_test_create_user_fn)(const char *context, const char *mailbox); +typedef int (ast_vm_test_destroy_user_fn)(const char *context, const char *mailbox); + +void ast_install_vm_test_functions(ast_vm_test_create_user_fn *vm_test_create_user_func, + ast_vm_test_destroy_user_fn *vm_test_destroy_user_func); void ast_uninstall_vm_test_functions(void); #endif @@ -467,7 +652,7 @@ int ast_app_messagecount(const char *context, const char *mailbox, const char *f */ const char *ast_vm_index_to_foldername(int id); -/* +/*! * \brief Create a snapshot of a mailbox which contains information about every msg. * * \param mailbox, the mailbox to look for @@ -488,7 +673,7 @@ struct ast_vm_mailbox_snapshot *ast_vm_mailbox_snapshot_create(const char *mailb enum ast_vm_snapshot_sort_val sort_val, int combine_INBOX_and_OLD); -/* +/*! * \brief destroy a snapshot * * \param mailbox_snapshot The snapshot to destroy. @@ -580,7 +765,7 @@ int ast_vm_msg_play(struct ast_channel *chan, const char *context, const char *folder, const char *msg_num, - ast_vm_msg_play_cb cb); + ast_vm_msg_play_cb *cb); #ifdef TEST_FRAMEWORK int ast_vm_test_destroy_user(const char *context, const char *mailbox); @@ -779,7 +964,7 @@ enum ast_getdata_result { AST_GETDATA_COMPLETE = 0, AST_GETDATA_TIMEOUT = 1, AST_GETDATA_INTERRUPTED = 2, - /*! indicates a user terminated empty string rather than an empty string resulting + /*! indicates a user terminated empty string rather than an empty string resulting * from a timeout or other factors */ AST_GETDATA_EMPTY_END_TERMINATED = 3, }; @@ -1070,7 +1255,8 @@ int ast_app_dtget(struct ast_channel *chan, const char *context, char *collect, /*! \brief Allow to record message and have a review option */ int ast_record_review(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime, const char *fmt, int *duration, const char *path); -/*!\brief Decode an encoded control or extended ASCII character +/*! + * \brief Decode an encoded control or extended ASCII character * \param[in] stream String to decode * \param[out] result Decoded character * \param[out] consumed Number of characters used in stream to encode the character @@ -1079,7 +1265,8 @@ int ast_record_review(struct ast_channel *chan, const char *playfile, const char */ int ast_get_encoded_char(const char *stream, char *result, size_t *consumed); -/*!\brief Decode a stream of encoded control or extended ASCII characters +/*! + * \brief Decode a stream of encoded control or extended ASCII characters * \param[in] stream Encoded string * \param[out] result Decoded string * \param[in] result_len Maximum size of the result buffer diff --git a/main/app.c b/main/app.c index 6f70b2101b..9e78417c34 100644 --- a/main/app.c +++ b/main/app.c @@ -426,87 +426,33 @@ int ast_app_run_sub(struct ast_channel *autoservice_chan, struct ast_channel *su return res; } -static int (*ast_has_voicemail_func)(const char *mailbox, const char *folder) = NULL; -static int (*ast_inboxcount_func)(const char *mailbox, int *newmsgs, int *oldmsgs) = NULL; -static int (*ast_inboxcount2_func)(const char *mailbox, int *urgentmsgs, int *newmsgs, int *oldmsgs) = NULL; -static int (*ast_sayname_func)(struct ast_channel *chan, const char *mailbox, const char *context) = NULL; -static int (*ast_messagecount_func)(const char *context, const char *mailbox, const char *folder) = NULL; -static int (*ast_copy_recording_to_vm_func)(struct ast_vm_recording_data *vm_rec_data) = NULL; -static const char *(*ast_vm_index_to_foldername_func)(int id) = NULL; -static struct ast_vm_mailbox_snapshot *(*ast_vm_mailbox_snapshot_create_func)(const char *mailbox, - const char *context, - const char *folder, - int descending, - enum ast_vm_snapshot_sort_val sort_val, - int combine_INBOX_and_OLD) = NULL; -static struct ast_vm_mailbox_snapshot *(*ast_vm_mailbox_snapshot_destroy_func)(struct ast_vm_mailbox_snapshot *mailbox_snapshot) = NULL; -static int (*ast_vm_msg_move_func)(const char *mailbox, - const char *context, - size_t num_msgs, - const char *oldfolder, - const char *old_msg_ids[], - const char *newfolder) = NULL; -static int (*ast_vm_msg_remove_func)(const char *mailbox, - const char *context, - size_t num_msgs, - const char *folder, - const char *msgs[]) = NULL; -static int (*ast_vm_msg_forward_func)(const char *from_mailbox, - const char *from_context, - const char *from_folder, - const char *to_mailbox, - const char *to_context, - const char *to_folder, - size_t num_msgs, - const char *msg_ids[], - int delete_old) = NULL; -static int (*ast_vm_msg_play_func)(struct ast_channel *chan, - const char *mailbox, - const char *context, - const char *folder, - const char *msg_num, - ast_vm_msg_play_cb cb) = NULL; - -void ast_install_vm_functions(int (*has_voicemail_func)(const char *mailbox, const char *folder), - int (*inboxcount_func)(const char *mailbox, int *newmsgs, int *oldmsgs), - int (*inboxcount2_func)(const char *mailbox, int *urgentmsgs, int *newmsgs, int *oldmsgs), - int (*messagecount_func)(const char *context, const char *mailbox, const char *folder), - int (*sayname_func)(struct ast_channel *chan, const char *mailbox, const char *context), - int (*copy_recording_to_vm_func)(struct ast_vm_recording_data *vm_rec_data), - const char *vm_index_to_foldername_func(int id), - struct ast_vm_mailbox_snapshot *(*vm_mailbox_snapshot_create_func)(const char *mailbox, - const char *context, - const char *folder, - int descending, - enum ast_vm_snapshot_sort_val sort_val, - int combine_INBOX_and_OLD), - struct ast_vm_mailbox_snapshot *(*vm_mailbox_snapshot_destroy_func)(struct ast_vm_mailbox_snapshot *mailbox_snapshot), - int (*vm_msg_move_func)(const char *mailbox, - const char *context, - size_t num_msgs, - const char *oldfolder, - const char *old_msg_ids[], - const char *newfolder), - int (*vm_msg_remove_func)(const char *mailbox, - const char *context, - size_t num_msgs, - const char *folder, - const char *msgs[]), - int (*vm_msg_forward_func)(const char *from_mailbox, - const char *from_context, - const char *from_folder, - const char *to_mailbox, - const char *to_context, - const char *to_folder, - size_t num_msgs, - const char *msg_ids[], - int delete_old), - int (*vm_msg_play_func)(struct ast_channel *chan, - const char *mailbox, - const char *context, - const char *folder, - const char *msg_num, - ast_vm_msg_play_cb cb)) +static ast_has_voicemail_fn *ast_has_voicemail_func = NULL; +static ast_inboxcount_fn *ast_inboxcount_func = NULL; +static ast_inboxcount2_fn *ast_inboxcount2_func = NULL; +static ast_sayname_fn *ast_sayname_func = NULL; +static ast_messagecount_fn *ast_messagecount_func = NULL; +static ast_copy_recording_to_vm_fn *ast_copy_recording_to_vm_func = NULL; +static ast_vm_index_to_foldername_fn *ast_vm_index_to_foldername_func = NULL; +static ast_vm_mailbox_snapshot_create_fn *ast_vm_mailbox_snapshot_create_func = NULL; +static ast_vm_mailbox_snapshot_destroy_fn *ast_vm_mailbox_snapshot_destroy_func = NULL; +static ast_vm_msg_move_fn *ast_vm_msg_move_func = NULL; +static ast_vm_msg_remove_fn *ast_vm_msg_remove_func = NULL; +static ast_vm_msg_forward_fn *ast_vm_msg_forward_func = NULL; +static ast_vm_msg_play_fn *ast_vm_msg_play_func = NULL; + +void ast_install_vm_functions(ast_has_voicemail_fn *has_voicemail_func, + ast_inboxcount_fn *inboxcount_func, + ast_inboxcount2_fn *inboxcount2_func, + ast_messagecount_fn *messagecount_func, + ast_sayname_fn *sayname_func, + ast_copy_recording_to_vm_fn *copy_recording_to_vm_func, + ast_vm_index_to_foldername_fn *vm_index_to_foldername_func, + ast_vm_mailbox_snapshot_create_fn *vm_mailbox_snapshot_create_func, + ast_vm_mailbox_snapshot_destroy_fn *vm_mailbox_snapshot_destroy_func, + ast_vm_msg_move_fn *vm_msg_move_func, + ast_vm_msg_remove_fn *vm_msg_remove_func, + ast_vm_msg_forward_fn *vm_msg_forward_func, + ast_vm_msg_play_fn *vm_msg_play_func) { ast_has_voicemail_func = has_voicemail_func; ast_inboxcount_func = inboxcount_func; @@ -541,11 +487,11 @@ void ast_uninstall_vm_functions(void) } #ifdef TEST_FRAMEWORK -int (*ast_vm_test_create_user_func)(const char *context, const char *mailbox) = NULL; -int (*ast_vm_test_destroy_user_func)(const char *context, const char *mailbox) = NULL; +static ast_vm_test_create_user_fn *ast_vm_test_create_user_func = NULL; +static ast_vm_test_destroy_user_fn *ast_vm_test_destroy_user_func = NULL; -void ast_install_vm_test_functions(int (*vm_test_create_user_func)(const char *context, const char *mailbox), - int (*vm_test_destroy_user_func)(const char *context, const char *mailbox)) +void ast_install_vm_test_functions(ast_vm_test_create_user_fn *vm_test_create_user_func, + ast_vm_test_destroy_user_fn *vm_test_destroy_user_func) { ast_vm_test_create_user_func = vm_test_create_user_func; ast_vm_test_destroy_user_func = vm_test_destroy_user_func; @@ -735,7 +681,7 @@ int ast_vm_msg_play(struct ast_channel *chan, const char *context, const char *folder, const char *msg_num, - ast_vm_msg_play_cb cb) + ast_vm_msg_play_cb *cb) { if (ast_vm_msg_play_func) { return ast_vm_msg_play_func(chan, mailbox, context, folder, msg_num, cb);