From 40bdfff73b2fd6e6f97de70de21ec60557118faa Mon Sep 17 00:00:00 2001
From: George Joseph <gjoseph@digium.com>
Date: Thu, 22 Apr 2021 12:07:22 -0600
Subject: [PATCH] Updates for the MessageSend Dialplan App
Enhancements:
* The MessageSend dialplan application now takes an optional
third argument that can set the message's "To" field on
outgoing messages. It's an alternative to using the
MESSAGE(to) dialplan function.
NOTE: No channel driver currently implements this field. A
follow-on commit for res_pjsip_messaging will implement it for
the chan_pjsip channel driver.
* To prevent confusion with the first argument, currently named
"to", it's been renamed to "destination". Its function,
creating the request URI, hasn't changed.
* The documentation for MessageSend was updated to be
more clear about the parameters and how they interact
the MESSAGE() dialplan function.
* With the rename of MessageSend's first parameter, and the fact
that message.c references <info> elements in chan_sip.c,
res_pjsip_messaging.c and res_xmpp, they each needed
documentation updates to use MessageDestinationInfo instead of
MessageToInfo.
* appdocsxml.dtd was updated to include a missing element
declaration for "dataType". This was showing up as an error
in Eclipse's dtd editor.
* Despite the changes in this commit, there should be
no impact to current users of MessageSend.
Change-Id: I6fb5b569657a02866a66ea352fd53d30d8ac965a
---
channels/chan_sip.c | 7 +++-
doc/CHANGES-staging/messagesend.txt | 16 ++++++++
doc/appdocsxml.dtd | 2 +
main/message.c | 61 +++++++++++++++++++++++------
res/res_pjsip_messaging.c | 7 +++-
res/res_xmpp.c | 5 ++-
6 files changed, 81 insertions(+), 17 deletions(-)
create mode 100644 doc/CHANGES-staging/messagesend.txt
diff --git a/channels/chan_sip.c b/channels/chan_sip.c
index 52bcd5ca6d..b13b892644 100644
--- a/channels/chan_sip.c
+++ b/channels/chan_sip.c
@@ -618,13 +618,16 @@
for all of the sip peers will be retrieved.</para>
</description>
</manager>
+ <info name="MessageDestinationInfo" language="en_US" tech="SIP">
+ <para>Specifying a prefix of <literal>sip:</literal> will send the
+ message as a SIP MESSAGE request.</para>
+ </info>
<info name="MessageFromInfo" 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="MessageToInfo" language="en_US" tech="SIP">
- <para>Specifying a prefix of <literal>sip:</literal> will send the
- message as a SIP MESSAGE request.</para>
+ <para>Ignored</para>
</info>
<managerEvent language="en_US" name="SIPQualifyPeerDone">
<managerEventInstance class="EVENT_FLAG_CALL">
diff --git a/doc/CHANGES-staging/messagesend.txt b/doc/CHANGES-staging/messagesend.txt
new file mode 100644
index 0000000000..7977ff15c8
--- /dev/null
+++ b/doc/CHANGES-staging/messagesend.txt
@@ -0,0 +1,16 @@
+Subject: MessageSend
+
+The MessageSend dialplan application now takes an
+optional third argument that can set the message's
+"To" field on outgoing messages. It's an alternative
+to using the MESSAGE(to) dialplan function.
+
+To prevent confusion with the first argument, currently
+named "to", it's been renamed to "destination".
+Its function, creating the request URI, hasn't changed.
+
+The online documentation has also been enhanced to
+explain the behavior.
+
+Despite the changes in this commit, there should be
+no impact to current users of MessageSend.
diff --git a/doc/appdocsxml.dtd b/doc/appdocsxml.dtd
index 7723bd5dc8..93fdd3afea 100644
--- a/doc/appdocsxml.dtd
+++ b/doc/appdocsxml.dtd
@@ -83,6 +83,8 @@
<!ELEMENT matchInfo (category|field?)>
+ <!ELEMENT dataType (#PCDATA)>
+
<!ELEMENT category (#PCDATA)>
<!ATTLIST category match (yes|no|true|false) #REQUIRED>
diff --git a/main/message.c b/main/message.c
index b6f254d166..75450e913d 100644
--- a/main/message.c
+++ b/main/message.c
@@ -52,13 +52,25 @@
<para>Field of the message to get or set.</para>
<enumlist>
<enum name="to">
- <para>Read-only. The destination of the message. When processing an
+ <para>When processing an
incoming message, this will be set to the destination listed as
the recipient of the message that was received by Asterisk.</para>
+ <para>
+ </para>
+ <para>For an outgoing message, this will set the To header in the
+ outgoing SIP message. This may be overridden by the "to" parameter
+ of MessageSend.
+ </para>
</enum>
<enum name="from">
- <para>Read-only. The source of the message. When processing an
+ <para>When processing an
incoming message, this will be set to the source of the message.</para>
+ <para>
+ </para>
+ <para>For an outgoing message, this will set the From header in the
+ outgoing SIP message. This may be overridden by the "from" parameter
+ of MessageSend.
+ </para>
</enum>
<enum name="custom_data">
<para>Write-only. Mark or unmark all message headers for an outgoing
@@ -119,23 +131,39 @@
Send a text message.
</synopsis>
<syntax>
- <parameter name="to" required="true">
+ <parameter name="destination" required="true">
<para>A To URI for the message.</para>
- <xi:include xpointer="xpointer(/docs/info[@name='MessageToInfo'])" />
+ <xi:include xpointer="xpointer(/docs/info[@name='MessageDestinationInfo'])" />
</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. This can be a
SIP(S) URI, such as <literal>Alice <sip:alice@atlanta.com></literal>,
- a string in the format <literal>alice@atlanta.com</literal>, or simply
- a username such as <literal>alice</literal>.</para>
+ or a string in the format <literal>alice@atlanta.com</literal>.
+ This will override a <literal>from</literal>
+ specified using the MESSAGE dialplan function or the <literal>from</literal>
+ that may have been on an incoming message.
+ </para>
+ <xi:include xpointer="xpointer(/docs/info[@name='MessageFromInfo'])" />
+ </parameter>
+ <parameter name="to" required="false">
+ <para>A To URI for the message if needed for the
+ message technology being used to send this message. This can be a
+ SIP(S) URI, such as <literal>Alice <sip:alice@atlanta.com></literal>,
+ or a string in the format <literal>alice@atlanta.com</literal>.
+ This will override a <literal>to</literal>
+ specified using the MESSAGE dialplan function or the <literal>to</literal>
+ that may have been on an incoming message.
+ </para>
+ <xi:include xpointer="xpointer(/docs/info[@name='MessageToInfo'])" />
</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>.
- The technology chosen for sending the message is determined
- based on a prefix to the <literal>to</literal> parameter.</para>
+ This may he come from an incoming message.
+ The technology chosen for sending the message is determined
+ based on a prefix to the <literal>destination</literal> parameter.</para>
<para>This application sets the following channel variables:</para>
<variablelist>
<variable name="MESSAGE_SEND_STATUS">
@@ -1204,8 +1232,9 @@ static int msg_send_exec(struct ast_channel *chan, const char *data)
char *parse;
int res = -1;
AST_DECLARE_APP_ARGS(args,
- AST_APP_ARG(to);
+ AST_APP_ARG(destination);
AST_APP_ARG(from);
+ AST_APP_ARG(to);
);
if (ast_strlen_zero(data)) {
@@ -1217,7 +1246,7 @@ static int msg_send_exec(struct ast_channel *chan, const char *data)
parse = ast_strdupa(data);
AST_STANDARD_APP_ARGS(args, parse);
- if (ast_strlen_zero(args.to)) {
+ if (ast_strlen_zero(args.destination)) {
ast_log(LOG_WARNING, "A 'to' URI is required for MessageSend()\n");
pbx_builtin_setvar_helper(chan, "MESSAGE_SEND_STATUS", "INVALID_URI");
return 0;
@@ -1236,7 +1265,7 @@ static int msg_send_exec(struct ast_channel *chan, const char *data)
ao2_ref(msg, +1);
ast_channel_unlock(chan);
- tech_name = ast_strdupa(args.to);
+ tech_name = ast_strdupa(args.destination);
tech_name = strsep(&tech_name, ":");
ast_rwlock_rdlock(&msg_techs_lock);
@@ -1248,13 +1277,21 @@ static int msg_send_exec(struct ast_channel *chan, const char *data)
goto exit_cleanup;
}
+ /*
+ * If there was a "to" in the call to MessageSend,
+ * replace the to already in the channel datastore.
+ */
+ if (!ast_strlen_zero(args.to)) {
+ ast_string_field_set(msg, to, args.to);
+ }
+
/*
* The message lock is held here to safely allow the technology
* implementation to access the message fields without worrying
* that they could change.
*/
ao2_lock(msg);
- res = msg_tech->msg_send(msg, S_OR(args.to, ""), S_OR(args.from, ""));
+ res = msg_tech->msg_send(msg, S_OR(args.destination, ""), S_OR(args.from, ""));
ao2_unlock(msg);
pbx_builtin_setvar_helper(chan, "MESSAGE_SEND_STATUS", res ? "FAILURE" : "SUCCESS");
diff --git a/res/res_pjsip_messaging.c b/res/res_pjsip_messaging.c
index 5378b8cd6b..92873244ef 100644
--- a/res/res_pjsip_messaging.c
+++ b/res/res_pjsip_messaging.c
@@ -24,13 +24,16 @@
***/
/*** DOCUMENTATION
+ <info name="MessageDestinationInfo" language="en_US" tech="PJSIP">
+ <para>Specifying a prefix of <literal>pjsip:</literal> will send the
+ message as a SIP MESSAGE request.</para>
+ </info>
<info name="MessageFromInfo" language="en_US" tech="PJSIP">
<para>The <literal>from</literal> parameter can be a configured endpoint
or in the form of "display-name" <URI>.</para>
</info>
<info name="MessageToInfo" language="en_US" tech="PJSIP">
- <para>Specifying a prefix of <literal>pjsip:</literal> will send the
- message as a SIP MESSAGE request.</para>
+ <para>Ignored</para>
</info>
***/
#include "asterisk.h"
diff --git a/res/res_xmpp.c b/res/res_xmpp.c
index 0f304375fe..63dc257a21 100644
--- a/res/res_xmpp.c
+++ b/res/res_xmpp.c
@@ -251,7 +251,7 @@
<para>Sends a message to a Jabber Client.</para>
</description>
</manager>
- <info name="MessageToInfo" language="en_US" tech="XMPP">
+ <info name="MessageDestinationInfo" language="en_US" tech="XMPP">
<para>Specifying a prefix of <literal>xmpp:</literal> will send the
message as an XMPP chat message.</para>
</info>
@@ -260,6 +260,9 @@
account defined in <literal>xmpp.conf</literal> to send the message from.
Note that this field is required for XMPP messages.</para>
</info>
+ <info name="MessageToInfo" language="en_US" tech="XMPP">
+ <para>Ignored</para>
+ </info>
<configInfo name="res_xmpp" language="en_US">
<synopsis>XMPP Messaging</synopsis>
<configFile name="xmpp.conf">
--
GitLab