Multiple revisions 420089-420090,420097

........
  r420089 | mjordan | 2014-08-05 15:10:52 -0500 (Tue, 05 Aug 2014) | 72 lines
  
  ARI: Add channel technology agnostic out of call text messaging
  
  This patch adds the ability to send and receive text messages from various
  technology stacks in Asterisk through ARI. This includes chan_sip (sip),
  res_pjsip_messaging (pjsip), and res_xmpp (xmpp). Messages are sent using the
  endpoints resource, and can be sent directly through that resource, or to a
  particular endpoint.
  
  For example, the following would send the message "Hello there" to PJSIP
  endpoint alice with a display URI of sip:asterisk@mycooldomain.org:
  
  ari/endpoints/sendMessage?to=pjsip:alice&from=sip:asterisk@mycooldomain.org&body=Hello+There
  
  This is equivalent to the following as well:
  
  ari/endpoints/PJSIP/alice/sendMessage?from=sip:asterisk@mycooldomain.org&body=Hello+There
  
  Both forms are available for message technologies that allow for arbitrary
  destinations, such as chan_sip.
  
  Inbound messages can now be received over ARI as well. An ARI application that
  subscribes to endpoints will receive messages from those endpoints:
  
  {
    "type": "TextMessageReceived",
    "timestamp": "2014-07-12T22:53:13.494-0500",
    "endpoint": {
      "technology": "PJSIP",
      "resource": "alice",
      "state": "online",
      "channel_ids": []
    },
    "message": {
      "from": "\"alice\" <sip:alice@127.0.0.1>",
      "to": "pjsip:asterisk@127.0.0.1",
      "body": "Watson, come here.",
      "variables": []
    },
    "application": "testsuite"
  }
  
  The above was made possible due to some rather major changes in the message
  core. This includes (but is not limited to):
  - Users of the message API can now register message handlers. A handler has
    two callbacks: one to determine if the handler has a destination for the
    message, and another to handle it.
  - All dialplan functionality of handling a message was moved into a message
    handler provided by the message API.
  - Messages can now have the technology/endpoint associated with them.
    Various other properties are also now more easily accessible.
  - A number of ao2 containers that weren't really needed were replaced with
    vectors. Iteration over ao2_containers is expensive and pointless when
    the lifetime of things is well defined and the number of things is very
    small.
  
  res_stasis now has a new file that makes up its structure, messaging. The
  messaging functionality implements a message handler, and passes received
  messages that match an interested endpoint over to the app for processing.
  
  Note that inadvertently while testing this, I reproduced ASTERISK-23969.
  res_pjsip_messaging was incorrectly parsing out the 'to' field, such that
  arbitrary SIP URIs mangled the endpoint lookup. This patch includes the
  fix for that as well.
  
  Review: https://reviewboard.asterisk.org/r/3726
  
  ASTERISK-23692 #close
  Reported by: Matt Jordan
  
  ASTERISK-23969 #close
  Reported by: Andrew Nagy
........
  r420090 | mjordan | 2014-08-05 15:16:37 -0500 (Tue, 05 Aug 2014) | 2 lines
  
  Remove automerge properties :-(
........
  r420097 | mjordan | 2014-08-05 16:36:25 -0500 (Tue, 05 Aug 2014) | 2 lines
  
  test_message: Fix strict-aliasing compilation issue
........

Merged revisions 420089-420090,420097 from http://svn.asterisk.org/svn/asterisk/branches/12


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@420098 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 144 insertions, 3 deletions

diff --git a/include/asterisk/message.h b/include/asterisk/message.h
index 7e5c77a6a..f81574c9b 100644
--- a/include/asterisk/message.h
+++ b/include/asterisk/message.h
@@ -25,8 +25,9 @@
  *
  * The purpose of this API is to provide support for text messages that
  * are not session based.  The messages are passed into the Asterisk core
- * to be routed through the dialplan and potentially sent back out through
- * a message technology that has been registered through this API.
+ * to be routed through the dialplan or another interface and potentially
+ * sent back out through a message technology that has been registered
+ * through this API.
  */
 
 #ifndef __AST_MESSAGE_H__
@@ -91,6 +92,64 @@ int ast_msg_tech_register(const struct ast_msg_tech *tech);
 int ast_msg_tech_unregister(const struct ast_msg_tech *tech);
 
 /*!
+ * \brief An external processor of received messages
+ * \since 12.5.0
+ */
+struct ast_msg_handler {
+	/*!
+	 * \brief Name of the message handler
+	 */
+	const char *name;
+
+	/*!
+	 * \brief The function callback that will handle the message
+	 *
+	 * \param msg The message to handle
+	 *
+	 * \retval 0 The handler processed the message successfull
+	 * \retval non-zero The handler passed or could not process the message
+	 */
+	int (* const handle_msg)(struct ast_msg *msg);
+
+	/*!
+	 * \brief Return whether or not the message has a valid destination
+	 *
+	 * A message may be delivered to the dialplan and/or other locations,
+	 * depending on whether or not other handlers have been registered. This
+	 * function is called by the message core to determine if any handler can
+	 * process a message.
+	 *
+	 * \param msg The message to inspect
+	 *
+	 * \retval 0 The message does not have a valid destination
+	 * \retval 1 The message has a valid destination
+	 */
+	int (* const has_destination)(const struct ast_msg *msg);
+};
+
+/*!
+ * \brief Register a \c ast_msg_handler
+ * \since 12.5.0
+ *
+ * \param handler The handler to register
+ *
+ * \retval 0 Success
+ * \retval non-zero Error
+ */
+int ast_msg_handler_register(const struct ast_msg_handler *handler);
+
+/*!
+ * \brief Unregister a \c ast_msg_handler
+ * \since 12.5.0
+ *
+ * \param handler The handler to unregister
+ *
+ * \retval 0 Success
+ * \retval non-zero Error
+ */
+int ast_msg_handler_unregister(const struct ast_msg_handler *handler);
+
+/*!
  * \brief Allocate a message.
  *
  * Allocate a message for the purposes of passing it into the Asterisk core
@@ -162,7 +221,29 @@ int __attribute__((format(printf, 2, 3)))
  */
 int __attribute__((format(printf, 2, 3)))
 		ast_msg_set_exten(struct ast_msg *msg, const char *fmt, ...);
-	
+
+/*!
+ * \brief Set the technology associated with this message
+ *
+ * \since 12.5.0
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int __attribute__((format(printf, 2, 3)))
+		ast_msg_set_tech(struct ast_msg *msg, const char *fmt, ...);
+
+/*!
+ * \brief Set the technology's endpoint associated with this message
+ *
+ * \since 12.5.0
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int __attribute__((format(printf, 2, 3)))
+		ast_msg_set_endpoint(struct ast_msg *msg, const char *fmt, ...);
+
 /*!
  * \brief Set a variable on the message going to the dialplan.
  * \note Setting a variable that already exists overwrites the existing variable value
@@ -209,6 +290,66 @@ const char *ast_msg_get_var(struct ast_msg *msg, const char *name);
 const char *ast_msg_get_body(const struct ast_msg *msg);
 
 /*!
+ * \brief Retrieve the source of this message
+ *
+ * \since 12.5.0
+ *
+ * \param msg The message to get the soure from
+ *
+ * \retval The source of the message
+ * \retval NULL or empty string if the message has no source
+ */
+const char *ast_msg_get_from(const struct ast_msg *msg);
+
+/*!
+ * \brief Retrieve the destination of this message
+ *
+ * \since 12.5.0
+ *
+ * \param msg The message to get the destination from
+ *
+ * \retval The destination of the message
+ * \retval NULL or empty string if the message has no destination
+ */
+const char *ast_msg_get_to(const struct ast_msg *msg);
+
+/*!
+ * \brief Retrieve the technology associated with this message
+ *
+ * \since 12.5.0
+ *
+ * \param msg The message to get the technology from
+ *
+ * \retval The technology of the message
+ * \retval NULL or empty string if the message has no associated technology
+ */
+const char *ast_msg_get_tech(const struct ast_msg *msg);
+
+/*!
+ * \brief Retrieve the endpoint associated with this message
+ *
+ * \since 12.5.0
+ *
+ * \param msg The message to get the endpoint from
+ *
+ * \retval The endpoint associated with the message
+ * \retval NULL or empty string if the message has no associated endpoint
+ */
+const char *ast_msg_get_endpoint(const struct ast_msg *msg);
+
+/*!
+ * \brief Determine if a particular message has a destination via some handler
+ *
+ * \since 12.5.0
+ *
+ * \param msg The message to check
+ *
+ * \retval 0 if the message has no handler that can find a destination
+ * \retval 1 if the message has a handler that can find a destination
+ */
+int ast_msg_has_destination(const struct ast_msg *msg);
+
+/*!
  * \brief Queue a message for routing through the dialplan.
  *
  * Regardless of the return value of this function, this funciton will take