Asterisk - The Open Source Telephony Project  GIT-master-44aef04
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.

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

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

1383 {
1384  struct ast_msg_data *msg;
1385  size_t len = sizeof(*msg);
1386  size_t i;
1387  size_t current_offset = 0;
1388  enum ast_msg_data_attribute_type attr_type;
1389 
1390  if (!attributes) {
1391  ast_assert(attributes != NULL);
1392  return NULL;
1393  }
1394 
1395  if (!count) {
1396  ast_assert(count > 0);
1397  return NULL;
1398  }
1399 
1400  /* Calculate the length required for the buffer */
1401  for (i=0; i < count; i++) {
1402  if (!attributes[i].value) {
1403  ast_assert(attributes[i].value != NULL);
1404  return NULL;
1405  }
1406  len += (strlen(attributes[i].value) + 1);
1407  }
1408 
1409  msg = ast_calloc(1, len);
1410  if (!msg) {
1411  return NULL;
1412  }
1413  msg->source = source;
1414  msg->length = len;
1415 
1416  /* Mark all of the attributes as unset */
1417  for (attr_type = 0; attr_type < __AST_MSG_DATA_ATTR_LAST; attr_type++) {
1418  msg->attribute_value_offsets[attr_type] = ATTRIBUTE_UNSET;
1419  }
1420 
1421  /* Set the ones we have and increment the offset */
1422  for (i=0; i < count; i++) {
1423  len = (strlen(attributes[i].value) + 1);
1424  ast_copy_string(msg->buf + current_offset, attributes[i].value, len); /* Safe */
1425  msg->attribute_value_offsets[attributes[i].type] = current_offset;
1426  current_offset += len;
1427  }
1428 
1429  return msg;
1430 }
enum ast_msg_data_attribute_type type
Definition: message.h:463
Structure used to transport a message through the frame core.
Definition: message.c:1369
#define ast_assert(a)
Definition: utils.h:650
#define NULL
Definition: resample.c:96
int value
Definition: syslog.c:37
enum ast_msg_data_source_type source
Definition: message.c:1372
int attribute_value_offsets[__AST_MSG_DATA_ATTR_LAST]
Definition: message.c:1374
#define ATTRIBUTE_UNSET
Definition: message.c:1379
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:204
ast_msg_data_attribute_type
Definition: message.h:454
size_t length
Definition: message.c:1371
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:401
char buf[0]
Definition: message.c:1376

◆ 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
sourceThe 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 1432 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().

1434 {
1435  struct ast_msg_data_attribute attrs[] =
1436  {
1437  {
1439  .value = (char *)S_OR(to, ""),
1440  },
1441  {
1442  .type = AST_MSG_DATA_ATTR_FROM,
1443  .value = (char *)S_OR(from, ""),
1444  },
1445  {
1447  .value = (char *)S_OR(content_type, ""),
1448  },
1449  {
1450  .type = AST_MSG_DATA_ATTR_BODY,
1451  .value = (char *)S_OR(body, ""),
1452  },
1453  };
1454 
1455  return ast_msg_data_alloc(source_type, attrs, ARRAY_LEN(attrs));
1456 }
#define ARRAY_LEN(a)
Definition: isdn_lib.c:42
enum ast_msg_data_attribute_type type
Definition: message.h:463
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.
Definition: message.c:1381
#define S_OR(a, b)
returns the equivalent of logic or for strings: first one if not empty, otherwise second one...
Definition: strings.h:79

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

References ast_assert, ast_malloc, length, and NULL.

Referenced by sendtext_data_create().

1459 {
1460  struct ast_msg_data *dest;
1461 
1462  if (!msg) {
1463  ast_assert(msg != NULL);
1464  return NULL;
1465  }
1466 
1467  dest = ast_malloc(msg->length);
1468  if (!dest) {
1469  return NULL;
1470  }
1471  memcpy(dest, msg, msg->length);
1472 
1473  return dest;
1474 }
Structure used to transport a message through the frame core.
Definition: message.c:1369
#define ast_assert(a)
Definition: utils.h:650
#define NULL
Definition: resample.c:96
#define ast_malloc(len)
A wrapper for malloc()
Definition: astmm.h:193
size_t length
Definition: message.c:1371

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

1498 {
1499  if (!msg) {
1500  ast_assert(msg != NULL);
1501  return "";
1502  }
1503 
1504  if (msg->attribute_value_offsets[attribute_type] > ATTRIBUTE_UNSET) {
1505  return msg->buf + msg->attribute_value_offsets[attribute_type];
1506  }
1507 
1508  return "";
1509 }
#define ast_assert(a)
Definition: utils.h:650
#define NULL
Definition: resample.c:96
int attribute_value_offsets[__AST_MSG_DATA_ATTR_LAST]
Definition: message.c:1374
#define ATTRIBUTE_UNSET
Definition: message.c:1379
char buf[0]
Definition: message.c:1376

◆ 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 1476 of file message.c.

References ast_assert, length, and NULL.

Referenced by queue_sendtext_data(), and send_message().

1477 {
1478  if (!msg) {
1479  ast_assert(msg != NULL);
1480  return 0;
1481  }
1482 
1483  return msg->length;
1484 }
#define ast_assert(a)
Definition: utils.h:650
#define NULL
Definition: resample.c:96
size_t length
Definition: message.c:1371

◆ 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 1486 of file message.c.

References ast_assert, AST_MSG_DATA_SOURCE_TYPE_UNKNOWN, NULL, and source.

1487 {
1488  if (!msg) {
1489  ast_assert(msg != NULL);
1491  }
1492 
1493  return msg->source;
1494 }
#define ast_assert(a)
Definition: utils.h:650
#define NULL
Definition: resample.c:96
enum ast_msg_data_source_type source
Definition: message.c:1372

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

1512 {
1513  struct ast_frame f;
1514 
1515  if (!channel) {
1516  ast_assert(channel != NULL);
1517  return -1;
1518  }
1519 
1520  if (!msg) {
1521  ast_assert(msg != NULL);
1522  return -1;
1523  }
1524 
1525  memset(&f, 0, sizeof(f));
1526  f.frametype = AST_FRAME_TEXT_DATA;
1527  f.data.ptr = msg;
1528  f.datalen = msg->length;
1529  return ast_queue_frame(channel, &f);
1530 }
#define ast_assert(a)
Definition: utils.h:650
#define NULL
Definition: resample.c:96
int ast_queue_frame(struct ast_channel *chan, struct ast_frame *f)
Queue one or more frames to a channel&#39;s frame queue.
Definition: channel.c:1135
size_t length
Definition: message.c:1371
Data structure associated with a single frame of data.