Asterisk - The Open Source Telephony Project  GIT-master-8beac82
Data Structures | Enumerations | Functions
message.h File Reference

Out-of-call text message support. More...

Go to the source code of this file.

Data Structures

struct  ast_msg_data_attribute
 
struct  ast_msg_handler
 An external processor of received messages. More...
 
struct  ast_msg_tech
 A message technology. More...
 

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_msgast_msg_alloc (void)
 Allocate a message. More...
 
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...
 
struct ast_msgast_msg_destroy (struct ast_msg *msg)
 Destroy an ast_msg. More...
 
const char * ast_msg_get_body (const struct ast_msg *msg)
 Get the body of a message. More...
 
const char * ast_msg_get_endpoint (const struct ast_msg *msg)
 Retrieve the endpoint associated with this message. More...
 
const char * ast_msg_get_from (const struct ast_msg *msg)
 Retrieve the source of this message. More...
 
const char * ast_msg_get_tech (const struct ast_msg *msg)
 Retrieve the technology associated with this message. More...
 
const char * ast_msg_get_to (const struct ast_msg *msg)
 Retrieve the destination of this message. More...
 
const char * ast_msg_get_var (struct ast_msg *msg, const char *name)
 Get the specified variable on the message. More...
 
int ast_msg_handler_register (const struct ast_msg_handler *handler)
 Register a ast_msg_handler. More...
 
int ast_msg_handler_unregister (const struct ast_msg_handler *handler)
 Unregister a ast_msg_handler. More...
 
int ast_msg_has_destination (const struct ast_msg *msg)
 Determine if a particular message has a destination via some handler. More...
 
int ast_msg_queue (struct ast_msg *msg)
 Queue a message for routing through the dialplan. More...
 
struct ast_msgast_msg_ref (struct ast_msg *msg)
 Bump a msg's ref count. More...
 
int ast_msg_send (struct ast_msg *msg, const char *to, const char *from)
 Send a msg directly to an endpoint. More...
 
int ast_msg_set_body (struct ast_msg *msg, const char *fmt,...)
 Set the 'body' text of a message (in UTF-8) More...
 
int ast_msg_set_context (struct ast_msg *msg, const char *fmt,...)
 Set the dialplan context for this message. More...
 
int ast_msg_set_endpoint (struct ast_msg *msg, const char *fmt,...)
 Set the technology's endpoint associated with this message. More...
 
int ast_msg_set_exten (struct ast_msg *msg, const char *fmt,...)
 Set the dialplan extension for this message. More...
 
int ast_msg_set_from (struct ast_msg *msg, const char *fmt,...)
 Set the 'from' URI of a message. More...
 
int ast_msg_set_tech (struct ast_msg *msg, const char *fmt,...)
 Set the technology associated with this message. More...
 
int ast_msg_set_to (struct ast_msg *msg, const char *fmt,...)
 Set the 'to' URI of a message. More...
 
int ast_msg_set_var (struct ast_msg *msg, const char *name, const char *value)
 Set a variable on the message going to the dialplan. More...
 
int ast_msg_set_var_outbound (struct ast_msg *msg, const char *name, const char *value)
 Set a variable on the message being sent to a message tech directly. More...
 
int ast_msg_tech_register (const struct ast_msg_tech *tech)
 Register a message technology. More...
 
int ast_msg_tech_unregister (const struct ast_msg_tech *tech)
 Unregister a message technology. More...
 
void ast_msg_var_iterator_destroy (struct ast_msg_var_iterator *iter)
 Destroy a message variable iterator. More...
 
struct ast_msg_var_iteratorast_msg_var_iterator_init (const struct ast_msg *msg)
 Create a new message variable iterator. More...
 
int ast_msg_var_iterator_next (const struct ast_msg *msg, struct ast_msg_var_iterator *iter, const char **name, const char **value)
 Get the next variable name and value that is set for sending outbound. More...
 
int ast_msg_var_iterator_next_received (const struct ast_msg *msg, struct ast_msg_var_iterator *iter, const char **name, const char **value)
 Get the next variable name and value that was set on a received message. More...
 
void ast_msg_var_unref_current (struct ast_msg_var_iterator *iter)
 Unref a message var from inside an iterator loop. More...
 

Detailed Description

Out-of-call text message support.

Author
Russell Bryant russe.nosp@m.ll@d.nosp@m.igium.nosp@m..com

The purpose of this API is to provide support for text messages that are not session based. The messages are passed into the Asterisk core to be routed through the dialplan or another interface and potentially sent back out through a message technology that has been registered through this API.

Definition in file message.h.

Function Documentation

◆ ast_msg_alloc()

struct ast_msg* ast_msg_alloc ( void  )

Allocate a message.

Allocate a message for the purposes of passing it into the Asterisk core to be routed through the dialplan. If ast_msg_queue() is not called, this message must be destroyed using ast_msg_destroy(). Otherwise, the message core code will take care of it.

Returns
A message object. This function will return NULL if an allocation error occurs.

Definition at line 432 of file message.c.

References ao2_alloc, AO2_ALLOC_OPT_LOCK_MUTEX, ao2_container_alloc_list, ao2_ref, ast_string_field_init, ast_string_field_set, context, msg_data::msg, msg_data_cmp_fn(), msg_destructor(), NULL, and ast_msg::vars.

Referenced by action_messagesend(), AST_TEST_DEFINE(), module_on_rx_request(), msg_datastore_find_or_create(), receive_message(), send_message(), and xmpp_pak_message().

433 {
434  struct ast_msg *msg;
435 
436  if (!(msg = ao2_alloc(sizeof(*msg), msg_destructor))) {
437  return NULL;
438  }
439 
440  if (ast_string_field_init(msg, 128)) {
441  ao2_ref(msg, -1);
442  return NULL;
443  }
444 
447  if (!msg->vars) {
448  ao2_ref(msg, -1);
449  return NULL;
450  }
451  ast_string_field_set(msg, context, "default");
452 
453  return msg;
454 }
static int msg_data_cmp_fn(void *obj, void *arg, int flags)
Definition: message.c:412
#define ao2_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn)
Definition: astobj2.h:1335
#define NULL
Definition: resample.c:96
static void msg_destructor(void *obj)
Definition: message.c:424
struct ao2_container * vars
Definition: message.c:265
#define ast_string_field_init(x, size)
Initialize a field pool and fields.
Definition: stringfields.h:353
#define ao2_ref(o, delta)
Definition: astobj2.h:464
#define ao2_alloc(data_size, destructor_fn)
Definition: astobj2.h:411
A message.
Definition: message.c:247
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:120
#define ast_string_field_set(x, field, data)
Set a field to a simple string value.
Definition: stringfields.h:514

◆ ast_msg_destroy()

struct ast_msg* ast_msg_destroy ( struct ast_msg msg)

Destroy an ast_msg.

This should only be called on a message if it was not passed on to ast_msg_queue().

Returns
NULL, always.

Definition at line 462 of file message.c.

References ao2_ref, and NULL.

Referenced by ast_msg_safe_destroy(), module_on_rx_request(), msg_data_destroy(), receive_message(), send_message(), and xmpp_pak_message().

463 {
464  ao2_ref(msg, -1);
465  return NULL;
466 }
#define NULL
Definition: resample.c:96
#define ao2_ref(o, delta)
Definition: astobj2.h:464

◆ ast_msg_get_body()

const char* ast_msg_get_body ( const struct ast_msg msg)

Get the body of a message.

Note
The return value is valid only as long as the ast_message is valid. Hold a reference to the message if you plan on storing the return value.
Returns
The body of the messsage, encoded in UTF-8.

Definition at line 545 of file message.c.

References ast_msg::body.

Referenced by AST_TEST_DEFINE(), msg_send(), msg_to_json(), sip_msg_send(), and xmpp_send_cb().

546 {
547  return msg->body;
548 }
const ast_string_field body
Definition: message.c:263

◆ ast_msg_get_endpoint()

const char* ast_msg_get_endpoint ( const struct ast_msg msg)

Retrieve the endpoint associated with this message.

Since
12.5.0
Parameters
msgThe message to get the endpoint from
Return values
Theendpoint associated with the message
NULLor empty string if the message has no associated endpoint

Definition at line 565 of file message.c.

References ast_msg::endpoint.

Referenced by AST_TEST_DEFINE(), and msg_to_endpoint().

566 {
567  return msg->endpoint;
568 }
const ast_string_field endpoint
Definition: message.c:263

◆ ast_msg_get_from()

const char* ast_msg_get_from ( const struct ast_msg msg)

Retrieve the source of this message.

Since
12.5.0
Parameters
msgThe message to get the soure from
Return values
Thesource of the message
NULLor empty string if the message has no source

Definition at line 550 of file message.c.

References ast_msg::from.

Referenced by AST_TEST_DEFINE(), msg_send(), and msg_to_json().

551 {
552  return msg->from;
553 }
const ast_string_field from
Definition: message.c:263

◆ ast_msg_get_tech()

const char* ast_msg_get_tech ( const struct ast_msg msg)

Retrieve the technology associated with this message.

Since
12.5.0
Parameters
msgThe message to get the technology from
Return values
Thetechnology of the message
NULLor empty string if the message has no associated technology

Definition at line 560 of file message.c.

References ast_msg::tech.

Referenced by AST_TEST_DEFINE(), and msg_to_endpoint().

561 {
562  return msg->tech;
563 }
const ast_string_field tech
Definition: message.c:263

◆ ast_msg_get_to()

const char* ast_msg_get_to ( const struct ast_msg msg)

Retrieve the destination of this message.

Since
12.5.0
Parameters
msgThe message to get the destination from
Return values
Thedestination of the message
NULLor empty string if the message has no destination

Definition at line 555 of file message.c.

References ast_msg::to.

Referenced by AST_TEST_DEFINE(), msg_send(), msg_to_json(), and test_msg_has_destination_cb().

556 {
557  return msg->to;
558 }
const ast_string_field to
Definition: message.c:263

◆ ast_msg_get_var()

const char* ast_msg_get_var ( struct ast_msg msg,
const char *  name 
)

Get the specified variable on the message.

Note
The return value is valid only as long as the ast_message is valid. Hold a reference to the message if you plan on storing the return value. Do re-set the same message var name while holding a pointer to the result of this function.
Returns
The value associated with variable "name". NULL if variable not found.

Definition at line 634 of file message.c.

References ao2_ref, msg_data_find(), NULL, msg_data::value, and ast_msg::vars.

Referenced by AST_TEST_DEFINE(), msg_data_func_read(), and update_content_type().

635 {
636  struct msg_data *data;
637  const char *val = NULL;
638 
639  if (!(data = msg_data_find(msg->vars, name))) {
640  return NULL;
641  }
642 
643  /* Yep, this definitely looks like val would be a dangling pointer
644  * after the ref count is decremented. As long as the message structure
645  * is used in a thread safe manner, this will not be the case though.
646  * The ast_msg holds a reference to this object in the msg->vars container. */
647  val = data->value;
648  ao2_ref(data, -1);
649 
650  return val;
651 }
static const char name[]
Definition: format_mp3.c:68
Definition: ast_expr2.c:325
#define NULL
Definition: resample.c:96
struct ao2_container * vars
Definition: message.c:265
static struct msg_data * msg_data_find(struct ao2_container *vars, const char *name)
Definition: message.c:586
#define ao2_ref(o, delta)
Definition: astobj2.h:464
const ast_string_field value
Definition: message.c:238

◆ ast_msg_handler_register()

int ast_msg_handler_register ( const struct ast_msg_handler handler)

Register a ast_msg_handler.

Since
12.5.0
Parameters
handlerThe handler to register
Return values
0Success
non-zeroError

Definition at line 1656 of file message.c.

References ast_log, ast_rwlock_unlock, ast_rwlock_wrlock, AST_VECTOR_APPEND, ast_verb, LOG_ERROR, match(), msg_handler_find_by_tech_name(), and ast_msg_handler::name.

Referenced by ast_msg_init(), AST_TEST_DEFINE(), and messaging_init().

1657 {
1658  const struct ast_msg_handler *match;
1659 
1660  ast_rwlock_wrlock(&msg_handlers_lock);
1661 
1662  match = msg_handler_find_by_tech_name(handler->name);
1663  if (match) {
1664  ast_log(LOG_ERROR, "Message handler already registered for '%s'\n",
1665  handler->name);
1666  ast_rwlock_unlock(&msg_handlers_lock);
1667  return -1;
1668  }
1669 
1670  if (AST_VECTOR_APPEND(&msg_handlers, handler)) {
1671  ast_log(LOG_ERROR, "Failed to register message handler for '%s'\n",
1672  handler->name);
1673  ast_rwlock_unlock(&msg_handlers_lock);
1674  return -1;
1675  }
1676  ast_verb(2, "Message handler '%s' registered.\n", handler->name);
1677 
1678  ast_rwlock_unlock(&msg_handlers_lock);
1679 
1680  return 0;
1681 
1682 }
An external processor of received messages.
Definition: message.h:98
#define AST_VECTOR_APPEND(vec, elem)
Append an element to a vector, growing the vector if needed.
Definition: vector.h:256
static int match(struct ast_sockaddr *addr, unsigned short callno, unsigned short dcallno, const struct chan_iax2_pvt *cur, int check_dcallno)
Definition: chan_iax2.c:2316
#define ast_rwlock_unlock(a)
Definition: lock.h:232
#define ast_verb(level,...)
Definition: logger.h:463
#define ast_log
Definition: astobj2.c:42
#define LOG_ERROR
Definition: logger.h:285
const char * name
Name of the message handler.
Definition: message.h:102
#define ast_rwlock_wrlock(a)
Definition: lock.h:234
static const struct ast_msg_handler * msg_handler_find_by_tech_name(const char *tech_name)
Definition: message.c:1221

◆ ast_msg_handler_unregister()

int ast_msg_handler_unregister ( const struct ast_msg_handler handler)

Unregister a ast_msg_handler.

Since
12.5.0
Parameters
handlerThe handler to unregister
Return values
0Success
non-zeroError

Definition at line 1698 of file message.c.

References ast_log, ast_rwlock_unlock, ast_rwlock_wrlock, AST_VECTOR_ELEM_CLEANUP_NOOP, AST_VECTOR_REMOVE_CMP_UNORDERED, ast_verb, LOG_ERROR, match(), msg_handler_cmp(), and ast_msg_handler::name.

Referenced by AST_TEST_DEFINE(), message_shutdown(), and messaging_cleanup().

1699 {
1700  int match;
1701 
1702  ast_rwlock_wrlock(&msg_handlers_lock);
1703  match = AST_VECTOR_REMOVE_CMP_UNORDERED(&msg_handlers, handler, msg_handler_cmp,
1705  ast_rwlock_unlock(&msg_handlers_lock);
1706 
1707  if (match) {
1708  ast_log(LOG_ERROR, "No '%s' message handler found.\n", handler->name);
1709  return -1;
1710  }
1711 
1712  ast_verb(3, "Message handler '%s' unregistered.\n", handler->name);
1713  return 0;
1714 }
#define AST_VECTOR_REMOVE_CMP_UNORDERED(vec, value, cmp, cleanup)
Remove an element from a vector that matches the given comparison.
Definition: vector.h:488
static int match(struct ast_sockaddr *addr, unsigned short callno, unsigned short dcallno, const struct chan_iax2_pvt *cur, int check_dcallno)
Definition: chan_iax2.c:2316
#define ast_rwlock_unlock(a)
Definition: lock.h:232
#define ast_verb(level,...)
Definition: logger.h:463
#define ast_log
Definition: astobj2.c:42
#define AST_VECTOR_ELEM_CLEANUP_NOOP(elem)
Vector element cleanup that does nothing.
Definition: vector.h:573
#define LOG_ERROR
Definition: logger.h:285
static int msg_handler_cmp(const struct ast_msg_handler *vec_elem, const struct ast_msg_handler *srch)
Comparison callback for ast_msg_handler vector removal.
Definition: message.c:1693
const char * name
Name of the message handler.
Definition: message.h:102
#define ast_rwlock_wrlock(a)
Definition: lock.h:234

◆ ast_msg_has_destination()

int ast_msg_has_destination ( const struct ast_msg msg)

Determine if a particular message has a destination via some handler.

Since
12.5.0
Parameters
msgThe message to check
Return values
0if the message has no handler that can find a destination
1if the message has a handler that can find a destination

Definition at line 951 of file message.c.

References ast_debug, ast_rwlock_rdlock, ast_rwlock_unlock, AST_VECTOR_GET, AST_VECTOR_SIZE, handler(), ast_msg_handler::has_destination, ast_msg_handler::name, and result.

Referenced by AST_TEST_DEFINE(), module_on_rx_request(), and receive_message().

952 {
953  int i;
954  int result = 0;
955 
956  ast_rwlock_rdlock(&msg_handlers_lock);
957  for (i = 0; i < AST_VECTOR_SIZE(&msg_handlers); i++) {
958  const struct ast_msg_handler *handler = AST_VECTOR_GET(&msg_handlers, i);
959 
960  ast_debug(5, "Seeing if %s can handle message\n", handler->name);
961  if (handler->has_destination(msg)) {
962  ast_debug(5, "%s can handle message\n", handler->name);
963  result = 1;
964  break;
965  }
966  }
967  ast_rwlock_unlock(&msg_handlers_lock);
968 
969  return result;
970 }
#define ast_rwlock_rdlock(a)
Definition: lock.h:233
An external processor of received messages.
Definition: message.h:98
int(*const has_destination)(const struct ast_msg *msg)
Return whether or not the message has a valid destination.
Definition: message.h:127
#define ast_rwlock_unlock(a)
Definition: lock.h:232
#define ast_debug(level,...)
Log a DEBUG message.
Definition: logger.h:452
const char * name
Name of the message handler.
Definition: message.h:102
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:682
static void handler(const char *name, int response_code, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
Definition: test_ari.c:59
static PGresult * result
Definition: cel_pgsql.c:88
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:611

◆ ast_msg_queue()

int ast_msg_queue ( struct ast_msg msg)

Queue a message for routing through the dialplan.

Regardless of the return value of this function, this funciton will take care of ensuring that the message object is properly destroyed when needed.

Return values
0message successfully queued
non-zerofailure, message not sent to dialplan

Definition at line 972 of file message.c.

References ao2_ref, ast_taskprocessor_push(), and msg_q_cb().

Referenced by AST_TEST_DEFINE(), module_on_rx_request(), receive_message(), and xmpp_pak_message().

973 {
974  int res;
975  res = ast_taskprocessor_push(msg_q_tp, msg_q_cb, msg);
976  if (res == -1) {
977  ao2_ref(msg, -1);
978  }
979 
980  return res;
981 }
static int msg_q_cb(void *data)
Definition: message.c:921
#define ao2_ref(o, delta)
Definition: astobj2.h:464
int ast_taskprocessor_push(struct ast_taskprocessor *tps, int(*task_exe)(void *datap), void *datap) attribute_warn_unused_result
Push a task into the specified taskprocessor queue and signal the taskprocessor thread.

◆ ast_msg_ref()

struct ast_msg* ast_msg_ref ( struct ast_msg msg)

Bump a msg's ref count.

Definition at line 456 of file message.c.

References ao2_ref, and msg_data::msg.

Referenced by msg_data_create().

457 {
458  ao2_ref(msg, 1);
459  return msg;
460 }
#define ao2_ref(o, delta)
Definition: astobj2.h:464

◆ ast_msg_send()

int ast_msg_send ( struct ast_msg msg,
const char *  to,
const char *  from 
)

Send a msg directly to an endpoint.

Regardless of the return value of this function, this funciton will take care of ensuring that the message object is properly destroyed when needed.

Return values
0message successfully queued to be sent out
non-zerofailure, message not get sent out.

Definition at line 1396 of file message.c.

References ao2_ref, ast_log, ast_rwlock_rdlock, ast_rwlock_unlock, ast_strdupa, ast_strlen_zero(), LOG_ERROR, msg_find_by_tech_name(), ast_msg_tech::msg_send, msg_tech, NULL, S_OR, and strsep().

Referenced by AST_TEST_DEFINE(), and send_message().

1397 {
1398  char *tech_name = NULL;
1399  const struct ast_msg_tech *msg_tech;
1400  int res = -1;
1401 
1402  if (ast_strlen_zero(to)) {
1403  ao2_ref(msg, -1);
1404  return -1;
1405  }
1406 
1407  tech_name = ast_strdupa(to);
1408  tech_name = strsep(&tech_name, ":");
1409 
1411  msg_tech = msg_find_by_tech_name(tech_name);
1412 
1413  if (!msg_tech) {
1414  ast_log(LOG_ERROR, "Unknown message tech: %s\n", tech_name);
1416  return -1;
1417  }
1418 
1419  res = msg_tech->msg_send(msg, S_OR(to, ""), S_OR(from, ""));
1420 
1422 
1423  ao2_ref(msg, -1);
1424 
1425  return res;
1426 }
#define ast_rwlock_rdlock(a)
Definition: lock.h:233
static const struct ast_msg_tech * msg_find_by_tech_name(const char *tech_name)
Definition: message.c:1195
static const struct ast_msg_tech msg_tech
#define NULL
Definition: resample.c:96
#define ast_rwlock_unlock(a)
Definition: lock.h:232
#define ast_log
Definition: astobj2.c:42
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
#define ao2_ref(o, delta)
Definition: astobj2.h:464
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: astmm.h:300
#define LOG_ERROR
Definition: logger.h:285
A message technology.
Definition: message.h:52
static ast_rwlock_t msg_techs_lock
Lock for msg_techs vector.
Definition: message.c:269
char * strsep(char **str, const char *delims)
#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
int(*const msg_send)(const struct ast_msg *msg, const char *to, const char *from)
Send a message.
Definition: message.h:75

◆ ast_msg_set_body()

int ast_msg_set_body ( struct ast_msg msg,
const char *  fmt,
  ... 
)

Set the 'body' text of a message (in UTF-8)

Return values
0success
-1failure

Definition at line 490 of file message.c.

References ast_string_field_build_va, and ast_msg::body.

Referenced by action_messagesend(), AST_TEST_DEFINE(), msg_func_write(), receive_message(), rx_data_to_ast_msg(), send_message(), and xmpp_pak_message().

491 {
492  va_list ap;
493 
494  va_start(ap, fmt);
495  ast_string_field_build_va(msg, body, fmt, ap);
496  va_end(ap);
497 
498  return 0;
499 }
#define ast_string_field_build_va(x, field, fmt, args)
Set a field to a complex (built) value.
Definition: stringfields.h:588

◆ ast_msg_set_context()

int ast_msg_set_context ( struct ast_msg msg,
const char *  fmt,
  ... 
)

Set the dialplan context for this message.

Return values
0success
-1failure

Definition at line 501 of file message.c.

References ast_string_field_build_va, and context.

Referenced by AST_TEST_DEFINE(), receive_message(), rx_data_to_ast_msg(), and xmpp_pak_message().

502 {
503  va_list ap;
504 
505  va_start(ap, fmt);
506  ast_string_field_build_va(msg, context, fmt, ap);
507  va_end(ap);
508 
509  return 0;
510 }
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:120
#define ast_string_field_build_va(x, field, fmt, args)
Set a field to a complex (built) value.
Definition: stringfields.h:588

◆ ast_msg_set_endpoint()

int ast_msg_set_endpoint ( struct ast_msg msg,
const char *  fmt,
  ... 
)

Set the technology's endpoint associated with this message.

Since
12.5.0
Return values
0success
-1failure

Definition at line 534 of file message.c.

References ast_string_field_build_va, and ast_msg::endpoint.

Referenced by AST_TEST_DEFINE(), receive_message(), rx_data_to_ast_msg(), and xmpp_pak_message().

535 {
536  va_list ap;
537 
538  va_start(ap, fmt);
539  ast_string_field_build_va(msg, endpoint, fmt, ap);
540  va_end(ap);
541 
542  return 0;
543 }
#define ast_string_field_build_va(x, field, fmt, args)
Set a field to a complex (built) value.
Definition: stringfields.h:588

◆ ast_msg_set_exten()

int ast_msg_set_exten ( struct ast_msg msg,
const char *  fmt,
  ... 
)

Set the dialplan extension for this message.

Return values
0success
-1failure

Definition at line 512 of file message.c.

References ast_string_field_build_va, and exten.

Referenced by AST_TEST_DEFINE(), receive_message(), and rx_data_to_ast_msg().

513 {
514  va_list ap;
515 
516  va_start(ap, fmt);
517  ast_string_field_build_va(msg, exten, fmt, ap);
518  va_end(ap);
519 
520  return 0;
521 }
static char exten[AST_MAX_EXTENSION]
Definition: chan_alsa.c:122
#define ast_string_field_build_va(x, field, fmt, args)
Set a field to a complex (built) value.
Definition: stringfields.h:588

◆ ast_msg_set_from()

int ast_msg_set_from ( struct ast_msg msg,
const char *  fmt,
  ... 
)

Set the 'from' URI of a message.

Return values
0success
-1failure

Definition at line 479 of file message.c.

References ast_string_field_build_va, and msg_data::from.

Referenced by AST_TEST_DEFINE(), msg_func_write(), receive_message(), rx_data_to_ast_msg(), send_message(), and xmpp_pak_message().

480 {
481  va_list ap;
482 
483  va_start(ap, fmt);
484  ast_string_field_build_va(msg, from, fmt, ap);
485  va_end(ap);
486 
487  return 0;
488 }
#define ast_string_field_build_va(x, field, fmt, args)
Set a field to a complex (built) value.
Definition: stringfields.h:588

◆ ast_msg_set_tech()

int ast_msg_set_tech ( struct ast_msg msg,
const char *  fmt,
  ... 
)

Set the technology associated with this message.

Since
12.5.0
Return values
0success
-1failure

Definition at line 523 of file message.c.

References ast_string_field_build_va, and ast_msg::tech.

Referenced by AST_TEST_DEFINE(), receive_message(), rx_data_to_ast_msg(), and xmpp_pak_message().

524 {
525  va_list ap;
526 
527  va_start(ap, fmt);
528  ast_string_field_build_va(msg, tech, fmt, ap);
529  va_end(ap);
530 
531  return 0;
532 }
#define ast_string_field_build_va(x, field, fmt, args)
Set a field to a complex (built) value.
Definition: stringfields.h:588

◆ ast_msg_set_to()

int ast_msg_set_to ( struct ast_msg msg,
const char *  fmt,
  ... 
)

Set the 'to' URI of a message.

Return values
0success
-1failure

Definition at line 468 of file message.c.

References ast_string_field_build_va, and ast_msg::to.

Referenced by AST_TEST_DEFINE(), msg_func_write(), receive_message(), rx_data_to_ast_msg(), send_message(), and xmpp_pak_message().

469 {
470  va_list ap;
471 
472  va_start(ap, fmt);
473  ast_string_field_build_va(msg, to, fmt, ap);
474  va_end(ap);
475 
476  return 0;
477 }
#define ast_string_field_build_va(x, field, fmt, args)
Set a field to a complex (built) value.
Definition: stringfields.h:588

◆ ast_msg_set_var()

int ast_msg_set_var ( struct ast_msg msg,
const char *  name,
const char *  value 
)

Set a variable on the message going to the dialplan.

Note
Setting a variable that already exists overwrites the existing variable value
Parameters
msg
nameName of variable to set
valueValue of variable to set
Return values
0success
-1failure

Definition at line 629 of file message.c.

References msg_set_var_full().

Referenced by AST_TEST_DEFINE(), headers_to_vars(), receive_message(), rx_data_to_ast_msg(), set_message_vars_from_req(), and xmpp_pak_message().

630 {
631  return msg_set_var_full(msg, name, value, 0);
632 }
static const char name[]
Definition: format_mp3.c:68
int value
Definition: syslog.c:37
static int msg_set_var_full(struct ast_msg *msg, const char *name, const char *value, unsigned int outbound)
Definition: message.c:594

◆ ast_msg_set_var_outbound()

int ast_msg_set_var_outbound ( struct ast_msg msg,
const char *  name,
const char *  value 
)

Set a variable on the message being sent to a message tech directly.

Note
Setting a variable that already exists overwrites the existing variable value
Parameters
msg
nameName of variable to set
valueValue of variable to set
Return values
0success
-1failure

Definition at line 624 of file message.c.

References msg_set_var_full().

Referenced by action_messagesend(), AST_TEST_DEFINE(), msg_data_func_write(), and send_message().

625 {
626  return msg_set_var_full(msg, name, value, 1);
627 }
static const char name[]
Definition: format_mp3.c:68
int value
Definition: syslog.c:37
static int msg_set_var_full(struct ast_msg *msg, const char *name, const char *value, unsigned int outbound)
Definition: message.c:594

◆ ast_msg_tech_register()

int ast_msg_tech_register ( const struct ast_msg_tech tech)

Register a message technology.

Return values
0success
non-zerofailure

Definition at line 1596 of file message.c.

References ast_log, ast_rwlock_unlock, ast_rwlock_wrlock, AST_VECTOR_APPEND, ast_verb, LOG_ERROR, match(), msg_find_by_tech_name(), and ast_msg_tech::name.

Referenced by AST_TEST_DEFINE(), and load_module().

1597 {
1598  const struct ast_msg_tech *match;
1599 
1601 
1602  match = msg_find_by_tech_name(tech->name);
1603  if (match) {
1604  ast_log(LOG_ERROR, "Message technology already registered for '%s'\n",
1605  tech->name);
1607  return -1;
1608  }
1609 
1610  if (AST_VECTOR_APPEND(&msg_techs, tech)) {
1611  ast_log(LOG_ERROR, "Failed to register message technology for '%s'\n",
1612  tech->name);
1614  return -1;
1615  }
1616  ast_verb(3, "Message technology '%s' registered.\n", tech->name);
1617 
1619 
1620  return 0;
1621 }
#define AST_VECTOR_APPEND(vec, elem)
Append an element to a vector, growing the vector if needed.
Definition: vector.h:256
const char *const name
Name of this message technology.
Definition: message.h:61
static const struct ast_msg_tech * msg_find_by_tech_name(const char *tech_name)
Definition: message.c:1195
static int match(struct ast_sockaddr *addr, unsigned short callno, unsigned short dcallno, const struct chan_iax2_pvt *cur, int check_dcallno)
Definition: chan_iax2.c:2316
#define ast_rwlock_unlock(a)
Definition: lock.h:232
#define ast_verb(level,...)
Definition: logger.h:463
#define ast_log
Definition: astobj2.c:42
#define LOG_ERROR
Definition: logger.h:285
A message technology.
Definition: message.h:52
static ast_rwlock_t msg_techs_lock
Lock for msg_techs vector.
Definition: message.c:269
#define ast_rwlock_wrlock(a)
Definition: lock.h:234

◆ ast_msg_tech_unregister()

int ast_msg_tech_unregister ( const struct ast_msg_tech tech)

Unregister a message technology.

Return values
0success
non-zerofailure

Definition at line 1637 of file message.c.

References ast_log, ast_rwlock_unlock, ast_rwlock_wrlock, AST_VECTOR_ELEM_CLEANUP_NOOP, AST_VECTOR_REMOVE_CMP_UNORDERED, ast_verb, LOG_ERROR, match(), msg_tech_cmp(), and ast_msg_tech::name.

Referenced by AST_TEST_DEFINE(), load_module(), and unload_module().

1638 {
1639  int match;
1640 
1642  match = AST_VECTOR_REMOVE_CMP_UNORDERED(&msg_techs, tech, msg_tech_cmp,
1645 
1646  if (match) {
1647  ast_log(LOG_ERROR, "No '%s' message technology found.\n", tech->name);
1648  return -1;
1649  }
1650 
1651  ast_verb(2, "Message technology '%s' unregistered.\n", tech->name);
1652 
1653  return 0;
1654 }
#define AST_VECTOR_REMOVE_CMP_UNORDERED(vec, value, cmp, cleanup)
Remove an element from a vector that matches the given comparison.
Definition: vector.h:488
const char *const name
Name of this message technology.
Definition: message.h:61
static int match(struct ast_sockaddr *addr, unsigned short callno, unsigned short dcallno, const struct chan_iax2_pvt *cur, int check_dcallno)
Definition: chan_iax2.c:2316
#define ast_rwlock_unlock(a)
Definition: lock.h:232
#define ast_verb(level,...)
Definition: logger.h:463
#define ast_log
Definition: astobj2.c:42
#define AST_VECTOR_ELEM_CLEANUP_NOOP(elem)
Vector element cleanup that does nothing.
Definition: vector.h:573
#define LOG_ERROR
Definition: logger.h:285
static ast_rwlock_t msg_techs_lock
Lock for msg_techs vector.
Definition: message.c:269
#define ast_rwlock_wrlock(a)
Definition: lock.h:234
static int msg_tech_cmp(const struct ast_msg_tech *vec_elem, const struct ast_msg_tech *srch)
Comparison callback for ast_msg_tech vector removal.
Definition: message.c:1632

◆ ast_msg_var_iterator_destroy()

void ast_msg_var_iterator_destroy ( struct ast_msg_var_iterator iter)

Destroy a message variable iterator.

Parameters
iterIterator to be destroyed

Definition at line 720 of file message.c.

References ao2_iterator_destroy(), ast_free, ast_msg_var_unref_current(), and ast_msg_var_iterator::iter.

Referenced by AST_TEST_DEFINE(), msg_to_json(), sip_msg_send(), and vars_to_headers().

721 {
722  if (iter) {
723  ao2_iterator_destroy(&iter->iter);
725  ast_free(iter);
726  }
727 }
struct ao2_iterator iter
Definition: message.c:654
void ao2_iterator_destroy(struct ao2_iterator *iter)
Destroy a container iterator.
void ast_msg_var_unref_current(struct ast_msg_var_iterator *iter)
Unref a message var from inside an iterator loop.
Definition: message.c:714
#define ast_free(a)
Definition: astmm.h:182

◆ ast_msg_var_iterator_init()

struct ast_msg_var_iterator* ast_msg_var_iterator_init ( const struct ast_msg msg)

Create a new message variable iterator.

Parameters
msgA message whose variables are to be iterated over
Returns
An opaque pointer to the new iterator

Definition at line 658 of file message.c.

References ao2_iterator_init(), ast_calloc, ast_msg_var_iterator::iter, NULL, and ast_msg::vars.

Referenced by AST_TEST_DEFINE(), msg_to_json(), sip_msg_send(), and vars_to_headers().

659 {
660  struct ast_msg_var_iterator *iter;
661 
662  iter = ast_calloc(1, sizeof(*iter));
663  if (!iter) {
664  return NULL;
665  }
666 
667  iter->iter = ao2_iterator_init(msg->vars, 0);
668 
669  return iter;
670 }
struct ao2_iterator iter
Definition: message.c:654
#define NULL
Definition: resample.c:96
struct ao2_container * vars
Definition: message.c:265
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:204
struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags) attribute_warn_unused_result
Create an iterator for a container.

◆ ast_msg_var_iterator_next()

int ast_msg_var_iterator_next ( const struct ast_msg msg,
struct ast_msg_var_iterator iter,
const char **  name,
const char **  value 
)

Get the next variable name and value that is set for sending outbound.

Parameters
msgThe message with the variables
iterAn iterator created with ast_msg_var_iterator_init
nameA pointer to the name result pointer
valueA pointer to the value result pointer
Return values
0No more entries
1Valid entry

Definition at line 703 of file message.c.

References ast_msg_var_iterator_get_next().

Referenced by AST_TEST_DEFINE(), sip_msg_send(), and vars_to_headers().

704 {
705  return ast_msg_var_iterator_get_next(msg, iter, name, value, 1);
706 }
static const char name[]
Definition: format_mp3.c:68
int value
Definition: syslog.c:37
static int ast_msg_var_iterator_get_next(const struct ast_msg *msg, struct ast_msg_var_iterator *iter, const char **name, const char **value, unsigned int send)
Definition: message.c:672

◆ ast_msg_var_iterator_next_received()

int ast_msg_var_iterator_next_received ( const struct ast_msg msg,
struct ast_msg_var_iterator iter,
const char **  name,
const char **  value 
)

Get the next variable name and value that was set on a received message.

Parameters
msgThe message with the variables
iterAn iterator created with ast_msg_var_iterator_init
nameA pointer to the name result pointer
valueA pointer to the value result pointer
Return values
0No more entries
1Valid entry

Definition at line 708 of file message.c.

References ast_msg_var_iterator_get_next().

Referenced by msg_to_json().

710 {
711  return ast_msg_var_iterator_get_next(msg, iter, name, value, 0);
712 }
static const char name[]
Definition: format_mp3.c:68
int value
Definition: syslog.c:37
static int ast_msg_var_iterator_get_next(const struct ast_msg *msg, struct ast_msg_var_iterator *iter, const char **name, const char **value, unsigned int send)
Definition: message.c:672

◆ ast_msg_var_unref_current()

void ast_msg_var_unref_current ( struct ast_msg_var_iterator iter)

Unref a message var from inside an iterator loop.

Definition at line 714 of file message.c.

References ao2_cleanup, ast_msg_var_iterator::current_used, and NULL.

Referenced by ast_msg_var_iterator_destroy(), AST_TEST_DEFINE(), msg_to_json(), sip_msg_send(), and vars_to_headers().

715 {
716  ao2_cleanup(iter->current_used);
717  iter->current_used = NULL;
718 }
#define NULL
Definition: resample.c:96
#define ao2_cleanup(obj)
Definition: astobj2.h:1958
struct msg_data * current_used
Definition: message.c:655