Enhanced Messaging

Data Structures
struct	ast_msg_data_attribute

Enumerations
enum	ast_msg_data_attribute_type {   AST_MSG_DATA_ATTR_TO = 0, AST_MSG_DATA_ATTR_FROM, AST_MSG_DATA_ATTR_CONTENT_TYPE, AST_MSG_DATA_ATTR_BODY,   __AST_MSG_DATA_ATTR_LAST }
enum	ast_msg_data_source_type {   AST_MSG_DATA_SOURCE_TYPE_UNKNOWN = 0, AST_MSG_DATA_SOURCE_TYPE_T140, AST_MSG_DATA_SOURCE_TYPE_IN_DIALOG, AST_MSG_DATA_SOURCE_TYPE_OUT_OF_DIALOG,   __AST_MSG_DATA_SOURCE_TYPE_LAST }

Functions
struct ast_msg_data *	ast_msg_data_alloc (enum ast_msg_data_source_type source, struct ast_msg_data_attribute attributes[], size_t count)
	Allocates an ast_msg_data structure. More...
struct ast_msg_data *	ast_msg_data_alloc2 (enum ast_msg_data_source_type source_type, const char *to, const char *from, const char *content_type, const char *body)
	Allocates an ast_msg_data structure. More...
struct ast_msg_data *	ast_msg_data_dup (struct ast_msg_data *msg)
	Clone an ast_msg_data structure. More...
const char *	ast_msg_data_get_attribute (struct ast_msg_data *msg, enum ast_msg_data_attribute_type attribute_type)
	Get attribute from ast_msg_data. More...
size_t	ast_msg_data_get_length (struct ast_msg_data *msg)
	Get length of the structure. More...
enum ast_msg_data_source_type	ast_msg_data_get_source_type (struct ast_msg_data *msg)
	Get "source type" from ast_msg_data. More...
int	ast_msg_data_queue_frame (struct ast_channel *channel, struct ast_msg_data *msg)
	Queue an AST_FRAME_TEXT_DATA frame containing an ast_msg_data structure. More...

Detailed Description

Enhanced Messaging

The basic messaging framework has a basic drawback... It can only pass a text string through the core. This causes several issues:

• Only a content type of text/plain can be passed.
• If a softmix bridge is used, the original sender identity is lost.

The Enhanced Messaging framework allows attributes, such as "From", "To" and "Content-Type" to be attached to the message by the incoming channel tech which can then be used by the outgoing channel tech to construct the appropriate technology-specific outgoing message.

Enumeration Type Documentation

ast_msg_data_attribute_type

enum ast_msg_data_attribute_type

Enumerator
AST_MSG_DATA_ATTR_TO
AST_MSG_DATA_ATTR_FROM
AST_MSG_DATA_ATTR_CONTENT_TYPE
AST_MSG_DATA_ATTR_BODY
__AST_MSG_DATA_ATTR_LAST

Definition at line 454 of file message.h.

                                 {
   AST_MSG_DATA_ATTR_TO = 0,
   AST_MSG_DATA_ATTR_FROM,
   AST_MSG_DATA_ATTR_CONTENT_TYPE,
   AST_MSG_DATA_ATTR_BODY,
   __AST_MSG_DATA_ATTR_LAST,
};

ast_msg_data_source_type

enum ast_msg_data_source_type

Enumerator
AST_MSG_DATA_SOURCE_TYPE_UNKNOWN
AST_MSG_DATA_SOURCE_TYPE_T140
AST_MSG_DATA_SOURCE_TYPE_IN_DIALOG
AST_MSG_DATA_SOURCE_TYPE_OUT_OF_DIALOG
__AST_MSG_DATA_SOURCE_TYPE_LAST

Definition at line 446 of file message.h.

                              {
   AST_MSG_DATA_SOURCE_TYPE_UNKNOWN = 0,
   AST_MSG_DATA_SOURCE_TYPE_T140,
   AST_MSG_DATA_SOURCE_TYPE_IN_DIALOG,
   AST_MSG_DATA_SOURCE_TYPE_OUT_OF_DIALOG,
   __AST_MSG_DATA_SOURCE_TYPE_LAST,
};

Function Documentation

ast_msg_data_alloc()

struct ast_msg_data* ast_msg_data_alloc	(	enum ast_msg_data_source_type	source,
		struct ast_msg_data_attribute	attributes[],
		size_t	count
	)

Allocates an ast_msg_data structure.

Since

13.22.0

15.5.0

Parameters

source	The source type of the message
attributes	A pointer to an array of ast_msg_data_attribute structures
count	The number of elements in the array

Returns

Pointer to msg structure or NULL on allocation failure. Caller must call ast_free when done.

Definition at line 1418 of file message.c.

References __AST_MSG_DATA_ATTR_LAST, ast_assert, ast_calloc, ast_copy_string(), ATTRIBUTE_UNSET, attribute_value_offsets, buf, len(), length, msg_data::msg, NULL, source, ast_msg_data_attribute::type, msg_data::value, and ast_msg_data_attribute::value.

Referenced by ast_msg_data_alloc2(), ast_sendtext(), chan_pjsip_sendtext(), incoming_in_dialog_request(), send_message(), and sendtext_exec().

{
   struct ast_msg_data *msg;
   size_t len = sizeof(*msg);
   size_t i;
   size_t current_offset = 0;
   enum ast_msg_data_attribute_type attr_type;

   if (!attributes) {
      ast_assert(attributes != NULL);
      return NULL;
   }

   if (!count) {
      ast_assert(count > 0);
      return NULL;
   }

   /* Calculate the length required for the buffer */
   for (i=0; i < count; i++) {
      if (!attributes[i].value) {
         ast_assert(attributes[i].value != NULL);
         return NULL;
      }
      len += (strlen(attributes[i].value) + 1);
   }

   msg = ast_calloc(1, len);
   if (!msg) {
      return NULL;
   }
   msg->source = source;
   msg->length = len;

   /* Mark all of the attributes as unset */
   for (attr_type = 0; attr_type < __AST_MSG_DATA_ATTR_LAST; attr_type++) {
      msg->attribute_value_offsets[attr_type] = ATTRIBUTE_UNSET;
   }

   /* Set the ones we have and increment the offset */
   for (i=0; i < count; i++) {
      len = (strlen(attributes[i].value) + 1);
      ast_copy_string(msg->buf + current_offset, attributes[i].value, len); /* Safe */
      msg->attribute_value_offsets[attributes[i].type] = current_offset;
      current_offset += len;
   }

   return msg;
}

ast_msg_data_alloc2()

struct ast_msg_data* ast_msg_data_alloc2	(	enum ast_msg_data_source_type	source_type,
		const char *	to,
		const char *	from,
		const char *	content_type,
		const char *	body
	)

Allocates an ast_msg_data structure.

Since

13.35.0

16.12.0

17.6.0

Parameters

source	The source type of the message
to	Where the message is sent to
from	Where the message is sent from
content_type	Content type of the body
body	The message body

Returns

Pointer to msg structure or NULL on allocation failure. Caller must call ast_free when done.

Definition at line 1469 of file message.c.

References ARRAY_LEN, ast_msg_data_alloc(), AST_MSG_DATA_ATTR_BODY, AST_MSG_DATA_ATTR_CONTENT_TYPE, AST_MSG_DATA_ATTR_FROM, AST_MSG_DATA_ATTR_TO, S_OR, and ast_msg_data_attribute::type.

Referenced by queue_sendtext_data().

{
   struct ast_msg_data_attribute attrs[] =
   {
      {
         .type = AST_MSG_DATA_ATTR_TO,
         .value = (char *)S_OR(to, ""),
      },
      {
         .type = AST_MSG_DATA_ATTR_FROM,
         .value = (char *)S_OR(from, ""),
      },
      {
         .type = AST_MSG_DATA_ATTR_CONTENT_TYPE,
         .value = (char *)S_OR(content_type, ""),
      },
      {
         .type = AST_MSG_DATA_ATTR_BODY,
         .value = (char *)S_OR(body, ""),
      },
   };

   return ast_msg_data_alloc(source_type, attrs, ARRAY_LEN(attrs));
}

ast_msg_data_dup()

struct ast_msg_data* ast_msg_data_dup

(

struct ast_msg_data *

msg

)

Clone an ast_msg_data structure.

Since

13.22.0

15.5.0

Parameters

msg	The message to clone

Returns

New message structure or NULL if there was an allocation failure. Caller must call ast_free when done.

Definition at line 1495 of file message.c.

References ast_assert, ast_malloc, length, and NULL.

Referenced by sendtext_data_create().

{
   struct ast_msg_data *dest;

   if (!msg) {
      ast_assert(msg != NULL);
      return NULL;
   }

   dest = ast_malloc(msg->length);
   if (!dest) {
      return NULL;
   }
   memcpy(dest, msg, msg->length);

   return dest;
}

ast_msg_data_get_attribute()

const char* ast_msg_data_get_attribute	(	struct ast_msg_data *	msg,
		enum ast_msg_data_attribute_type	attribute_type
	)

Get attribute from ast_msg_data.

Since

13.22.0

15.5.0

Parameters

msg	Pointer to ast_msg_data structure
attribute_type	One of ast_msg_data_attribute_type

Returns

The attribute or an empty string ("") if the attribute wasn't set.

Definition at line 1533 of file message.c.

References ast_assert, ATTRIBUTE_UNSET, attribute_value_offsets, buf, and NULL.

Referenced by ast_bridge_channel_queue_frame(), ast_sendtext_data(), bridge_channel_handle_write(), chan_pjsip_sendtext_data(), incoming_in_dialog_request(), sendtext(), and softmix_bridge_write_text().

{
   if (!msg) {
      ast_assert(msg != NULL);
      return "";
   }

   if (msg->attribute_value_offsets[attribute_type] > ATTRIBUTE_UNSET) {
      return msg->buf + msg->attribute_value_offsets[attribute_type];
   }

   return "";
}

ast_msg_data_get_length()

size_t ast_msg_data_get_length

(

struct ast_msg_data *

msg

)

Get length of the structure.

Since

13.22.0

15.5.0

Parameters

msg	Pointer to ast_msg_data structure

Returns

The length of the structure itself plus the dynamically allocated attribute buffer.

Definition at line 1513 of file message.c.

References ast_assert, length, and NULL.

Referenced by queue_sendtext_data(), and send_message().

{
   if (!msg) {
      ast_assert(msg != NULL);
      return 0;
   }

   return msg->length;
}

ast_msg_data_get_source_type()

enum ast_msg_data_source_type ast_msg_data_get_source_type

(

struct ast_msg_data *

msg

)

Get "source type" from ast_msg_data.

Since

13.22.0

15.5.0

Parameters

msg	Pointer to ast_msg_data structure

Returns

The source type field.

Definition at line 1523 of file message.c.

References ast_assert, AST_MSG_DATA_SOURCE_TYPE_UNKNOWN, NULL, and source.

{
   if (!msg) {
      ast_assert(msg != NULL);
      return AST_MSG_DATA_SOURCE_TYPE_UNKNOWN;
   }

   return msg->source;
}

ast_msg_data_queue_frame()

int ast_msg_data_queue_frame	(	struct ast_channel *	channel,
		struct ast_msg_data *	msg
	)

Queue an AST_FRAME_TEXT_DATA frame containing an ast_msg_data structure.

Since

13.22.0

15.5.0

Parameters

channel	The channel on which to queue the frame
msg	Pointer to ast_msg_data structure

Return values

-1	Error
0	Success

Definition at line 1548 of file message.c.

References ast_assert, AST_FRAME_TEXT_DATA, ast_queue_frame(), ast_frame::data, ast_frame::datalen, ast_frame::frametype, length, msg_data::msg, NULL, and ast_frame::ptr.

Referenced by incoming_in_dialog_request().

{
   struct ast_frame f;

   if (!channel) {
      ast_assert(channel != NULL);
      return -1;
   }

   if (!msg) {
      ast_assert(msg != NULL);
      return -1;
   }

   memset(&f, 0, sizeof(f));
   f.frametype = AST_FRAME_TEXT_DATA;
   f.data.ptr = msg;
   f.datalen = msg->length;
   return ast_queue_frame(channel, &f);
}