Geolocation: Base Asterisk Prereqs

* Added ast_variable_list_from_quoted_string()
  Parse a quoted string into an ast_variable list.

* Added ast_str_substitute_variables_full2()
  Perform variable/function/expression substitution on an ast_str.

* Added ast_strsep_quoted()
  Like ast_strsep except you can specify a specific quote character.
  Also added unit test.

* Added ast_xml_find_child_element()
  Find a direct child element by name.

* Added ast_xml_doc_dump_memory()
  Dump the specified document to a buffer

* ast_datastore_free() now checks for a NULL datastore
  before attempting to destroy it.

Change-Id: I5dcefed2f5f93a109e8b489e18d80d42e45244ec

include/asterisk/config.h

@@ -1023,6 +1023,26 @@ struct ast_str *ast_variable_list_join(const struct ast_variable *head, const ch
 struct ast_variable *ast_variable_list_from_string(const char *input, const char *item_separator,
 	const char *name_value_separator);
 
+/*!
+ * \brief Parse a string into an ast_variable list.  The reverse of ast_variable_list_join
+ *
+ * \param input                The name-value pair string to parse.
+ * \param item_separator       The string used to separate the list items.
+ *                             Only the first character in the string will be used.
+ *                             If NULL, "," will be used.
+ * \param name_value_separator The string used to separate each item's name and value.
+ *                             Only the first character in the string will be used.
+ *                             If NULL, "=" will be used.
+ * \param quote_str            The string used to quote values.
+ *                             Only the first character in the string will be used.
+ *                             If NULL, '"' will be used.
+ *
+ * \retval A pointer to a list of ast_variables.
+ * \retval NULL if there was an error or no variables could be parsed.
+ */
+struct ast_variable *ast_variable_list_from_quoted_string(const char *input, const char *item_separator,
+	const char *name_value_separator, const char *quote_str);
+
 /*!
  * \brief Update variable value within a config
  *

include/asterisk/pbx.h

@@ -1472,6 +1472,28 @@ void ast_str_substitute_variables_varshead(struct ast_str **buf, ssize_t maxlen,
  * \param used Number of bytes read from the template.  (May be NULL)
  */
 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);
+
+/*!
+ * \brief Perform variable/function/expression substitution on an ast_str
+ *
+ * \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        A channel from which to extract values, and to pass
+ *                 to any dialplan functions.
+ * \param headp    A channel variables list to also search for variables.
+ * \param templ    Variable template to expand.
+ * \param used     Number of bytes read from the template.  (May be NULL)
+ * \param use_both Normally, if a channel is specified, headp is ignored.
+ *                 If this parameter is set to 1 and both a channel and headp
+ *                 are specified, the channel will be searched for variables
+ *                 first and any not found will be searched for in headp.
+ */
+void ast_str_substitute_variables_full2(struct ast_str **buf, ssize_t maxlen,
+	struct ast_channel *c, struct varshead *headp, const char *templ,
+	size_t *used, int use_both);
+
 /*! @} */
 
 int ast_extension_patmatch(const char *pattern, const char *data);

include/asterisk/strings.h

@@ -308,6 +308,24 @@ enum ast_strsep_flags {
  */
 char *ast_strsep(char **s, const char sep, uint32_t flags);
 
+/*!
+ * \brief Like ast_strsep() except you can specify a specific quote character
+ *
+  \param s Pointer to address of the string to be processed.
+  Will be modified and can't be constant.
+  \param sep A single character delimiter.
+  \param quote The quote character
+  \param flags Controls post-processing of the result.
+  AST_STRSEP_TRIM trims all leading and trailing whitespace from the result.
+  AST_STRSEP_STRIP does a trim then strips the outermost quotes.  You may want
+  to trim again after the strip.  Just OR both the TRIM and STRIP flags.
+  AST_STRSEP_UNESCAPE unescapes '\' sequences.
+  AST_STRSEP_ALL does all of the above processing.
+  \return The next token or NULL if done or if there are more than 8 levels of
+  nested quotes.
+ */
+char *ast_strsep_quoted(char **s, const char sep, const char quote, uint32_t flags);
+
 /*!
   \brief Strip backslash for "escaped" semicolons,
 	the string to be stripped (will be modified).

include/asterisk/xml.h

@@ -188,6 +188,18 @@ int ast_xml_set_attribute(struct ast_xml_node *node, const char *name, const cha
 struct ast_xml_node *ast_xml_find_element(struct ast_xml_node *root_node, const char *name, const char *attrname, const char *attrvalue);
 struct ast_xml_ns *ast_xml_find_namespace(struct ast_xml_doc *doc, struct ast_xml_node *node, const char *ns_name);
 
+/*!
+ * \brief Find a direct child element by name.
+ * \param parent_node This is the parent node to search.
+ * \param name Node name to find.
+ * \param attrname attribute name to match (if NULL it won't be matched).
+ * \param attrvalue attribute value to match (if NULL it won't be matched).
+ * \retval NULL if not found.
+ * \return The node on success.
+ */
+#define ast_xml_find_child_element(_parent_node, _name, _attrname, _attrvalue) \
+    ast_xml_find_element(ast_xml_node_get_children(_parent_node), _name, _attrname, _attrvalue)
+
 /*!
  * \brief Get the prefix of a namespace.
  * \param ns The namespace
@@ -248,6 +260,17 @@ struct ast_xml_node *ast_xml_node_get_parent(struct ast_xml_node *node);
  * \brief Dump the specified document to a file. */
 int ast_xml_doc_dump_file(FILE *output, struct ast_xml_doc *doc);
 
+/*!
+ * \brief Dump the specified document to a buffer
+ *
+ * \param doc The XML doc to dump
+ * \param buffer A pointer to a char * to receive the address of the results
+ * \param length A pointer to an int to receive the length of the results
+ *
+ * \note The result buffer must be freed with ast_xml_free_text().
+ */
+void ast_xml_doc_dump_memory(struct ast_xml_doc *doc, char **buffer, int *length);
+
 /*!
  * \brief Free the XPath results
  * \param results The XPath results object to dispose of