Asterisk - The Open Source Telephony Project  21.4.1
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.

Function Documentation

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.

References ast_calloc, ast_copy_string(), attribute_value_offsets, buf, and length.

Referenced by ast_msg_data_alloc2(), and ast_sendtext().

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 }
Structure used to transport a message through the frame core.
int attribute_value_offsets[__AST_MSG_DATA_ATTR_LAST]
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:425
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.

References ast_msg_data_alloc(), and S_OR.

Referenced by queue_sendtext_data().

1499 {
1500  struct ast_msg_data_attribute attrs[] =
1501  {
1502  {
1503  .type = AST_MSG_DATA_ATTR_TO,
1504  .value = (char *)S_OR(to, ""),
1505  },
1506  {
1507  .type = AST_MSG_DATA_ATTR_FROM,
1508  .value = (char *)S_OR(from, ""),
1509  },
1510  {
1511  .type = AST_MSG_DATA_ATTR_CONTENT_TYPE,
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
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.

References ast_malloc, and length.

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 }
Structure used to transport a message through the frame core.
#define ast_malloc(len)
A wrapper for malloc()
Definition: astmm.h:191
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.

References attribute_value_offsets, and buf.

Referenced by ast_bridge_channel_queue_frame(), ast_sendtext_data(), and chan_pjsip_sendtext_data().

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 }
int attribute_value_offsets[__AST_MSG_DATA_ATTR_LAST]
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.

References length.

Referenced by queue_sendtext_data().

1542 {
1543  if (!msg) {
1544  ast_assert(msg != NULL);
1545  return 0;
1546  }
1547 
1548  return msg->length;
1549 }
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);
1555  return AST_MSG_DATA_SOURCE_TYPE_UNKNOWN;
1556  }
1557 
1558  return msg->source;
1559 }
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.

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

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:1139
Data structure associated with a single frame of data.