[Asterisk-cvs] asterisk/include/asterisk app.h,1.40,1.41

[kpfleming]

Update of /usr/cvsroot/asterisk/include/asterisk
In directory mongoose.digium.com:/tmp/cvs-serv619/include/asterisk

Modified Files:
	app.h 
Log Message:
add some macros to simplify application argument parsing


Index: app.h
===================================================================
RCS file: /usr/cvsroot/asterisk/include/asterisk/app.h,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -d -r1.40 -r1.41
--- app.h	24 Oct 2005 20:12:06 -0000	1.40
+++ app.h	28 Oct 2005 16:19:43 -0000	1.41
@@ -182,6 +182,46 @@
 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 @@
   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);