Implement a new element in AstXML for AMI actions documentation.

A new xml element was created to manage the AMI actions documentation,
using AstXML.
To register a manager action using XML documentation it is now possible
using ast_manager_register_xml().
The CLI command 'manager show command' can be used to show the parsed
documentation.

Example manager xml documentation:
<manager name="ami action name" language="en_US">
    <synopsis>
        AMI action synopsis.
    </synopsis>
    <syntax>
        <xi:include xpointer="xpointer(...)" /> <-- for ActionID
        <parameter name="header1" required="true">
	    <para>Description</para>
	</parameter>
	...
    </syntax>
    <description>
        <para>AMI action description</para>
    </description>
    <see-also>
    	...
    </see-also>
</manager>



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

1 files changed, 68 insertions, 2 deletions

diff --git a/main/xmldoc.c b/main/xmldoc.c
index 29d951ac5..3f9b607d2 100644
--- a/main/xmldoc.c
+++ b/main/xmldoc.c
@@ -986,9 +986,66 @@ static char *xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *nam
 	return ret;
 }
 
+/*! \internal
+ *  \brief Generate an AMI action syntax.
+ *  \param fixnode The manager action node pointer.
+ *  \param name The name of the manager action.
+ *  \retval The generated syntax.
+ *  \retval NULL on error.
+ */
+static char *xmldoc_get_syntax_manager(struct ast_xml_node *fixnode, const char *name)
+{
+	struct ast_str *syntax;
+	struct ast_xml_node *node = fixnode;
+	const char *paramtype, *attrname;
+	int required;
+	char *ret;
+
+	syntax = ast_str_create(128);
+	if (!syntax) {
+		return ast_strdup(name);
+	}
+
+	ast_str_append(&syntax, 0, "Action: %s", name);
+
+	for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
+		if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
+			continue;
+		}
+
+		/* Is this parameter required? */
+		required = 0;
+		paramtype = ast_xml_get_attribute(node, "required");
+		if (paramtype) {
+			required = ast_true(paramtype);
+			ast_xml_free_attr(paramtype);
+		}
+
+		attrname = ast_xml_get_attribute(node, "name");
+		if (!attrname) {
+			/* ignore this bogus parameter and continue. */
+			continue;
+		}
+
+		ast_str_append(&syntax, 0, "\n%s%s:%s <value>",
+			(required ? "" : "["),
+			attrname,
+			(required ? "" : "]"));
+
+		ast_xml_free_attr(attrname);
+	}
+
+	/* return a common string. */
+	ret = ast_strdup(ast_str_buffer(syntax));
+	ast_free(syntax);
+
+	return ret;
+}
+
 /*! \brief Types of syntax that we are able to generate. */
 enum syntaxtype {
 	FUNCTION_SYNTAX,
+	MANAGER_SYNTAX,
 	COMMAND_SYNTAX
 };
 
@@ -999,6 +1056,7 @@ struct strsyntaxtype {
 } stxtype[] = {
 	{ "function",		FUNCTION_SYNTAX	},
 	{ "application",	FUNCTION_SYNTAX	},
+	{ "manager",		MANAGER_SYNTAX  },
 	{ "agi",		COMMAND_SYNTAX	}
 };
 
@@ -1036,10 +1094,18 @@ char *ast_xmldoc_build_syntax(const char *type, const char *name)
 	}
 
 	if (node) {
-		if (xmldoc_get_syntax_type(type) == FUNCTION_SYNTAX) {
+		switch (xmldoc_get_syntax_type(type)) {
+		case FUNCTION_SYNTAX:
 			syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
-		} else {
+			break;
+		case COMMAND_SYNTAX:
 			syntax = xmldoc_get_syntax_cmd(node, name, 1);
+			break;
+		case MANAGER_SYNTAX:
+			syntax = xmldoc_get_syntax_manager(node, name);
+			break;
+		default:
+			syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
 		}
 	}
 	return syntax;