diff options
Diffstat (limited to 'include/asterisk/pbx.h')
| -rw-r--r-- | include/asterisk/pbx.h | 89 |
1 files changed, 86 insertions, 3 deletions
diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h index cd327661f..95a23f8cc 100644 --- a/include/asterisk/pbx.h +++ b/include/asterisk/pbx.h @@ -90,8 +90,20 @@ struct ast_custom_function { 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 (*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 **, ssize_t); + /*! 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; }; @@ -422,6 +434,24 @@ int ast_extension_state_del(int id, ast_state_cb_type callback); int ast_get_hint(char *hint, int hintsize, char *name, int namesize, 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 hintsize 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 namesize Maximum 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, ssize_t hintsize, struct ast_str **name, ssize_t namesize, + struct ast_channel *c, const char *context, const char *exten); + /*! * \brief Determine whether an extension exists * @@ -960,7 +990,45 @@ int pbx_builtin_raise_exception(struct ast_channel *chan, void *data); 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); -void ast_str_substitute_variables(struct ast_str **buf, size_t maxlen, struct ast_channel *chan, const char *templ); +/*! @} */ +/*! @} */ + +/*! @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. + */ +const char *ast_str_retrieve_variable(struct ast_str **buf, ssize_t 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, ssize_t 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, ssize_t 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. + */ +void ast_str_substitute_variables_full(struct ast_str **buf, ssize_t maxlen, struct ast_channel *c, struct varshead *headp, const char *templ, size_t *used); /*! @} */ int ast_extension_patmatch(const char *pattern, const char *data); @@ -1050,6 +1118,21 @@ int ast_processed_calls(void); int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len); /*! + * \brief executes a read operation on a function + * + * \param chan Channel to execute on + * \param function Data containing the function call string (will be modified) + * \param str A dynamic string buffer into which to place the result. + * \param maxlen <0 if the dynamic buffer should not grow; >0 if the dynamic buffer should be limited to that number of bytes; 0 if the dynamic buffer has no upper limit + * + * This application executes a function in read mode on a given channel. + * + * \retval 0 success + * \retval non-zero failure + */ +int ast_func_read2(struct ast_channel *chan, const char *function, struct ast_str **str, ssize_t maxlen); + +/*! * \brief executes a write operation on a function * * \param chan Channel to execute on |