[asterisk-commits] brushtyler: branch brushtyler/voicemail_menu_branch r213081 - /team/brushtyle...

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Wed Aug 19 12:12:56 CDT 2009


Author: brushtyler
Date: Wed Aug 19 12:12:52 2009
New Revision: 213081

URL: http://svn.asterisk.org/svn-view/asterisk?view=rev&rev=213081
Log:
added some comments

Modified:
    team/brushtyler/voicemail_menu_branch/apps/newvoicemail.c

Modified: team/brushtyler/voicemail_menu_branch/apps/newvoicemail.c
URL: http://svn.asterisk.org/svn-view/asterisk/team/brushtyler/voicemail_menu_branch/apps/newvoicemail.c?view=diff&rev=213081&r1=213080&r2=213081
==============================================================================
--- team/brushtyler/voicemail_menu_branch/apps/newvoicemail.c (original)
+++ team/brushtyler/voicemail_menu_branch/apps/newvoicemail.c Wed Aug 19 12:12:52 2009
@@ -2028,6 +2028,8 @@
  * \param vms
  * \param vmu
  * \param s_cid to return the sender cid
+ *
+ * This is called to retrieve information to the sender of a message
  * 
  * \return -1 if an error is occurred, 1 if sender has a mailbox, 0 otherwise.
  */
@@ -2087,6 +2089,8 @@
  * \param chan
  * \param vms
  * \param vmu
+ *
+ * This is called to set some channel variables to retrieve message information in the voicemail_menu.conf
  * 
  * \return zero on success, -1 on error.
  */
@@ -2149,6 +2153,8 @@
  * \param chan
  * \param vms
  * \param vmu
+ *
+ * This is called to set some channel variables to retrieve global information in the voicemail_menu.conf
  * 
  * \return zero on success, -1 on error.
  */
@@ -2192,6 +2198,11 @@
  * \param vms
  * \param fold to return the folder as second param in args
  * \param num to return the message number as first param in args
+ *
+ * This is called to parse a string that contains as first arg a message number and as second arg a folder name. 
+ * If the folder name is omitted the message number is relative on the current message, if is "current" or an existent 
+ *  folder name instead the message number is an absolute number. If both the message number and folder is omitted, 
+ *  is considered as the current message (number 0 and folder "").
  * 
  * \return zero on success, -1 on error.
  */
@@ -2263,6 +2274,9 @@
  * \param vmu
  * \param vm_var
  * \param result none
+ *
+ * This function calls the parse_message_num() to retrieve the number and folder 
+ *  from args, then sets that message as current message
  * 
  * \return zero on success, 1 on error that affects only the current 
  *  action, -1 on other errors.
@@ -2311,7 +2325,7 @@
 }
 
 /*!
- * \brief Check a mailbox existance
+ * \brief Check a mailbox existence
  * \param args the mailbox number
  * \param chan
  * \param vms
@@ -2341,13 +2355,16 @@
 
 /*!
  * \brief Check if a message exists
- * \param args can conteins number and folder of the message to check 
+ * \param args can contains number and folder of the message to check 
  *  or the name of a special message (unv, busy, name, temp, rec)
  * \param chan
  * \param vms
  * \param vmu
  * \param vm_var
  * \param result is "1" if the message exists, "0" otherwise
+ *
+ * This function retrieves the message number and folder or the special message 
+ *  name from args and makes an existence test
  */
 static int vmm_msg_exists(const char* args, struct ast_channel* chan, struct vm_state* vms,
             struct ast_vm_user* vmu, struct exec_main_var* vm_var, char **result)
@@ -2425,6 +2442,9 @@
  * \param vm_var
  * \param result none
  * 
+ * This function takes from args the name of a folder and then saves the current 
+ *  selected message in that folder.
+ * 
  * \return zero on success, 1 if an error occurred but affects only the current 
  *  action, -1 on other errors.
  */
@@ -2468,6 +2488,9 @@
  * \brief Parse the greeting and special message names
  * \param args a message name to parse
  * \param ret the special message name used in the application
+ * 
+ * This function parses the greetings/special message name and returns the 
+ * special name used by the programs to refer it.
  * 
  * \return zero on success, -1 if the passed message name doesn't match any
  *  special message names
@@ -2529,13 +2552,20 @@
 		    struct ast_vm_user* vmu, struct exec_main_var* vm_var);
 
 /*!
- * \brief Record a temporary message
+ * \brief Record a temporary message (voice message and information file) 
+ *  or a greeting message (voice message only)
  * \param args none
  * \param chan
  * \param vms
  * \param vmu
  * \param vm_var
  * \param result none
+ * 
+ * This is used to record a temporary message or greeting message. If args 
+ *  contains the name of a greeting message (unv, busy, name, temp) then record 
+ *  only the voice message and save it, else if contains the keyword for 
+ *  temporary message (rec) the voice message are recorded and the information 
+ *  file are created too.
  * 
  * \return zero on success, 1 if an error occurred but affects only the current 
  *  action, -1 on other errors.
@@ -2568,6 +2598,9 @@
  * \param vmu
  * \param vm_var
  * \param result none
+ * 
+ * This function plays a sound file using args as name of the file to play. Is
+ *  used in voicemail_menu.conf to play the menu instructions.
  * 
  * \return zero on success, -1 on errors.
  */
@@ -2612,6 +2645,9 @@
  * \param vm_var
  * \param result none
  * 
+ * This function retrieves the message number and folder from args and then
+ *  sets that message as current and plays it.
+ * 
  * \return zero on success, 1 if an error occurred but affects only the current 
  *  action, -1 on other errors.
  */
@@ -2657,6 +2693,11 @@
  * \param vms
  * \param vmu
  * \param vm_var
+ * 
+ * This function is used to record both the voice message and the related 
+ *  information file. It creates the information file and then records the 
+ *  voice message. If an error occurs or if the recorded file is too short, 
+ *  both the two files are deleted.  
  * 
  * \return zero on success, 1 if an error occurred but affects only the current 
  *  action, -1 on other errors.
@@ -2772,7 +2813,18 @@
 	return res;
 }
 
-/* play, record, store and delete a greeting message or a temporary message */
+/*!
+ * \brief Play, record, store and delete a greeting message or a temporary message
+ * \param chan
+ * \param type is the message type
+ * \param option to choose an action to do
+ * \param vms
+ * \param vmu
+ * \param vm_var
+ * 
+ * \return zero on success, 1 if an error occurred but affects only the current 
+ *  action, -1 on other errors.
+ */
 static int review_record_store_delete(struct ast_channel *chan, const char *type, int option, 
              struct vm_state* vms, struct ast_vm_user* vmu, struct exec_main_var* vm_var)
 {
@@ -2855,7 +2907,18 @@
     return -1;
 }
 
-/* change the user password */
+/*!
+ * \brief Change the user password
+ * \param args none
+ * \param chan
+ * \param vms
+ * \param vmu
+ * \param vm_var
+ * \param result none
+ * 
+ * \return zero on success, 1 if an error occurred but affects only the current 
+ *  action, -1 on other errors.
+ */
 static int vmm_change_password(const char* args, struct ast_channel* chan, struct vm_state* vms,
 		    struct ast_vm_user* vmu, struct exec_main_var* vm_var, char **result)
 {
@@ -2915,6 +2978,18 @@
     return 0;
 }
 
+/*!
+ * \brief Change the current opened folder
+ * \param args folder to open
+ * \param chan
+ * \param vms
+ * \param vmu
+ * \param vm_var
+ * \param result none
+ * 
+ * \return zero on success, 1 if an error occurred but affects only the current 
+ *  action, -1 on other errors.
+ */
 static int vmm_change_to(const char *args, struct ast_channel* chan, struct vm_state* vms,
 			 struct ast_vm_user* vmu, struct exec_main_var* vm_var, char **result)
 {
@@ -2949,6 +3024,19 @@
 	return 0;
 }
 
+/*!
+ * \brief Set or unset a message for deletion or delete a greeting/temporary message
+ * \param args can contains the message number and folder or a special 
+ *  message type (unv, busy, name, temp, rec)
+ * \param chan
+ * \param vms
+ * \param vmu
+ * \param vm_var
+ * \param result none
+ * 
+ * \return zero on success, 1 if an error occurred but affects only the current 
+ *  action, -1 on other errors.
+ */
 static int vmm_delete(const char* args, struct ast_channel* chan, struct vm_state* vms,
 		      struct ast_vm_user* vmu, struct exec_main_var* vm_var, char **result)
 {
@@ -3000,6 +3088,19 @@
 	return 0;
 }
 
+/*!
+ * \brief Forward a message to another mailbox
+ * \param args the recipient mailbox and optionally the type of special message 
+ *  to forward
+ * \param chan
+ * \param vms
+ * \param vmu
+ * \param vm_var
+ * \param result none
+ * 
+ * \return zero on success, 1 if an error occurred but affects only the current 
+ *  action, -1 on other errors.
+ */
 static int vmm_forward_msg(const char* args, struct ast_channel* chan, struct vm_state* vms, 
             struct ast_vm_user* vmu, struct exec_main_var* vm_var, char **result)
 {
@@ -3057,6 +3158,18 @@
     return exec_skipaftercmd(chan, vms, vmu, vm_var);
 }
 
+/*!
+ * \brief Play the message information
+ * \param args can contains the message number and folder
+ * \param chan
+ * \param vms
+ * \param vmu
+ * \param vm_var
+ * \param result none
+ * 
+ * \return zero on success, 1 if an error occurred but affects only the current 
+ *  action, -1 on other errors.
+ */
 static int vmm_envelope(const char* args, struct ast_channel* chan, struct vm_state* vms,
 			struct ast_vm_user* vmu, struct exec_main_var* vm_var, char **result)
 {
@@ -3075,7 +3188,18 @@
     return res;
 }
 
-
+/*!
+ * \brief Make an external call
+ * \param args the number to call
+ * \param chan
+ * \param vms
+ * \param vmu
+ * \param vm_var
+ * \param result none
+ * 
+ * \return zero on success, 1 if an error occurred but affects only the current 
+ *  action, -1 on other errors.
+ */
 static int vmm_dialout(const char* args, struct ast_channel* chan, struct vm_state* vms,
 		       struct ast_vm_user* vmu, struct exec_main_var* vm_var, char **result)
 {
@@ -3089,15 +3213,30 @@
 		return 1;
 
 	if (option_verbose > 2)
-		ast_verbose( VERBOSE_PREFIX_3 "Placing outgoing call to extension '%s' in context '%s' from context '%s'\n", args, vmu->dialout, chan->context);
+		ast_verbose(VERBOSE_PREFIX_3 "Placing outgoing call to extension '%s' in context '%s' from context '%s'\n", args, vmu->dialout, chan->context);
 
 	ast_copy_string(chan->exten, args, sizeof(chan->exten));
 	ast_copy_string(chan->context, vmu->dialout, sizeof(chan->context));
 	chan->priority = 0;
+    vm_var->silentexit = 1; /* exit from voicemail app */
 	return 0;
 }
 
-/* exec a function by variables substitution and, if requireq, subfunctions parse and execution */
+/*!
+ * \brief Exec a function by variables substitution and subfunctions parse and execution
+ * \param chan
+ * \param vms
+ * \param vmu
+ * \param vm_var
+ * \param r_level number of function recursive call, set it to 0 when call this function
+ * \param function the function to execute
+ * \param result the result return by the function execution
+ * \param depth the actual menu level, incremented when call another menu
+ * \param res used to return menu informations (i.e. jump to other menu, pressed digits)
+ *  or NULL if only the function execution is required (i.e. test a condition)
+ * 
+ * \return zero on success, -1 on error, the digit pressed by user.
+ */
 static int exec_function(struct ast_channel *chan, struct vm_state* vms, struct ast_vm_user *vmu, 
     struct exec_main_var* vm_var, int r_level, const char *function, char **result, int depth, struct exec_result* res)
 {
@@ -3266,6 +3405,16 @@
 #if debug
 		ast_log(LOG_NOTICE, "RESULT Function: %s(%s) => %s\n", my_f[i].name, buf, *result ? *result : "");
 #endif
+        /* if the previous action want to exit from voicemail application */
+        if (vm_var->silentexit) {
+            vms->exiting = 1;
+            if (res) {
+                res->code = VMM_RETURN;
+        		res->steps = depth + 1;
+                return 0;
+            }
+            return -1;
+        }
 		if ((digit >= '0' && digit <= '9') || digit == '#' || digit == '*') {
             /* digit pressed, save it */
             if (res)
@@ -3292,7 +3441,7 @@
             res->code = VMM_CONTINUE;
         return 0;
     }
-
+    /* if an error occurs then return it */
     if (digit < 0) {
         *result = NULL;
         if (res) {
@@ -3324,10 +3473,16 @@
     return digit;
 }
 
-/*! \brief determine if an entry condition is enabled.
- * If no condition return -1
- * If the condition is verified return 1
- * If the condition is not verified (NULL, 0, empty string) return 0
+/*!
+ * \brief Evaluates an entry condition
+ * \param condition the entry condition to evaluate
+ * \param chan
+ * \param vms
+ * \param vmu
+ * \param vm_var
+ * 
+ * \return zero if result is NULL or "0" or an empty string (condition not verified), 
+ *  -1 if no condition, 1 in the other cases (condition is verified).
  */
 static int enabled(const char *condition, struct ast_channel *chan, struct vm_state* vms, 
             struct ast_vm_user *vmu, struct exec_main_var* vm_var)
@@ -3960,13 +4115,14 @@
 	}
 #endif
 
-	/* before call the do_menu we ave to initialize the value of the fields of 
+	/* before call the do_menu we have to initialize the value of the fields of 
      * the structure exec_main_var */
 	vm_var.useadsi = useadsi;
 	vm_var.play_folder = play_folder;
 	vm_var.record_gain = record_gain;
     vm_var.in_urgent = in_urgent;
     vm_var.play_auto = play_auto;
+    vm_var.silentexit = 0;
 
 	if(context)
 		vm_var.context = ast_strdupa(context);
@@ -3979,8 +4135,11 @@
 	ast_stopstream(chan);
 	/* adsi_goodbye(chan);
 	if (useadsi)
-		ast_adsi_unload_session(chan);
-	*/
+		ast_adsi_unload_session(chan); */
+
+    if (vm_var.silentexit) /* called a dialout or a callback */
+		res = ast_play_and_wait(chan, "vm-dialout");
+
 	if (vmu)
 		close_mailbox(&vms, vmu);
     /* delete the temporary recorded message */




More information about the asterisk-commits mailing list