<html>
<body>
<div style="font-family: Verdana, Arial, Helvetica, Sans-Serif;">
<table bgcolor="#f9f3c9" width="100%" cellpadding="8" style="border: 1px #c9c399 solid;">
<tr>
<td>
This is an automatically generated e-mail. To reply, visit:
<a href="https://reviewboard.asterisk.org/r/2049/">https://reviewboard.asterisk.org/r/2049/</a>
</td>
</tr>
</table>
<br />
<table bgcolor="#fefadf" width="100%" cellspacing="0" cellpadding="8" style="background-image: url('https://reviewboard.asterisk.org/media/rb/images/review_request_box_top_bg.png'); background-position: left top; background-repeat: repeat-x; border: 1px black solid;">
<tr>
<td>
<div>Review request for Asterisk Developers and rmudgett.</div>
<div>By Matt Jordan.</div>
<h1 style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Description </h1>
<table width="100%" bgcolor="#ffffff" cellspacing="0" cellpadding="10" style="border: 1px solid #b8b5a0">
<tr>
<td>
<pre style="margin: 0; padding: 0; white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">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, while the MessageSend application is technology agnostic, how the channel drivers that support the MessageSend application behave is dependent on those the protocols and the channel driver implementation. Prior to this patch, those details were either documented in the application/command documentation itself, or were left undocumented.
Documenting technology specific information with the items that use that information tends to be problematic for the following reasons:
1) Sometimes, the documentation more naturally belongs in the channel driver or resource that implements that technology, as opposed to the consumer that uses it.
2) There may be multiple consumers that produce the technology specific behavior. It is not always clear who should provide the documentation for a technology specific behavior when multiple applications/commands share that behavior. This leads to confusion between documented applications, or inconsistency. For example, many technology specific behaviors documented for the Dial application can also apply to the Originate manager command (and possible FollowMe or Queue as well).
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 has historically had a note describing how the SIP channel driver interprets the From: field:
<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>
This information was replicated for the MessageSend AMI command. As the information is SIP specific information, it may be beneficial to document this information in chan_sip. As such, this can now be represented as an info node:
<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>
The MessageSend application/command can then reference this information using standard XInclude:
<xi:include xpointer="xpointer(/docs/info[@name='XMPPMessageToInfo'])" />
Note that while an application/command can use XInclude to pull the <info/> elements in, it is still possible to document the <info/> elements with the application/commands itself, as has been done historically.
An example of how this appears for the AMI command MessageSend is shown below. Note that technology specific information is given yellow markup in the CLI, in a manner similar to the <note/> elements.
*CLI> manager show command MessageSend
[Syntax]
Action: MessageSend
[ActionID:] <value>
To: <value>
[From:] <value>
[Body:] <value>
[Base64Body:] <value>
[Variable:] <value>
[Synopsis]
Send an out of call message to an endpoint.
[Description]
Not available
[Arguments]
ActionID
ActionID for this transaction. Will be returned.
To
The URI the message is to be sent to.
Technology: SIP
Specifying a prefix of 'sip:' will send the message as a
SIP MESSAGE request.
Technology: XMPP
Specifying a prefix of 'xmpp:' will send the message as an
XMPP chat message.
From
A From URI for the message if needed for the message technology being
used to send this message.
Technology: SIP
The 'from' parameter can be a configured peer name or in
the form of "display-name" <URI>.
Body
The message body text. This must not contain any newlines as that
conflicts with the AMI protocol.
Base64Body
Text bodies requiring the use of newlines have to be base64 encoded
in this field. Base64Body will be decoded before being sent out.
Base64Body takes precedence over Body.
Variable
Message variable to set, multiple Variable: headers are allowed.
The header value is a comma separated list of name=value pairs.
[See Also]
Not available
</pre>
</td>
</tr>
</table>
<h1 style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Diffs</b> </h1>
<ul style="margin-left: 3em; padding-left: 0;">
<li>/trunk/res/res_xmpp.c <span style="color: grey">(370048)</span></li>
<li>/trunk/doc/appdocsxml.dtd <span style="color: grey">(370048)</span></li>
<li>/trunk/main/message.c <span style="color: grey">(370048)</span></li>
<li>/trunk/main/xmldoc.c <span style="color: grey">(370048)</span></li>
<li>/trunk/channels/chan_sip.c <span style="color: grey">(370048)</span></li>
</ul>
<p><a href="https://reviewboard.asterisk.org/r/2049/diff/" style="margin-left: 3em;">View Diff</a></p>
</td>
</tr>
</table>
</div>
</body>
</html>