Asterisk - The Open Source Telephony Project GIT-master-d856a3e
Data Structures | Enumerations | Functions
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_dataast_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_dataast_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_dataast_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:

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

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.

454 {
460};
@ AST_MSG_DATA_ATTR_BODY
Definition: message.h:458
@ AST_MSG_DATA_ATTR_TO
Definition: message.h:455
@ AST_MSG_DATA_ATTR_FROM
Definition: message.h:456
@ __AST_MSG_DATA_ATTR_LAST
Definition: message.h:459
@ AST_MSG_DATA_ATTR_CONTENT_TYPE
Definition: message.h:457

◆ 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.

446 {
452};
@ __AST_MSG_DATA_SOURCE_TYPE_LAST
Definition: message.h:451
@ AST_MSG_DATA_SOURCE_TYPE_UNKNOWN
Definition: message.h:447
@ AST_MSG_DATA_SOURCE_TYPE_IN_DIALOG
Definition: message.h:449
@ AST_MSG_DATA_SOURCE_TYPE_T140
Definition: message.h:448
@ AST_MSG_DATA_SOURCE_TYPE_OUT_OF_DIALOG
Definition: message.h:450

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
sourceThe source type of the message
attributesA pointer to an array of ast_msg_data_attribute structures
countThe 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 1446 of file main/message.c.

1448{
1449 struct ast_msg_data *msg;
1450 size_t len = sizeof(*msg);
1451 size_t i;
1452 size_t current_offset = 0;
1453 enum ast_msg_data_attribute_type attr_type;
1454
1455 if (!attributes) {
1456 ast_assert(attributes != NULL);
1457 return NULL;
1458 }
1459
1460 if (!count) {
1461 ast_assert(count > 0);
1462 return NULL;
1463 }
1464
1465 /* Calculate the length required for the buffer */
1466 for (i=0; i < count; i++) {
1467 if (!attributes[i].value) {
1468 ast_assert(attributes[i].value != NULL);
1469 return NULL;
1470 }
1471 len += (strlen(attributes[i].value) + 1);
1472 }
1473
1474 msg = ast_calloc(1, len);
1475 if (!msg) {
1476 return NULL;
1477 }
1478 msg->source = source;
1479 msg->length = len;
1480
1481 /* Mark all of the attributes as unset */
1482 for (attr_type = 0; attr_type < __AST_MSG_DATA_ATTR_LAST; attr_type++) {
1483 msg->attribute_value_offsets[attr_type] = ATTRIBUTE_UNSET;
1484 }
1485
1486 /* Set the ones we have and increment the offset */
1487 for (i=0; i < count; i++) {
1488 len = (strlen(attributes[i].value) + 1);
1489 ast_copy_string(msg->buf + current_offset, attributes[i].value, len); /* Safe */
1490 msg->attribute_value_offsets[attributes[i].type] = current_offset;
1491 current_offset += len;
1492 }
1493
1494 return msg;
1495}
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
ast_msg_data_attribute_type
Definition: message.h:454
#define ATTRIBUTE_UNSET
#define NULL
Definition: resample.c:96
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:425
enum ast_msg_data_attribute_type type
Definition: message.h:463
Structure used to transport a message through the frame core.
enum ast_msg_data_source_type source
int attribute_value_offsets[__AST_MSG_DATA_ATTR_LAST]
int value
Definition: syslog.c:37
#define ast_assert(a)
Definition: utils.h:739

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_typeThe source type of the message
toWhere the message is sent to
fromWhere the message is sent from
content_typeContent type of the body
bodyThe message body
Returns
Pointer to msg structure or NULL on allocation failure. Caller must call ast_free when done.

Definition at line 1497 of file main/message.c.

1499{
1500 struct ast_msg_data_attribute attrs[] =
1501 {
1502 {
1504 .value = (char *)S_OR(to, ""),
1505 },
1506 {
1507 .type = AST_MSG_DATA_ATTR_FROM,
1508 .value = (char *)S_OR(from, ""),
1509 },
1510 {
1512 .value = (char *)S_OR(content_type, ""),
1513 },
1514 {
1515 .type = AST_MSG_DATA_ATTR_BODY,
1516 .value = (char *)S_OR(body, ""),
1517 },
1518 };
1519
1520 return ast_msg_data_alloc(source_type, attrs, ARRAY_LEN(attrs));
1521}
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.
#define S_OR(a, b)
returns the equivalent of logic or for strings: first one if not empty, otherwise second one.
Definition: strings.h:80
#define ARRAY_LEN(a)
Definition: utils.h:666

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

1524{
1525 struct ast_msg_data *dest;
1526
1527 if (!msg) {
1528 ast_assert(msg != NULL);
1529 return NULL;
1530 }
1531
1532 dest = ast_malloc(msg->length);
1533 if (!dest) {
1534 return NULL;
1535 }
1536 memcpy(dest, msg, msg->length);
1537
1538 return dest;
1539}
#define ast_malloc(len)
A wrapper for malloc()
Definition: astmm.h:191

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
msgPointer to ast_msg_data structure
attribute_typeOne of ast_msg_data_attribute_type
Returns
The attribute or an empty string ("") if the attribute wasn't set.

Definition at line 1561 of file main/message.c.

1563{
1564 if (!msg) {
1565 ast_assert(msg != NULL);
1566 return "";
1567 }
1568
1569 if (msg->attribute_value_offsets[attribute_type] > ATTRIBUTE_UNSET) {
1570 return msg->buf + msg->attribute_value_offsets[attribute_type];
1571 }
1572
1573 return "";
1574}

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
msgPointer to ast_msg_data structure
Returns
The length of the structure itself plus the dynamically allocated attribute buffer.

Definition at line 1541 of file main/message.c.

1542{
1543 if (!msg) {
1544 ast_assert(msg != NULL);
1545 return 0;
1546 }
1547
1548 return msg->length;
1549}

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
msgPointer to ast_msg_data structure
Returns
The source type field.

Definition at line 1551 of file main/message.c.

1552{
1553 if (!msg) {
1554 ast_assert(msg != NULL);
1556 }
1557
1558 return msg->source;
1559}

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
channelThe channel on which to queue the frame
msgPointer to ast_msg_data structure
Return values
-1Error
0Success

Definition at line 1576 of file main/message.c.

1577{
1578 struct ast_frame f;
1579
1580 if (!channel) {
1581 ast_assert(channel != NULL);
1582 return -1;
1583 }
1584
1585 if (!msg) {
1586 ast_assert(msg != NULL);
1587 return -1;
1588 }
1589
1590 memset(&f, 0, sizeof(f));
1591 f.frametype = AST_FRAME_TEXT_DATA;
1592 f.data.ptr = msg;
1593 f.datalen = msg->length;
1594 return ast_queue_frame(channel, &f);
1595}
int ast_queue_frame(struct ast_channel *chan, struct ast_frame *f)
Queue one or more frames to a channel's frame queue.
Definition: channel.c:1158
@ AST_FRAME_TEXT_DATA
Data structure associated with a single frame of data.

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