Merge str_substitution branch.

This branch adds additional methods to dialplan functions, whereby the result
buffers are now dynamic buffers, which can be expanded to the size of any
result.  No longer are variable substitutions limited to 4095 bytes of data.
In addition, the common case of needing buffers much smaller than that will
enable substitution to only take up the amount of memory actually needed.
The existing variable substitution routines are still available, but users
of those API calls should transition to using the dynamic-buffer APIs.
Reviewboard: http://reviewboard.digium.com/r/174/


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@191140 f38db490-d61c-443f-a65b-d21fe96a405b

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