[svn-commits] mjordan: trunk r370278 - in /trunk: channels/ doc/ main/ res/
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Thu Jul 19 17:17:17 CDT 2012
Author: mjordan
Date: Thu Jul 19 17:17:13 2012
New Revision: 370278
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=370278
Log:
Add the ability to specify technology specific documentation
A number of applications/AMI commands in Asterisk have specific behavioral
differences depending on the resource or channel technology those
applications are executed on. For example, the MessageSend application/
command is technology agnostic, but how the channel drivers that support
that functionality behave is dependant on the protocols and channel
driver implementation. Prior to this patch, those details were either
documented in the application/command documentation itself, or were left
undocumented.
This patch adds a new element to the documentation schema, <info/>. An info
node is essentially a piece of technology specific reference information that
can be included by any top level XML documentation node. For example, the
MessageSend application can now include XMPP/SIP specific information, where
that technology specific information can be defined in chan_motif/res_xmpp/
chan_sip. Likewise, that information can also be included in the MessageSend
AMI command.
Review: https://reviewboard.asterisk.org/r/2049
Modified:
trunk/channels/chan_sip.c
trunk/doc/appdocsxml.dtd
trunk/main/message.c
trunk/main/xmldoc.c
trunk/res/res_xmpp.c
Modified: trunk/channels/chan_sip.c
URL: http://svnview.digium.com/svn/asterisk/trunk/channels/chan_sip.c?view=diff&rev=370278&r1=370277&r2=370278
==============================================================================
--- trunk/channels/chan_sip.c (original)
+++ trunk/channels/chan_sip.c Thu Jul 19 17:17:13 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" <URI>.</para>
+ </info>
+ <info name="SIPMessageToInfo" language="en_US" tech="SIP">
+ <para>Specifying a prefix of <literal>sip:</literal> will send the
+ message as a SIP MESSAGE request.</para>
+ </info>
***/
static int min_expiry = DEFAULT_MIN_EXPIRY; /*!< Minimum accepted registration time */
Modified: trunk/doc/appdocsxml.dtd
URL: http://svnview.digium.com/svn/asterisk/trunk/doc/appdocsxml.dtd?view=diff&rev=370278&r1=370277&r2=370278
==============================================================================
--- trunk/doc/appdocsxml.dtd (original)
+++ trunk/doc/appdocsxml.dtd Thu Jul 19 17:17:13 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|info|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">
@@ -58,17 +63,17 @@
<!ATTLIST parameter argsep CDATA ",">
<!ELEMENT optionlist (option+)>
- <!ELEMENT option (argument|para|note|warning|variablelist|enumlist|xi:include)*>
+ <!ELEMENT option (argument|para|note|warning|variablelist|enumlist|info|xi:include)*>
<!ATTLIST option name CDATA #REQUIRED>
<!ATTLIST option argsep CDATA ",">
<!ATTLIST option implies CDATA "">
<!ATTLIST option hasparams CDATA "">
<!ELEMENT enumlist (enum+)>
- <!ELEMENT enum (para|note|warning|parameter|enumlist|xi:include)*>
+ <!ELEMENT enum (para|note|warning|parameter|enumlist|info|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: trunk/main/message.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/message.c?view=diff&rev=370278&r1=370277&r2=370278
==============================================================================
--- trunk/main/message.c (original)
+++ trunk/main/message.c Thu Jul 19 17:17:13 2012
@@ -122,20 +122,20 @@
<syntax>
<parameter name="to" required="true">
<para>A To URI for the message.</para>
+ <xi:include xpointer="xpointer(/docs/info[@name='SIPMessageToInfo'])" />
+ <xi:include xpointer="xpointer(/docs/info[@name='XMPPMessageToInfo'])" />
</parameter>
<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" <URI>.</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>
-
+ sent is what is currently set to <literal>MESSAGE(body)</literal>.
+ 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">
@@ -164,14 +164,13 @@
<xi:include xpointer="xpointer(/docs/manager[@name='Login']/syntax/parameter[@name='ActionID'])" />
<parameter name="To" required="true">
<para>The URI the message is to be sent to.</para>
+ <xi:include xpointer="xpointer(/docs/info[@name='SIPMessageToInfo'])" />
+ <xi:include xpointer="xpointer(/docs/info[@name='XMPPMessageToInfo'])" />
</parameter>
<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" <URI>.</para>
- </note>
+ <xi:include xpointer="xpointer(/docs/info[@name='SIPMessageFromInfo'])" />
</parameter>
<parameter name="Body">
<para>The message body text. This must not contain any newlines as that
Modified: trunk/main/xmldoc.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/xmldoc.c?view=diff&rev=370278&r1=370277&r2=370278
==============================================================================
--- trunk/main/xmldoc.c (original)
+++ trunk/main/xmldoc.c Thu Jul 19 17:17:13 2012
@@ -65,6 +65,10 @@
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);
+static int xmldoc_parse_para(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer);
+static int xmldoc_parse_specialtags(struct ast_xml_node *fixnode, const char *tabs, const char *posttabs, struct ast_str **buffer);
+
/*!
* \brief Container of documentation trees
@@ -1197,6 +1201,26 @@
}
/*! \internal
+ * \brief Parse common internal elements. This includes paragraphs, special
+ * tags, and information nodes.
+ * \param node The element to parse
+ * \param tabs Add this string before the content of the parsed element.
+ * \param posttabs Add this string after the content of the parsed element.
+ * \param buffer This must be an already allocated ast_str. It will be used to
+ * store the result (if something has already been placed in the
+ * buffer, the parsed elements will be appended)
+ * \retval 1 if any data was appended to the buffer
+ * \retval 2 if the data appended to the buffer contained a text paragraph
+ * \retval 0 if no data was appended to the buffer
+ */
+static int xmldoc_parse_common_elements(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
+{
+ return (xmldoc_parse_para(node, tabs, posttabs, buffer)
+ || xmldoc_parse_specialtags(node, tabs, posttabs, buffer)
+ || xmldoc_parse_info(node, tabs, posttabs, buffer));
+}
+
+/*! \internal
* \brief Parse a <para> element.
* \param node The <para> element pointer.
* \param tabs Added this string before the content of the <para> element.
@@ -1287,7 +1311,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 +1323,55 @@
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_common_elements(node, internaltabs, posttabs, buffer))) {
+ if (internal_ret > ret) {
+ ret = internal_ret;
+ }
+ }
+ }
+ ast_free(internaltabs);
return ret;
}
@@ -1327,7 +1401,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 +1410,7 @@
}
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_common_elements(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
count++;
ret = 1;
}
@@ -1368,10 +1439,7 @@
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_common_elements(tmp, (ret ? tabs : ""), "\n", buffer)) {
printedpara = 1;
continue;
}
@@ -1442,10 +1510,7 @@
}
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_common_elements(tmp, (ret ? tabs : ""), "\n", buffer)) {
ret = 1;
continue;
}
@@ -1579,9 +1644,7 @@
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_common_elements(node, (ret ? tabs : " - "), "\n", buffer)) {
ret = 1;
}
@@ -1659,9 +1722,7 @@
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_common_elements(node, (ret ? tabs : ""), "\n", buffer)) {
ret = 1;
}
@@ -1779,6 +1840,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 +1954,7 @@
} 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_common_elements(tmp, "", "\n", &ret)) {
continue;
}
/* if found, parse a <variablelist> element. */
Modified: trunk/res/res_xmpp.c
URL: http://svnview.digium.com/svn/asterisk/trunk/res/res_xmpp.c?view=diff&rev=370278&r1=370277&r2=370278
==============================================================================
--- trunk/res/res_xmpp.c (original)
+++ trunk/res/res_xmpp.c Thu Jul 19 17:17:13 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 svn-commits
mailing list