[asterisk-commits] mjordan: branch mjordan/tech-doc r370065 - in /team/mjordan/tech-doc: ./ chan...

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Fri Jul 13 17:05:27 CDT 2012


Author: mjordan
Date: Fri Jul 13 17:05:22 2012
New Revision: 370065

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=370065
Log:
Branch out tech specific documentation

This still needs a few more tweaks and some general clean up.  Off to a
branch with you to get done this weekend!

Added:
    team/mjordan/tech-doc/
      - copied from r370048, trunk/
Modified:
    team/mjordan/tech-doc/channels/chan_sip.c
    team/mjordan/tech-doc/doc/appdocsxml.dtd
    team/mjordan/tech-doc/main/message.c
    team/mjordan/tech-doc/main/xml.c
    team/mjordan/tech-doc/main/xmldoc.c
    team/mjordan/tech-doc/res/res_xmpp.c

Modified: team/mjordan/tech-doc/channels/chan_sip.c
URL: http://svnview.digium.com/svn/asterisk/team/mjordan/tech-doc/channels/chan_sip.c?view=diff&rev=370065&r1=370048&r2=370065
==============================================================================
--- team/mjordan/tech-doc/channels/chan_sip.c (original)
+++ team/mjordan/tech-doc/channels/chan_sip.c Fri Jul 13 17:05:22 2012
@@ -572,6 +572,14 @@
 			via multiple <literal>Variable: name=value</literal> sequences.</para>
 		</description>
 	</manager>
+	<info name="SIPMessageFromInfo" language="en_US" tech="SIP">
+		<para>The <literal>from</literal> parameter can be a configured peer name
+		or in the form of "display-name" &lt;URI&gt;.</para>
+	</info>
+	<info name="SIPMessageToInfo" language="en_US" tech="SIP">
+		<para>Specifying a prefix of <literal>xmpp:</literal> will send the
+		message as a SIP MESSAGE request.</para>
+	</info>
  ***/
 
 static int min_expiry = DEFAULT_MIN_EXPIRY;        /*!< Minimum accepted registration time */

Modified: team/mjordan/tech-doc/doc/appdocsxml.dtd
URL: http://svnview.digium.com/svn/asterisk/team/mjordan/tech-doc/doc/appdocsxml.dtd?view=diff&rev=370065&r1=370048&r2=370065
==============================================================================
--- team/mjordan/tech-doc/doc/appdocsxml.dtd (original)
+++ team/mjordan/tech-doc/doc/appdocsxml.dtd Fri Jul 13 17:05:22 2012
@@ -1,4 +1,4 @@
-  <!ELEMENT docs (application|function|agi|manager|managerEvent)*>
+  <!ELEMENT docs (application|function|agi|manager|managerEvent|info)*>
   <!ATTLIST docs xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude">
 
   <!ELEMENT xi:include (xi:fallback?) >
@@ -36,6 +36,11 @@
   <!ELEMENT managerEventInstance (synopsis?,syntax?,description?,see-also?)*>
   <!ATTLIST managerEventInstance class CDATA #REQUIRED>
 
+  <!ELEMENT info (para|note|warning|variablelist|enumlist|xi:include)*>
+  <!ATTLIST info name CDATA #REQUIRED>
+  <!ATTLIST info language CDATA #REQUIRED>
+  <!ATTLIST info tech CDATA #REQUIRED>
+
   <!ELEMENT see-also (ref|xi:include)*>
 
   <!ELEMENT ref (#PCDATA)>
@@ -46,9 +51,9 @@
   <!ELEMENT syntax (parameter|xi:include)*>
   <!ATTLIST syntax argsep CDATA ",">
 
-  <!ELEMENT description (para|note|warning|variablelist|enumlist|xi:include)*>
+  <!ELEMENT description (para|note|warning|variablelist|enumlist|info|xi:include)*>
 
-  <!ELEMENT parameter (optionlist|enumlist|argument|para|note|warning|parameter|xi:include)*>
+  <!ELEMENT parameter (optionlist|enumlist|argument|para|note|warning|parameter|info|xi:include)*>
   <!ATTLIST parameter name CDATA "">
   <!ATTLIST parameter required (yes|no|true|false) "false">
   <!ATTLIST parameter multiple (yes|no|true|false) "false">
@@ -68,7 +73,7 @@
   <!ELEMENT enum (para|note|warning|parameter|enumlist|xi:include)*>
   <!ATTLIST enum name CDATA "">
 
-  <!ELEMENT argument (para|note|warning|variablelist|argument|xi:include)*>
+  <!ELEMENT argument (para|note|warning|variablelist|argument|info|xi:include)*>
   <!ATTLIST argument name CDATA #REQUIRED>
   <!ATTLIST argument multiple (yes|no|true|false) "false">
   <!ATTLIST argument required (yes|no|true|false) "false">
@@ -87,7 +92,7 @@
   <!ELEMENT warning (para+|xi:include*)>
 
   <!ELEMENT variablelist (variable+|xi:include*)>
-  <!ELEMENT variable (#PCDATA|value|para|xi:include)*>
+  <!ELEMENT variable (#PCDATA|value|para|info|xi:include)*>
   <!ATTLIST variable name CDATA "">
 
   <!ELEMENT value (#PCDATA)>

Modified: team/mjordan/tech-doc/main/message.c
URL: http://svnview.digium.com/svn/asterisk/team/mjordan/tech-doc/main/message.c?view=diff&rev=370065&r1=370048&r2=370065
==============================================================================
--- team/mjordan/tech-doc/main/message.c (original)
+++ team/mjordan/tech-doc/main/message.c Fri Jul 13 17:05:22 2012
@@ -126,16 +126,14 @@
 			<parameter name="from" required="false">
 				<para>A From URI for the message if needed for the
 				message technology being used to send this message.</para>
-				<note>
-					<para>For SIP the from parameter can be a configured peer name
-					or in the form of "display-name" &lt;URI&gt;.</para>
-				</note>
+				<xi:include xpointer="xpointer(/docs/info[@name='SIPMessageFromInfo'])" />
 			</parameter>
 		</syntax>
 		<description>
 			<para>Send a text message.  The body of the message that will be
 			sent is what is currently set to <literal>MESSAGE(body)</literal>.</para>
-
+			<para>The technology chosen for sending the message is determined
+			based on a prefix to the <literal>to</literal> parameter.</para>
 			<para>This application sets the following channel variables:</para>
 			<variablelist>
 				<variable name="MESSAGE_SEND_STATUS">
@@ -168,10 +166,6 @@
 			<parameter name="From">
 				<para>A From URI for the message if needed for the
 				message technology being used to send this message.</para>
-				<note>
-					<para>For SIP the from parameter can be a configured peer name
-					or in the form of "display-name" &lt;URI&gt;.</para>
-				</note>
 			</parameter>
 			<parameter name="Body">
 				<para>The message body text.  This must not contain any newlines as that

Modified: team/mjordan/tech-doc/main/xml.c
URL: http://svnview.digium.com/svn/asterisk/team/mjordan/tech-doc/main/xml.c?view=diff&rev=370065&r1=370048&r2=370065
==============================================================================
--- team/mjordan/tech-doc/main/xml.c (original)
+++ team/mjordan/tech-doc/main/xml.c Fri Jul 13 17:05:22 2012
@@ -55,6 +55,7 @@
 struct ast_xml_doc *ast_xml_open(char *filename)
 {
 	xmlDoc *doc;
+	int res;
 
 	if (!filename) {
 		return NULL;
@@ -63,7 +64,8 @@
 	doc = xmlReadFile(filename, NULL, XML_PARSE_RECOVER);
 	if (doc) {
 		/* process xinclude elements. */
-		if (xmlXIncludeProcess(doc) < 0) {
+		if ((res = xmlXIncludeProcess(doc)) < 0) {
+			ast_log(AST_LOG_NOTICE, "Include returned %d\n", res);
 			xmlFreeDoc(doc);
 			return NULL;
 		}

Modified: team/mjordan/tech-doc/main/xmldoc.c
URL: http://svnview.digium.com/svn/asterisk/team/mjordan/tech-doc/main/xmldoc.c?view=diff&rev=370065&r1=370048&r2=370065
==============================================================================
--- team/mjordan/tech-doc/main/xmldoc.c (original)
+++ team/mjordan/tech-doc/main/xmldoc.c Fri Jul 13 17:05:22 2012
@@ -65,6 +65,7 @@
 
 static char *xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *name, int printname);
 static int xmldoc_parse_enumlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer);
+static int xmldoc_parse_info(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer);
 
 /*!
  * \brief Container of documentation trees
@@ -1287,7 +1288,8 @@
 		/* parse <para> elements inside special tags. */
 		for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
 			/* first <para> just print it without tabs at the begining. */
-			if (xmldoc_parse_para(node, (!count ? "" : tabs), posttabs, buffer) == 2) {
+			if ((xmldoc_parse_para(node, (!count ? "" : tabs), posttabs, buffer) == 2)
+				|| (xmldoc_parse_info(node, (!count ? "": tabs), posttabs, buffer) == 2)) {
 				ret = 2;
 			}
 		}
@@ -1298,6 +1300,56 @@
 
 		break;
 	}
+
+	return ret;
+}
+
+/*! \internal
+ *  \brief Parse an 'info' tag inside an element.
+ *  \param node A pointer to the 'info' xml node.
+ *  \param tabs A string to be appended at the beginning of each line being printed
+ *              inside 'buffer'
+  *  \param posttabs Add this string after the content of the <para> element, if one exists
+ *  \param String buffer to put values found inide the info element.
+ *  \ret 2 if the information contained a para element, and it returned a value of 2
+ *  \ret 1 if information was put into the buffer
+ *  \ret 0 if no information was put into the buffer or error
+ */
+static int xmldoc_parse_info(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
+{
+	const char *tech;
+	char *internaltabs;
+	int internal_ret;
+	int ret = 0;
+
+	if (strcasecmp(ast_xml_node_get_name(node), "info")) {
+		return ret;
+	}
+
+	ast_asprintf(&internaltabs, "%s    ", tabs);
+	if (!internaltabs) {
+		return ret;
+	}
+
+	tech = ast_xml_get_attribute(node, "tech");
+	if (tech) {
+		ast_str_append(buffer, 0, "%s<note>Technology: %s</note>\n", internaltabs, tech);
+		ast_xml_free_attr(tech);
+	}
+
+	ret = 1;
+
+	for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
+		if (!strcasecmp(ast_xml_node_get_name(node), "enumlist")) {
+			xmldoc_parse_enumlist(node, internaltabs, buffer);
+		} else if ((internal_ret = xmldoc_parse_para(node, internaltabs, posttabs, buffer))
+			|| (internal_ret = xmldoc_parse_specialtags(node, internaltabs, posttabs, buffer))) {
+			if (internal_ret > ret) {
+				ret = internal_ret;
+			}
+		}
+	}
+	ast_free(internaltabs);
 
 	return ret;
 }
@@ -1327,7 +1379,7 @@
 	if (!argname) {
 		return 0;
 	}
-	if (xmldoc_has_inside(node, "para") || xmldoc_has_specialtags(node)) {
+	if (xmldoc_has_inside(node, "para") || xmldoc_has_inside(node, "info") || xmldoc_has_specialtags(node)) {
 		ast_str_append(buffer, 0, "%s%s%s", tabs, argname, (insideparameter ? "\n" : ""));
 		ast_xml_free_attr(argname);
 	} else {
@@ -1336,10 +1388,9 @@
 	}
 
 	for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
-		if (xmldoc_parse_para(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
-			count++;
-			ret = 1;
-		} else if (xmldoc_parse_specialtags(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
+		if ((xmldoc_parse_para(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2)
+			|| (xmldoc_parse_info(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2)
+			|| (xmldoc_parse_specialtags(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2)) {
 			count++;
 			ret = 1;
 		}
@@ -1368,10 +1419,9 @@
 	int ret = 0, printedpara=0;
 
 	for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
-		if (xmldoc_parse_para(tmp, (ret ? tabs : ""), "\n", buffer)) {
-			printedpara = 1;
-			continue;
-		} else if (xmldoc_parse_specialtags(tmp, (ret ? tabs : ""), "\n", buffer)) {
+		if ((xmldoc_parse_para(tmp, (ret ? tabs : ""), "\n", buffer))
+			|| (xmldoc_parse_info(tmp, (ret ? tabs : ""), "\n", buffer))
+			|| (xmldoc_parse_specialtags(tmp, (ret ? tabs : ""), "\n", buffer))) {
 			printedpara = 1;
 			continue;
 		}
@@ -1442,10 +1492,9 @@
 	}
 	for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
 		/* We can have a <para> element inside the variable list */
-		if ((xmldoc_parse_para(tmp, (ret ? tabs : ""), "\n", buffer))) {
-			ret = 1;
-			continue;
-		} else if ((xmldoc_parse_specialtags(tmp, (ret ? tabs : ""), "\n", buffer))) {
+		if (xmldoc_parse_para(tmp, (ret ? tabs : ""), "\n", buffer)
+			|| xmldoc_parse_info(tmp, (ret ? tabs : ""), "\n", buffer)
+			|| xmldoc_parse_specialtags(tmp, (ret ? tabs : ""), "\n", buffer)) {
 			ret = 1;
 			continue;
 		}
@@ -1579,9 +1628,9 @@
 	ast_asprintf(&optiontabs, "%s    ", tabs);
 
 	for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
-		if ((xmldoc_parse_para(node, (ret ? tabs : " - "), "\n", buffer))) {
-			ret = 1;
-		} else if ((xmldoc_parse_specialtags(node, (ret ? tabs : " - "), "\n", buffer))) {
+		if (xmldoc_parse_para(node, (ret ? tabs : " - "), "\n", buffer)
+			|| xmldoc_parse_info(node, (ret ? tabs : " - "), "\n", buffer)
+			|| xmldoc_parse_specialtags(node, (ret ? tabs : " - "), "\n", buffer)) {
 			ret = 1;
 		}
 
@@ -1659,9 +1708,9 @@
 			continue;
 		}
 
-		if (xmldoc_parse_para(node, (ret ? tabs :  ""), "\n", buffer)) {
-			ret = 1;
-		} else if (xmldoc_parse_specialtags(node, (ret ? tabs :  ""), "\n", buffer)) {
+		if (xmldoc_parse_para(node, (ret ? tabs :  ""), "\n", buffer)
+			|| xmldoc_parse_info(node, (ret ? tabs : ""), "\n", buffer)
+			|| xmldoc_parse_specialtags(node, (ret ? tabs :  ""), "\n", buffer)) {
 			ret = 1;
 		}
 
@@ -1779,6 +1828,18 @@
 				continue;
 			}
 			continue;
+		} else if (!strcasecmp(ast_xml_node_get_name(node), "info")) {
+			if (!printed) {
+				ast_str_append(buffer, 0, "%s\n", paramname);
+				ast_xml_free_attr(paramname);
+				printed = 1;
+			}
+			if (xmldoc_parse_info(node, internaltabs, "\n", buffer)) {
+				/* If anything ever goes in below this condition before the continue below,
+				 * we should probably continue immediately. */
+				continue;
+			}
+			continue;
 		} else if ((xmldoc_parse_specialtags(node, internaltabs, "\n", buffer))) {
 			continue;
 		}
@@ -1881,9 +1942,9 @@
 	} else {
 		for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
 			/* if found, parse a <para> element. */
-			if (xmldoc_parse_para(tmp, "", "\n", &ret)) {
-				continue;
-			} else if (xmldoc_parse_specialtags(tmp, "", "\n", &ret)) {
+			if (xmldoc_parse_para(tmp, "", "\n", &ret)
+				|| xmldoc_parse_specialtags(tmp, "", "\n", &ret)
+				|| xmldoc_parse_info(tmp, "", "\n", &ret)) {
 				continue;
 			}
 			/* if found, parse a <variablelist> element. */

Modified: team/mjordan/tech-doc/res/res_xmpp.c
URL: http://svnview.digium.com/svn/asterisk/team/mjordan/tech-doc/res/res_xmpp.c?view=diff&rev=370065&r1=370048&r2=370065
==============================================================================
--- team/mjordan/tech-doc/res/res_xmpp.c (original)
+++ team/mjordan/tech-doc/res/res_xmpp.c Fri Jul 13 17:05:22 2012
@@ -270,6 +270,10 @@
 			<para>Sends a message to a Jabber Client.</para>
 		</description>
 	</manager>
+	<info name="XMPPMessageToInfo" language="en_US" tech="XMPP">
+		<para>Specifying a prefix of <literal>xmpp:</literal> will send the
+		message as an XMPP chat message.</para>
+	</info>
 ***/
 
 /*! \brief Supported general configuration flags */




More information about the asterisk-commits mailing list