[svn-commits] tilghman: branch tilghman/str_substitution r185191 - /team/tilghman/str_subst...
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Mon Mar 30 17:30:08 CDT 2009
Author: tilghman
Date: Mon Mar 30 17:30:05 2009
New Revision: 185191
URL: http://svn.digium.com/svn-view/asterisk?view=rev&rev=185191
Log:
Yet more documentation fixes
Modified:
team/tilghman/str_substitution/include/asterisk/pbx.h
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=185191&r1=185190&r2=185191
==============================================================================
--- team/tilghman/str_substitution/include/asterisk/pbx.h (original)
+++ team/tilghman/str_substitution/include/asterisk/pbx.h Mon Mar 30 17:30:05 2009
@@ -100,7 +100,7 @@
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 */
+ /*! 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;
@@ -263,7 +263,7 @@
*/
struct ast_context *ast_context_find(const char *name);
-/*! \brief The result codes when starting the PBX on a channelwith \see ast_pbx_start.
+/*! \brief The result codes when starting the PBX on a channel with \see ast_pbx_start.
AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf
*/
enum ast_pbx_result {
@@ -418,21 +418,33 @@
* \param maxlen size of hint buffer
* \param name buffer for name portion of hint
* \param maxnamelen size of name buffer
- * \param c this is not important
+ * \param c Channel from which to return the hint. This is only important when the hint or name contains an expression to be expanded.
* \param context which context to look in
* \param exten which extension to search for
*
* \return If an extension within the given context with the priority PRIORITY_HINT
- * is found a non zero value will be returned.
+ * 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);
+/*!
+ * \brief If an extension hint exists, return non-zero
+ *
+ * \param hint buffer for hint
+ * \param maxlen Maximum size of hint buffer (<0 to prevent growth, >0 to limit growth to that number of bytes, or 0 for unlimited growth)
+ * \param name buffer for name portion of hint
+ * \param maxnamelen Maxium size of name buffer (<0 to prevent growth, >0 to limit growth to that number of bytes, or 0 for unlimited growth)
+ * \param c Channel from which to return the hint. This is only important when the hint or name contains an expression to be expanded.
+ * \param context which context to look in
+ * \param exten which extension to search for
+ *
+ * \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_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
@@ -835,8 +847,13 @@
*/
int ast_context_unlockmacro(const char *macrocontext);
+/*!\brief Set the channel to next execute the specified dialplan location.
+ * \see ast_async_parseable_goto, ast_async_goto_if_exists
+ */
int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
+/*!\brief Set the channel to next execute the specified dialplan location.
+ */
int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority);
/*! Synchronously or asynchronously make an outbound call and send it to a
@@ -890,7 +907,7 @@
const char *ast_get_switch_registrar(struct ast_sw *sw);
/*! @} */
-/*!\brief Walking functions ... */
+/*! @name Walking functions ... */
/*! @{ */
struct ast_context *ast_walk_contexts(struct ast_context *con);
struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
@@ -904,12 +921,14 @@
struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
/*! @} */
-/*!
+/*!\brief Create a human-readable string, specifying all variables and their corresponding values.
+ * \param chan Channel from which to read variables
+ * \param buf Dynamic string in which to place the result (should be allocated with \see ast_str_create).
* \note Will lock the channel.
*/
int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **buf);
-/*!
+/*!\brief Return a pointer to the value of the corresponding channel variable.
* \note Will lock the channel.
*
* \note This function will return a pointer to the buffer inside the channel
@@ -928,47 +947,77 @@
*/
const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
-/*!
+/*!\brief Add a variable to the channel variable stack, without removing any previously set value.
* \note Will lock the channel.
*/
void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
-/*!
- * \note Will lock the channel.
+/*!\brief Add a variable to the channel variable stack, removing the most recently set value for the same name.
+ * \note Will lock the channel. May also be used to set a channel dialplan function to a particular value.
+ * \see ast_func_write
*/
void pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
-/*!
+/*!\brief Retrieve the value of a builtin variable or variable from the channel variable stack.
* \note Will lock the channel.
*/
void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
void pbx_builtin_clear_globals(void);
-/*!
+/*!\brief Parse and set a single channel variable, where the name and value are separated with an '=' character.
* \note Will lock the channel.
*/
int pbx_builtin_setvar(struct ast_channel *chan, void *data);
+
+/*!\brief Parse and set multiple channel variables, where the pairs are separated by the ',' character, and name and value are separated with an '=' character.
+ * \note Will lock the channel.
+ */
int pbx_builtin_setvar_multiple(struct ast_channel *chan, void *data);
int pbx_builtin_raise_exception(struct ast_channel *chan, void *data);
+/*! @name Substitution routines, using static string buffers
+ * @{ */
void pbx_substitute_variables_helper(struct ast_channel *c, const char *cp1, char *cp2, int count);
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
+/*! @} */
+
+/*! @name 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.
+ */
+char *ast_str_retrieve_variable(struct ast_str **buf, int maxlen, struct ast_channel *chan, struct varshead *headp, const char *var);
+
+/*!
+ * \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 templ Variable template to expand.
+ */
+void ast_str_substitute_variables(struct ast_str **buf, int maxlen, struct ast_channel *chan, const char *templ);
+
+/*!
+ * \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 headp If no channel is specified, a channel list from which to extract variable values
+ * \param templ Variable template to expand.
+ */
+void ast_str_substitute_variables_varshead(struct ast_str **buf, int maxlen, struct varshead *headp, const char *templ);
+
+/*!
+ * \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 c 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 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);
/*! @} */
@@ -997,10 +1046,6 @@
int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
/*!
- * \note I can find neither parsable nor parseable at dictionary.com,
- * but google gives me 169000 hits for parseable and only 49,800
- * for parsable
- *
* \note This function will handle locking the channel as needed.
*/
int ast_parseable_goto(struct ast_channel *chan, const char *goto_string);
More information about the svn-commits
mailing list