[asterisk-commits] tilghman: branch tilghman/str_substitution r185190 - in /team/tilghman/str_su...

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Mon Mar 30 16:33:41 CDT 2009


Author: tilghman
Date: Mon Mar 30 16:33:26 2009
New Revision: 185190

URL: http://svn.digium.com/svn-view/asterisk?view=rev&rev=185190
Log:
Add API documentation to pbx.h and fix app_macro

Modified:
    team/tilghman/str_substitution/apps/app_macro.c
    team/tilghman/str_substitution/include/asterisk/pbx.h

Modified: team/tilghman/str_substitution/apps/app_macro.c
URL: http://svn.digium.com/svn-view/asterisk/team/tilghman/str_substitution/apps/app_macro.c?view=diff&rev=185190&r1=185189&r2=185190
==============================================================================
--- team/tilghman/str_substitution/apps/app_macro.c (original)
+++ team/tilghman/str_substitution/apps/app_macro.c Mon Mar 30 16:33:26 2009
@@ -243,10 +243,6 @@
 	char *save_macro_offset;
 	struct ast_datastore *macro_store = ast_channel_datastore_find(chan, &macro_ds_info, NULL);
 
-	if (!tmp_subst) {
-		return -1;
-	}
- 
 	if (ast_strlen_zero(data)) {
 		ast_log(LOG_WARNING, "Macro() requires arguments. See \"core show application macro\" for help.\n");
 		return -1;

Modified: team/tilghman/str_substitution/include/asterisk/pbx.h
URL: http://svn.digium.com/svn-view/asterisk/team/tilghman/str_substitution/include/asterisk/pbx.h?view=diff&rev=185190&r1=185189&r2=185190
==============================================================================
--- team/tilghman/str_substitution/include/asterisk/pbx.h (original)
+++ team/tilghman/str_substitution/include/asterisk/pbx.h Mon Mar 30 16:33:26 2009
@@ -88,10 +88,20 @@
 		AST_STRING_FIELD(seealso);      /*!< See also */
 	);
 	enum ast_doc_src docsrc;		/*!< Where the documentation come from */
-	int (*read)(struct ast_channel *, const char *, char *, char *, size_t);	/*!< Read function, if read is supported */
-	int (*read2)(struct ast_channel *, const char *, char *, struct ast_str **, int);	/*!< Read function, if read is supported */
-	size_t read_max;                                                            /*!< If no read2 function is provided, what maximum size? */
-	int (*write)(struct ast_channel *, const char *, char *, const char *);		/*!< Write function, if write is supported */
+	/*! Read function, if read is supported */
+	int (*read)(struct ast_channel *, const char *, char *, char *, size_t);
+	/*! Read function, if read is supported.  Note: only one of read or read2
+	 * needs to be implemented.  In new code, read2 should be implemented as
+	 * the way forward, but they should return identical results, within the
+	 * constraints of buffer size, if both are implemented.  That is, if the
+	 * read function is handed a 16-byte buffer, and the result is 17 bytes
+	 * long, then the first 15 bytes (remember NULL terminator) should be
+	 * the same for both the read and the read2 methods. */
+	int (*read2)(struct ast_channel *, const char *, char *, struct ast_str **, int);
+	/*! If no read2 function is provided, what maximum size? */
+	size_t read_max;
+	/*!< Write function, if write is supported */
+	int (*write)(struct ast_channel *, const char *, char *, const char *);
 	struct ast_module *mod;         /*!< Module this custom function belongs to */
 	AST_RWLIST_ENTRY(ast_custom_function) acflist;
 };
@@ -415,11 +425,14 @@
  * \return If an extension within the given context with the priority PRIORITY_HINT
  * is found a non zero value will be returned.
  * Otherwise, 0 is returned.
+ *
+ * @{
  */
 int ast_get_hint(char *hint, int maxlen, char *name, int maxnamelen, 
 	struct ast_channel *c, const char *context, const char *exten);
 int ast_str_get_hint(struct ast_str **hint, int maxlen, struct ast_str **name, int maxnamelen, 
 	struct ast_channel *c, const char *context, const char *exten);
+/*! @} */
 
 /*!
  * \brief Determine whether an extension exists
@@ -877,7 +890,8 @@
 const char *ast_get_switch_registrar(struct ast_sw *sw);
 /*! @} */
 
-/* Walking functions ... */
+/*!\brief Walking functions ... */
+/*! @{ */
 struct ast_context *ast_walk_contexts(struct ast_context *con);
 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
 	struct ast_exten *priority);
@@ -888,6 +902,7 @@
 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
 	struct ast_ignorepat *ip);
 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
+/*! @} */
 
 /*!
  * \note Will lock the channel.
@@ -941,10 +956,21 @@
 void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
 void pbx_substitute_variables_helper_full(struct ast_channel *c, struct varshead *headp, const char *cp1, char *cp2, int cp2_size, size_t *used);
 
+/*!\brief Substitution routines, using dynamic string buffers
+ * \param buf Result will be placed in this buffer.
+ * \param maxlen -1 if the buffer should not grow, 0 if the buffer may grow to any size, and >0 if the buffer should grow only to that number of bytes.
+ * \param chan Channel variables from which to extract values, and channel to pass to any dialplan functions.
+ * \param headp If no channel is specified, a channel list from which to extract variable values
+ * \param var Variable name to retrieve.
+ * \param templ Variable template to expand.
+ * \param used Number of bytes read from the template.
+ * @{
+ */
 char *ast_str_retrieve_variable(struct ast_str **buf, int maxlen, struct ast_channel *chan, struct varshead *headp, const char *var);
 void ast_str_substitute_variables(struct ast_str **buf, int maxlen, struct ast_channel *chan, const char *templ);
 void ast_str_substitute_variables_varshead(struct ast_str **buf, int maxlen, struct varshead *headp, const char *templ);
 void ast_str_substitute_variables_full(struct ast_str **buf, int maxlen, struct ast_channel *c, struct varshead *headp, const char *templ, size_t *used);
+/*! @} */
 
 int ast_extension_patmatch(const char *pattern, const char *data);
 
@@ -1027,14 +1053,18 @@
  * \param chan Channel to execute on
  * \param function Data containing the function call string (will be modified)
  * \param workspace A pointer to safe memory to use for a return value 
+ * \param str A dynamic string buffer into which to place the result.
  * \param len the number of bytes in workspace
  *
  * This application executes a function in read mode on a given channel.
  *
  * \return zero on success, non-zero on failure
+ *
+ * @{
  */
 int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len);
 int ast_func_read2(struct ast_channel *chan, const char *function, struct ast_str **str, int maxlen);
+/*! @} */
 
 /*!
  * \brief executes a write operation on a function
@@ -1101,9 +1131,11 @@
 int ast_wrlock_contexts_version(void);
 	
 
-/* hashtable functions for contexts */
+/*!\brief hashtable functions for contexts */
+/*! @{ */
 int ast_hashtab_compare_contexts(const void *ah_a, const void *ah_b);
 unsigned int ast_hashtab_hash_contexts(const void *obj);
+/*! @} */
 
 #if defined(__cplusplus) || defined(c_plusplus)
 }




More information about the asterisk-commits mailing list