[Asterisk-code-review] Updates for the MessageSend Dialplan App (asterisk[master])

George Joseph asteriskteam at digium.com
Thu May 6 06:23:54 CDT 2021


George Joseph has submitted this change. ( https://gerrit.asterisk.org/c/asterisk/+/15827 )

Change subject: Updates for the MessageSend Dialplan App
......................................................................

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
---
M channels/chan_sip.c
A doc/CHANGES-staging/messagesend.txt
M doc/appdocsxml.dtd
M main/message.c
M res/res_pjsip_messaging.c
M res/res_xmpp.c
6 files changed, 81 insertions(+), 17 deletions(-)

Approvals:
  Joshua Colp: Looks good to me, but someone else must approve
  Kevin Harwell: Looks good to me, but someone else must approve
  George Joseph: Looks good to me, approved; Approved for Submit



diff --git a/channels/chan_sip.c b/channels/chan_sip.c
index da0e0de..77e1b24 100644
--- a/channels/chan_sip.c
+++ b/channels/chan_sip.c
@@ -619,13 +619,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 0000000..7977ff1
--- /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 7723bd5..93fdd3a 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 b6f254d..c667b0c 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 ourgoing 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 ourgoing 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 at atlanta.com></literal>,
-				a string in the format <literal>alice at atlanta.com</literal>, or simply
-				a username such as <literal>alice</literal>.</para>
+				or a string in the format <literal>alice at 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 at atlanta.com></literal>,
+				or a string in the format <literal>alice at 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 @@
 	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 @@
 	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 @@
 	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);
@@ -1249,12 +1278,20 @@
 	}
 
 	/*
+	 * 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 5378b8c..9287324 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 0f30437..63dc257 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">

-- 
To view, visit https://gerrit.asterisk.org/c/asterisk/+/15827
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings

Gerrit-Project: asterisk
Gerrit-Branch: master
Gerrit-Change-Id: I6fb5b569657a02866a66ea352fd53d30d8ac965a
Gerrit-Change-Number: 15827
Gerrit-PatchSet: 4
Gerrit-Owner: George Joseph <gjoseph at digium.com>
Gerrit-Reviewer: Friendly Automation
Gerrit-Reviewer: George Joseph <gjoseph at digium.com>
Gerrit-Reviewer: Joshua Colp <jcolp at sangoma.com>
Gerrit-Reviewer: Kevin Harwell <kharwell at digium.com>
Gerrit-MessageType: merged
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20210506/405f5a28/attachment-0001.html>


More information about the asterisk-code-review mailing list