Asterisk - The Open Source Telephony Project  18.5.0
Typedefs | Functions
messaging.h File Reference

Stasis out-of-call text message support. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef int(* message_received_cb) (const char *endpoint_id, struct ast_json *json_msg, void *pvt)
 Callback handler for when a message is received from the core. More...
 

Functions

int messaging_app_subscribe_endpoint (const char *app_name, struct ast_endpoint *endpoint, message_received_cb callback, void *pvt)
 Subscribe an application to an endpoint for messages. More...
 
void messaging_app_unsubscribe_endpoint (const char *app_name, const char *endpoint_id)
 Subscribe for messages from a particular endpoint. More...
 
int messaging_cleanup (void)
 Tidy up the messaging layer. More...
 
int messaging_init (void)
 Initialize the messaging layer. More...
 

Detailed Description

Stasis out-of-call text message support.

Author
Matt Jordan mjord.nosp@m.an@d.nosp@m.igium.nosp@m..com
Since
12.4.0

Definition in file messaging.h.

Typedef Documentation

◆ message_received_cb

typedef int(* message_received_cb) (const char *endpoint_id, struct ast_json *json_msg, void *pvt)

Callback handler for when a message is received from the core.

Parameters
endpoint_idThe ID of the endpoint that we received the message from
json_msgJSON representation of the text message
pvtao2 ref counted pvt passed during registration
Return values
0the message was handled
non-zerothe message was not handled

Definition at line 41 of file messaging.h.

Function Documentation

◆ messaging_app_subscribe_endpoint()

int messaging_app_subscribe_endpoint ( const char *  app_name,
struct ast_endpoint endpoint,
message_received_cb  callback,
void *  pvt 
)

Subscribe an application to an endpoint for messages.

Parameters
app_nameThe name of the Stasis Message Bus API application to subscribe to endpoint
endpointThe endpoint object to subscribe to
message_received_cbThe callback to call when a message is received
pvtAn ao2 ref counted object that will be passed to the callback.
Return values
0subscription was successful
-1subscription failed

Definition at line 493 of file messaging.c.

References ao2_cleanup, ao2_lock, ao2_ref, ao2_unlock, application_tuple_alloc(), ast_debug, ast_endpoint_get_id(), ast_test_suite_event_notify, AST_VECTOR_APPEND, get_or_create_subscription(), is_app_subscribed(), NULL, RAII_VAR, and sub.

Referenced by app_subscribe_endpoint().

494 {
496  struct application_tuple *tuple;
497 
498  sub = get_or_create_subscription(endpoint);
499  if (!sub) {
500  return -1;
501  }
502 
503  ao2_lock(sub);
505  ao2_unlock(sub);
506  return 0;
507  }
508 
510  if (!tuple) {
511  ao2_unlock(sub);
512  return -1;
513  }
514  if (AST_VECTOR_APPEND(&sub->applications, tuple)) {
515  ao2_ref(tuple, -1);
516  ao2_unlock(sub);
517  return -1;
518  }
519  ao2_unlock(sub);
520 
521  ast_debug(3, "App '%s' subscribed to messages from endpoint '%s'\n", app_name, endpoint ? ast_endpoint_get_id(endpoint) : "-- ALL --");
522  ast_test_suite_event_notify("StasisMessagingSubscription", "SubState: Subscribed\r\nAppName: %s\r\nToken: %s\r\n",
523  app_name, endpoint ? ast_endpoint_get_id(endpoint) : "ALL");
524 
525  return 0;
526 }
message_received_cb callback
Definition: messaging.c:53
#define AST_VECTOR_APPEND(vec, elem)
Append an element to a vector, growing the vector if needed.
Definition: vector.h:256
Storage object for an application.
Definition: messaging.c:49
#define ao2_unlock(a)
Definition: astobj2.h:730
#define NULL
Definition: resample.c:96
#define ast_debug(level,...)
Log a DEBUG message.
Definition: logger.h:452
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:911
#define ao2_ref(o, delta)
Definition: astobj2.h:464
#define ao2_lock(a)
Definition: astobj2.h:718
#define ast_test_suite_event_notify(s, f,...)
Definition: test.h:196
static struct message_subscription * get_or_create_subscription(struct ast_endpoint *endpoint)
Definition: messaging.c:459
const char * app_name(struct ast_app *app)
Definition: pbx_app.c:463
A subscription to some endpoint or technology.
Definition: messaging.c:59
static struct application_tuple * application_tuple_alloc(const char *app_name, message_received_cb callback, void *pvt)
Definition: messaging.c:89
#define ao2_cleanup(obj)
Definition: astobj2.h:1958
struct stasis_forward * sub
Definition: res_corosync.c:240
const char * ast_endpoint_get_id(const struct ast_endpoint *endpoint)
Gets the tech/resource id of the given endpoint.
static int is_app_subscribed(struct message_subscription *sub, const char *app_name)
Definition: messaging.c:378

◆ messaging_app_unsubscribe_endpoint()

void messaging_app_unsubscribe_endpoint ( const char *  app_name,
const char *  endpoint_id 
)

Subscribe for messages from a particular endpoint.

Parameters
app_nameName of the stasis application to unsubscribe from messaging
endpoint_idThe ID of the endpoint we no longer care about
Return values
0success
-1error

Definition at line 423 of file messaging.c.

References ao2_cleanup, ao2_lock, ao2_ref, ao2_unlink, ao2_unlock, application_tuple_cmp(), ast_debug, ast_endpoint_find_by_id(), ast_endpoint_get_id(), ast_endpoint_get_resource(), ast_rwlock_unlock, ast_rwlock_wrlock, ast_strlen_zero, ast_test_suite_event_notify, AST_VECTOR_ELEM_CLEANUP_NOOP, AST_VECTOR_REMOVE_CMP_UNORDERED, AST_VECTOR_SIZE, get_subscription(), is_app_subscribed(), messaging_subscription_cmp(), NULL, RAII_VAR, sub, and TECH_WILDCARD.

Referenced by unsubscribe().

424 {
426  RAII_VAR(struct ast_endpoint *, endpoint, NULL, ao2_cleanup);
427 
428  endpoint = ast_endpoint_find_by_id(endpoint_id);
429  sub = get_subscription(endpoint);
430  if (!sub) {
431  return;
432  }
433 
434  ao2_lock(sub);
435  if (!is_app_subscribed(sub, app_name)) {
436  ao2_unlock(sub);
437  return;
438  }
439 
441  if (AST_VECTOR_SIZE(&sub->applications) == 0) {
442  if (endpoint && !ast_strlen_zero(ast_endpoint_get_resource(endpoint))) {
444  } else {
445  ast_rwlock_wrlock(&tech_subscriptions_lock);
446  AST_VECTOR_REMOVE_CMP_UNORDERED(&tech_subscriptions, endpoint ? ast_endpoint_get_id(endpoint) : TECH_WILDCARD,
448  ast_rwlock_unlock(&tech_subscriptions_lock);
449  ao2_ref(sub, -1); /* Release the reference held by tech_subscriptions */
450  }
451  }
452  ao2_unlock(sub);
453 
454  ast_debug(3, "App '%s' unsubscribed to messages from endpoint '%s'\n", app_name, endpoint ? ast_endpoint_get_id(endpoint) : "-- ALL --");
455  ast_test_suite_event_notify("StasisMessagingSubscription", "SubState: Unsubscribed\r\nAppName: %s\r\nToken: %s\r\n",
456  app_name, endpoint ? ast_endpoint_get_id(endpoint) : "ALL");
457 }
static int application_tuple_cmp(struct application_tuple *item, const char *key)
Definition: messaging.c:373
#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
#define TECH_WILDCARD
Subscription to all technologies.
Definition: messaging.c:41
#define ao2_unlock(a)
Definition: astobj2.h:730
struct ast_endpoint * ast_endpoint_find_by_id(const char *id)
Finds the endpoint with the given tech[/resource] id.
#define NULL
Definition: resample.c:96
#define ast_rwlock_unlock(a)
Definition: lock.h:232
const char * ast_endpoint_get_resource(const struct ast_endpoint *endpoint)
Gets the resource name of the given endpoint.
#define ast_strlen_zero(foo)
Definition: strings.h:52
#define ast_debug(level,...)
Log a DEBUG message.
Definition: logger.h:452
static struct ao2_container * endpoint_subscriptions
The subscriptions to endpoints.
Definition: messaging.c:67
#define AST_VECTOR_ELEM_CLEANUP_NOOP(elem)
Vector element cleanup that does nothing.
Definition: vector.h:573
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:911
#define ao2_ref(o, delta)
Definition: astobj2.h:464
#define ao2_lock(a)
Definition: astobj2.h:718
#define ast_test_suite_event_notify(s, f,...)
Definition: test.h:196
#define ao2_unlink(container, obj)
Definition: astobj2.h:1598
const char * app_name(struct ast_app *app)
Definition: pbx_app.c:463
A subscription to some endpoint or technology.
Definition: messaging.c:59
static struct message_subscription * get_subscription(struct ast_endpoint *endpoint)
Definition: messaging.c:394
#define ast_rwlock_wrlock(a)
Definition: lock.h:234
#define ao2_cleanup(obj)
Definition: astobj2.h:1958
struct stasis_forward * sub
Definition: res_corosync.c:240
static int messaging_subscription_cmp(struct message_subscription *sub, const char *key)
Definition: messaging.c:368
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:611
const char * ast_endpoint_get_id(const struct ast_endpoint *endpoint)
Gets the tech/resource id of the given endpoint.
static int is_app_subscribed(struct message_subscription *sub, const char *app_name)
Definition: messaging.c:378

◆ messaging_cleanup()

int messaging_cleanup ( void  )

Tidy up the messaging layer.

Return values
0success
-1failure

Definition at line 529 of file messaging.c.

References ao2_ref, ast_msg_handler_unregister(), ast_rwlock_destroy, and AST_VECTOR_FREE.

Referenced by unload_module().

530 {
533  AST_VECTOR_FREE(&tech_subscriptions);
534  ast_rwlock_destroy(&tech_subscriptions_lock);\
535 
536  return 0;
537 }
#define AST_VECTOR_FREE(vec)
Deallocates this vector.
Definition: vector.h:174
int ast_msg_handler_unregister(const struct ast_msg_handler *handler)
Unregister a ast_msg_handler.
Definition: message.c:1671
#define ast_rwlock_destroy(rwlock)
Definition: lock.h:231
static struct ao2_container * endpoint_subscriptions
The subscriptions to endpoints.
Definition: messaging.c:67
#define ao2_ref(o, delta)
Definition: astobj2.h:464
struct ast_msg_handler ari_msg_handler
Definition: messaging.c:362

◆ messaging_init()

int messaging_init ( void  )

Initialize the messaging layer.

Return values
0success
-1failure

Definition at line 539 of file messaging.c.

References AO2_ALLOC_OPT_LOCK_RWLOCK, ao2_ref, ao2_t_container_alloc_hash, ast_msg_handler_register(), ast_rwlock_destroy, ast_rwlock_init, AST_VECTOR_FREE, AST_VECTOR_INIT, ENDPOINTS_NUM_BUCKETS, message_subscription_compare_cb(), message_subscription_hash_cb(), and NULL.

Referenced by load_module().

540 {
543  message_subscription_compare_cb, "Endpoint messaging subscription container creation");
544  if (!endpoint_subscriptions) {
545  return -1;
546  }
547 
548  if (AST_VECTOR_INIT(&tech_subscriptions, 4)) {
550  return -1;
551  }
552 
553  if (ast_rwlock_init(&tech_subscriptions_lock)) {
555  AST_VECTOR_FREE(&tech_subscriptions);
556  return -1;
557  }
558 
561  AST_VECTOR_FREE(&tech_subscriptions);
562  ast_rwlock_destroy(&tech_subscriptions_lock);
563  return -1;
564  }
565 
566  return 0;
567 }
#define AST_VECTOR_FREE(vec)
Deallocates this vector.
Definition: vector.h:174
#define ast_rwlock_destroy(rwlock)
Definition: lock.h:231
static int message_subscription_compare_cb(void *obj, void *arg, int flags)
Definition: messaging.c:160
int ast_msg_handler_register(const struct ast_msg_handler *handler)
Register a ast_msg_handler.
Definition: message.c:1629
#define NULL
Definition: resample.c:96
#define AST_VECTOR_INIT(vec, size)
Initialize a vector.
Definition: vector.h:113
static struct ao2_container * endpoint_subscriptions
The subscriptions to endpoints.
Definition: messaging.c:67
#define ao2_ref(o, delta)
Definition: astobj2.h:464
static int message_subscription_hash_cb(const void *obj, const int flags)
Definition: messaging.c:138
struct ast_msg_handler ari_msg_handler
Definition: messaging.c:362
#define ast_rwlock_init(rwlock)
wrapper for rwlock with tracking enabled
Definition: lock.h:222
#define ao2_t_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn, tag)
Allocate and initialize a hash container with the desired number of buckets.
Definition: astobj2.h:1308
#define ENDPOINTS_NUM_BUCKETS
Number of buckets for the endpoint_subscriptions container.
Definition: messaging.c:46