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 1458 of file main/message.c.

{
    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;
}

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

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

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_type	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 1509 of file main/message.c.

{
    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));
}

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().

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 1535 of file main/message.c.

{
    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;
}

References ast_assert, ast_malloc, length, and NULL.

Referenced by sendtext_data_create().

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 1573 of file main/message.c.

{
    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 "";
}

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().

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 1553 of file main/message.c.

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

References ast_assert, length, and NULL.

Referenced by queue_sendtext_data(), and send_message().

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 1563 of file main/message.c.

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

References ast_assert, AST_MSG_DATA_SOURCE_TYPE_UNKNOWN, NULL, and 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 1588 of file main/message.c.

{
    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);
}

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

Referenced by incoming_in_dialog_request().