add some macros to simplify application argument parsing

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@6873 65c4cc65-6c06-0410-ace0-fbb531ad65f3

diff --git a/include/asterisk/app.h b/include/asterisk/app.h
index 36f2453..5f64f33 100755 (executable)
--- a/include/asterisk/app.h
+++ b/include/asterisk/app.h
@@ -182,6 +182,46 @@ int ast_app_group_get_count(char *group, char *category);
 int ast_app_group_match_get_count(char *groupmatch, char *category);
 
 /*!
+  \brief Define an application argument
+  \param name The name of the argument
+*/
+#define AST_APP_ARG(name) char *name
+
+/*!
+  \brief Declare a structure to hold the application's arguments.
+  \param name The name of the structure
+  \param arglist The list of arguments, defined using AST_APP_ARG
+
+  This macro defines a structure intended to be used in a call
+  to ast_separate_app_args(). The structure includes all the
+  arguments specified, plus an argv array that overlays them and an
+  argc argument counter. The arguments must be declared using AST_APP_ARG,
+  and they will all be character pointers (strings).
+
+  Note: The structure is <b>not</b> initialized, as the call to
+  ast_separate_app_args() will perform that function before parsing
+  the arguments.
+ */
+#define AST_DECLARE_APP_ARGS(name, arglist) \
+       struct { \
+               int argc; \
+               char *argv[0]; \
+               arglist \
+       } name;
+
+/*!
+  \brief Performs the 'standard' argument separation process for an application.
+  \param args An argument structure defined using AST_DECLARE_APP_ARGS
+  \param parse A modifiable buffer containing the input to be parsed
+
+  This function will separate the input string using the standard argument
+  separator character '|' and fill in the provided structure, including
+  the argc argument counter field.
+ */
+#define AST_STANDARD_APP_ARGS(args, parse) \
+       args.argc = ast_separate_app_args(parse, '|', args.argv, (sizeof(args) - sizeof(args.argc)) / sizeof(args.argv[0]))
+       
+/*!
   \brief Separate a string into arguments in an array
   \param buf The string to be parsed (this must be a writable copy, as it will be modified)
   \param delim The character to be used to delimit arguments
@@ -191,6 +231,8 @@ int ast_app_group_match_get_count(char *groupmatch, char *category);
   Note: if there are more arguments in the string than the array will hold, the last element of
   the array will contain the remaining arguments, not separated.
 
+  The array will be completely zeroed by this function before it populates any entries.
+
   \return The number of arguments found, or zero if the function arguments are not valid.
 */
 int ast_separate_app_args(char *buf, char delim, char **array, int arraylen);