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

3 files changed, 131 insertions, 20 deletions

diff --git a/include/asterisk/ast_expr.h b/include/asterisk/ast_expr.h
index a89b7b9a1..2dcb71f63 100644
--- a/include/asterisk/ast_expr.h
+++ b/include/asterisk/ast_expr.h
@@ -31,8 +31,24 @@
 extern "C" {
 #endif
 
+/*!\brief Evaluate the given expression
+ * \param expr An expression
+ * \param buf Result buffer
+ * \param length Size of the result buffer, in bytes
+ * \param chan Channel to use for evaluating included dialplan functions, if any
+ * \return Length of the result string, in bytes
+ */
 int ast_expr(char *expr, char *buf, int length, struct ast_channel *chan);
 
+/*!\brief Evaluate the given expression
+ * \param str Dynamic result buffer
+ * \param maxlen <0 if the size of the buffer should remain constant, >0 if the size of the buffer should expand to that many bytes, maximum, or 0 for unlimited expansion of the result buffer
+ * \param chan Channel to use for evaluating included dialplan functions, if any
+ * \param expr An expression
+ * \return Length of the result string, in bytes
+ */
+int ast_str_expr(struct ast_str **str, ssize_t maxlen, struct ast_channel *chan, char *expr);
+
 #if defined(__cplusplus) || defined(c_plusplus)
 }
 #endif
diff --git a/include/asterisk/autoconfig.h.in b/include/asterisk/autoconfig.h.in
index 7ba30c2db..57987139f 100644
--- a/include/asterisk/autoconfig.h.in
+++ b/include/asterisk/autoconfig.h.in
@@ -1196,6 +1196,9 @@
 /* Define to the version of this package. */
 #undef PACKAGE_VERSION
 
+/* Define to 1 if the C compiler supports function prototypes. */
+#undef PROTOTYPES
+
 /* Define to necessary symbol if this constant uses a non-standard name on
    your system. */
 #undef PTHREAD_CREATE_JOINABLE
@@ -1212,6 +1215,11 @@
 /* Define to the type of arg 5 for `select'. */
 #undef SELECT_TYPE_ARG5
 
+/* Define to 1 if the `setvbuf' function takes the buffering type as its
+   second argument and the buffer pointer as the third, as on System V before
+   release 3. */
+#undef SETVBUF_REVERSED
+
 /* The size of `int', as computed by sizeof. */
 #undef SIZEOF_INT
 
@@ -1232,30 +1240,20 @@
 /* Define to 1 if your <sys/time.h> declares `struct tm'. */
 #undef TM_IN_SYS_TIME
 
-/* Enable extensions on AIX 3, Interix.  */
+/* Define to 1 if on AIX 3.
+   System headers sometimes define this.
+   We just want to avoid a redefinition error message.  */
 #ifndef _ALL_SOURCE
 # undef _ALL_SOURCE
 #endif
+
+/* Number of bits in a file offset, on hosts where this is settable. */
+#undef _FILE_OFFSET_BITS
+
 /* Enable GNU extensions on systems that have them.  */
 #ifndef _GNU_SOURCE
 # undef _GNU_SOURCE
 #endif
-/* Enable threading extensions on Solaris.  */
-#ifndef _POSIX_PTHREAD_SEMANTICS
-# undef _POSIX_PTHREAD_SEMANTICS
-#endif
-/* Enable extensions on HP NonStop.  */
-#ifndef _TANDEM_SOURCE
-# undef _TANDEM_SOURCE
-#endif
-/* Enable general extensions on Solaris.  */
-#ifndef __EXTENSIONS__
-# undef __EXTENSIONS__
-#endif
-
-
-/* Number of bits in a file offset, on hosts where this is settable. */
-#undef _FILE_OFFSET_BITS
 
 /* Define to 1 to make fseeko visible on some hosts (e.g. glibc 2.2). */
 #undef _LARGEFILE_SOURCE
@@ -1273,6 +1271,20 @@
 /* Define to 1 if you need to in order for `stat' and other things to work. */
 #undef _POSIX_SOURCE
 
+/* Enable extensions on Solaris.  */
+#ifndef __EXTENSIONS__
+# undef __EXTENSIONS__
+#endif
+#ifndef _POSIX_PTHREAD_SEMANTICS
+# undef _POSIX_PTHREAD_SEMANTICS
+#endif
+#ifndef _TANDEM_SOURCE
+# undef _TANDEM_SOURCE
+#endif
+
+/* Define like PROTOTYPES; this can be used by system headers. */
+#undef __PROTOTYPES
+
 /* Define to empty if `const' does not conform to ANSI C. */
 #undef const
 
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