Merge changes from team/group/appdocsxml

This commit introduces the first phase of an effort to manage documentation of the
interfaces in Asterisk in an XML format.  Currently, a new format is available for
applications and dialplan functions.  A good number of conversions to the new format
are also included.

For more information, see the following message to asterisk-dev:

http://lists.digium.com/pipermail/asterisk-dev/2008-October/034968.html


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

9 files changed, 220 insertions, 6 deletions

diff --git a/include/asterisk/_private.h b/include/asterisk/_private.h
index fe9aa2c04..be4542d7a 100644
--- a/include/asterisk/_private.h
+++ b/include/asterisk/_private.h
@@ -56,4 +56,10 @@ int ast_timing_init(void);		/*!< Provided by timing.c */
  */
 int ast_module_reload(const char *name);
 
+/*! \brief Load XML documentation. Provided by pbx.c 
+ *  \retval 1 on error.
+ *  \retval 0 on success. 
+ */
+int ast_load_documentation(void);
+
 #endif /* _ASTERISK__PRIVATE_H */
diff --git a/include/asterisk/autoconfig.h.in b/include/asterisk/autoconfig.h.in
index 3417c738e..79134bd3c 100644
--- a/include/asterisk/autoconfig.h.in
+++ b/include/asterisk/autoconfig.h.in
@@ -410,6 +410,9 @@
 /* Define to 1 if you have the <libintl.h> header file. */
 #undef HAVE_LIBINTL_H
 
+/* Define if your system has the LIBXML2 libraries. */
+#undef HAVE_LIBXML2
+
 /* Define to 1 if you have the <limits.h> header file. */
 #undef HAVE_LIMITS_H
 
diff --git a/include/asterisk/compat.h b/include/asterisk/compat.h
index e481fbec4..0b431f5e0 100644
--- a/include/asterisk/compat.h
+++ b/include/asterisk/compat.h
@@ -182,4 +182,15 @@ typedef unsigned int	uint;
 typedef unsigned long long uint64_t;
 #endif
 
+/* glob compat stuff */ 
+#if defined(__Darwin__) || defined(__CYGWIN__)
+#define GLOB_ABORTED GLOB_ABEND
+#endif
+#include <glob.h>
+#ifdef SOLARIS
+#define MY_GLOB_FLAGS   GLOB_NOCHECK
+#else
+#define MY_GLOB_FLAGS   (GLOB_NOMAGIC|GLOB_BRACE)
+#endif
+
 #endif
diff --git a/include/asterisk/extconf.h b/include/asterisk/extconf.h
index 086271ce5..7527c579f 100644
--- a/include/asterisk/extconf.h
+++ b/include/asterisk/extconf.h
@@ -76,8 +76,14 @@ struct ast_config {
 /*! \brief A registered application */
 struct ast_app {
 	int (*execute)(struct ast_channel *chan, void *data);
-	const char *synopsis;			/*!< Synopsis text for 'show applications' */
-	const char *description;		/*!< Description (help text) for 'show application &lt;name&gt;' */
+	AST_DECLARE_STRING_FIELDS(
+		AST_STRING_FIELD(synopsis);     /*!< Synopsis text for 'show applications' */
+		AST_STRING_FIELD(description);  /*!< Description (help text) for 'show application &lt;name&gt;' */
+		AST_STRING_FIELD(syntax);       /*!< Syntax text for 'core show applications' */
+		AST_STRING_FIELD(arguments);    /*!< Arguments description */
+		AST_STRING_FIELD(seealso);      /*!< See also */
+	);
+	enum ast_xmldoc_src docsrc;		/*!< Where the documentation come from. */
 	AST_RWLIST_ENTRY(ast_app) list;		/*!< Next app in list */
 	void *module;			/*!< Module this app belongs to */
 	char name[0];				/*!< Name of the application */
diff --git a/include/asterisk/module.h b/include/asterisk/module.h
index f466395c0..640c5af32 100644
--- a/include/asterisk/module.h
+++ b/include/asterisk/module.h
@@ -380,6 +380,23 @@ static void __restore_globals(void)
  */
 #define ast_register_application(app, execute, synopsis, description) ast_register_application2(app, execute, synopsis, description, ast_module_info->self)
 
+/*! 
+ * \brief Register an application using XML documentation.
+ *
+ * \param app Short name of the application
+ * \param execute a function callback to execute the application. It should return
+ *                non-zero if the channel needs to be hung up.
+ * 
+ * This registers an application with Asterisk's internal application list. 
+ * \note The individual applications themselves are responsible for registering and unregistering
+ *       and unregistering their own CLI commands.
+ * 
+ * \retval 0 success 
+ * \retval -1 failure.
+ */
+#define ast_register_application_xml(app, execute) ast_register_application(app, execute, NULL, NULL)
+
+
 /*!
  * \brief Register an application.
  *
diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h
index d2d95acca..3348bb8d7 100644
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -26,6 +26,7 @@
 #include "asterisk/sched.h"
 #include "asterisk/chanvars.h"
 #include "asterisk/hashtab.h"
+#include "asterisk/stringfields.h"
 
 #if defined(__cplusplus) || defined(c_plusplus)
 extern "C" {
@@ -73,12 +74,23 @@ struct ast_sw;
 /*! \brief Typedef for devicestate and hint callbacks */
 typedef int (*ast_state_cb_type)(char *context, char* id, enum ast_extension_states state, void *data);
 
+/*! \brief From where the documentation come from */
+enum ast_doc_src {
+	AST_XML_DOC,            /*!< From XML documentation */
+	AST_STATIC_DOC          /*!< From application/function registration */
+};
+
 /*! \brief Data structure associated with a custom dialplan function */
 struct ast_custom_function {
-	const char *name;		/*!< Name */
-	const char *synopsis;		/*!< Short description for "show functions" */
-	const char *desc;		/*!< Help text that explains it all */
-	const char *syntax;		/*!< Syntax description */
+	const char *name;			/*!< Name */
+	AST_DECLARE_STRING_FIELDS(
+		AST_STRING_FIELD(synopsis);     /*!< Synopsis text for 'show functions' */
+		AST_STRING_FIELD(desc);		/*!< Description (help text) for 'show functions &lt;name&gt;' */
+		AST_STRING_FIELD(syntax);       /*!< Syntax text for 'core show functions' */
+		AST_STRING_FIELD(arguments);    /*!< Arguments description */
+		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 */
 	struct ast_module *mod;         /*!< Module this custom function belongs to */
diff --git a/include/asterisk/strings.h b/include/asterisk/strings.h
index 19315b02f..16a60c38a 100644
--- a/include/asterisk/strings.h
+++ b/include/asterisk/strings.h
@@ -387,6 +387,21 @@ void ast_str_reset(struct ast_str *buf),
 }
 )
 
+/*! \brief Trims trailing whitespace characters from an ast_str string.
+ *  \param buf A pointer to the ast_str string.
+ */
+AST_INLINE_API(
+void ast_str_trim_blanks(struct ast_str *buf),
+{
+	if (!buf) {
+		return;
+	}
+	while (buf->used && buf->str[buf->used - 1] < 33) {
+		buf->str[--(buf->used)] = '\0';
+	}
+}
+)
+
 /*
  * AST_INLINE_API() is a macro that takes a block of code as an argument.
  * Using preprocessor #directives in the argument is not supported by all
diff --git a/include/asterisk/term.h b/include/asterisk/term.h
index 3277f0042..8c6cab43e 100644
--- a/include/asterisk/term.h
+++ b/include/asterisk/term.h
@@ -64,6 +64,28 @@ extern "C" {
 
 char *term_color(char *outbuf, const char *inbuf, int fgcolor, int bgcolor, int maxout);
 
+/*!
+ * \brief Append a color sequence to an ast_str
+ *
+ * \param str The string to append to
+ * \param fgcolor foreground color
+ * \param bgcolor background color
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int ast_term_color_code(struct ast_str **str, int fgcolor, int bgcolor);
+
+/*!
+ * \brief Write a color sequence to a string
+ *
+ * \param outbuf the location to write to
+ * \param fgcolor foreground color
+ * \param bgcolor background color
+ * \param maxout maximum number of characters to write
+ *
+ * \return outbuf
+ */
 char *term_color_code(char *outbuf, int fgcolor, int bgcolor, int maxout);
 
 char *term_strip(char *outbuf, char *inbuf, int maxout);
diff --git a/include/asterisk/xml.h b/include/asterisk/xml.h
new file mode 100644
index 000000000..8ed9ffdfd
--- /dev/null
+++ b/include/asterisk/xml.h
@@ -0,0 +1,122 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2008, Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+#ifndef _ASTERISK_XML_H
+#define _ASTERISK_XML_H
+
+/*! \file 
+ *  \brief Asterisk XML abstraction layer
+ */
+
+struct ast_xml_node;
+struct ast_xml_doc;
+
+/*! \brief Initialize the XML library implementation. 
+ *         This function is used to setup everything needed
+ *         to start working with the xml implementation.
+ *  \retval 0 On success.
+ *  \retval 1 On error.
+ */
+int ast_xml_init(void);
+
+/*! \brief Cleanup library allocated global data. 
+ *  \retval 0 On success.
+ *  \retval 1 On error.
+ */
+int ast_xml_finish(void);
+
+/*! \brief Open an XML document.
+ *  \param filename Document path.
+ *  \retval NULL on error.
+ *  \retval The ast_xml_doc reference to the open document.
+ */
+struct ast_xml_doc *ast_xml_open(char *filename);
+
+/*! \brief Close an already open document and free the used
+ *        structure.
+ *  \retval doc The document reference.
+ */
+void ast_xml_close(struct ast_xml_doc *doc);
+
+/*! \brief Get the document root node.
+ *  \param doc Document reference
+ *  \retval NULL on error
+ *  \retval The root node on success.
+ */
+struct ast_xml_node *ast_xml_get_root(struct ast_xml_doc *doc);
+
+/*! \brief Free node 
+ *  \param node Node to be released.
+ */
+void ast_xml_free_node(struct ast_xml_node *node);
+
+/*! \brief Free an attribute returned by ast_xml_get_attribute()
+ *  \param data pointer to be freed.
+ */
+void ast_xml_free_attr(const char *attribute);
+
+/*! \brief Free a content element that was returned by ast_xml_get_text()
+ *  \param text text to be freed.
+ */
+void ast_xml_free_text(const char *text);
+
+/*! \brief Get a node attribute by name
+ *  \param node Node where to search the attribute.
+ *  \param attrname Attribute name.
+ *  \retval NULL on error
+ *  \retval The attribute value on success.
+ */
+const char *ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname);
+
+/*! \brief Find a node element by name.
+ *  \param node This is the node starting point.
+ *  \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
+ *  \retval The node on success.
+ */
+struct ast_xml_node *ast_xml_find_element(struct ast_xml_node *root_node, const char *name, const char *attrname, const char *attrvalue);
+
+/*! \brief Get an element content string.
+ *  \param node Node from where to get the string.
+ *  \retval NULL on error.
+ *  \retval The text content of node.
+ */
+const char *ast_xml_get_text(struct ast_xml_node *node);
+
+/*! \brief Get the name of a node. */
+const char *ast_xml_node_get_name(struct ast_xml_node *node);
+
+/*! \brief Get the node's children. */
+struct ast_xml_node *ast_xml_node_get_children(struct ast_xml_node *node);
+
+/*! \brief Get the next node in the same level. */
+struct ast_xml_node *ast_xml_node_get_next(struct ast_xml_node *node);
+
+/*! \brief Get the previous node in the same leve. */
+struct ast_xml_node *ast_xml_node_get_prev(struct ast_xml_node *node);
+
+/*! \brief Get the parent of a specified node. */
+struct ast_xml_node *ast_xml_node_get_parent(struct ast_xml_node *node);
+
+/* Features using ast_xml_ */
+#ifdef HAVE_LIBXML2
+#define AST_XML_DOCS
+#endif
+
+#endif /* _ASTERISK_XML_H */
+