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_id	The ID of the endpoint that we received the message from
json_msg	JSON representation of the text message
pvt	ao2 ref counted pvt passed during registration

Return values

0	the message was handled
non-zero	the 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_name	The name of the Stasis Message Bus API application to subscribe to endpoint
endpoint	The endpoint object to subscribe to
message_received_cb	The callback to call when a message is received
pvt	An ao2 ref counted object that will be passed to the callback.

Return values

0	subscription was successful
-1	subscription 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().

{
   RAII_VAR(struct message_subscription *, sub, NULL, ao2_cleanup);
   struct application_tuple *tuple;

   sub = get_or_create_subscription(endpoint);
   if (!sub) {
      return -1;
   }

   ao2_lock(sub);
   if (is_app_subscribed(sub, app_name)) {
      ao2_unlock(sub);
      return 0;
   }

   tuple = application_tuple_alloc(app_name, callback, pvt);
   if (!tuple) {
      ao2_unlock(sub);
      return -1;
   }
   if (AST_VECTOR_APPEND(&sub->applications, tuple)) {
      ao2_ref(tuple, -1);
      ao2_unlock(sub);
      return -1;
   }
   ao2_unlock(sub);

   ast_debug(3, "App '%s' subscribed to messages from endpoint '%s'\n", app_name, endpoint ? ast_endpoint_get_id(endpoint) : "-- ALL --");
   ast_test_suite_event_notify("StasisMessagingSubscription", "SubState: Subscribed\r\nAppName: %s\r\nToken: %s\r\n",
      app_name, endpoint ? ast_endpoint_get_id(endpoint) : "ALL");

   return 0;
}

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_name	Name of the stasis application to unsubscribe from messaging
endpoint_id	The ID of the endpoint we no longer care about

Return values

0	success
-1	error

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

{
   RAII_VAR(struct message_subscription *, sub, NULL, ao2_cleanup);
   RAII_VAR(struct ast_endpoint *, endpoint, NULL, ao2_cleanup);

   endpoint = ast_endpoint_find_by_id(endpoint_id);
   sub = get_subscription(endpoint);
   if (!sub) {
      return;
   }

   ao2_lock(sub);
   if (!is_app_subscribed(sub, app_name)) {
      ao2_unlock(sub);
      return;
   }

   AST_VECTOR_REMOVE_CMP_UNORDERED(&sub->applications, app_name, application_tuple_cmp, ao2_cleanup);
   if (AST_VECTOR_SIZE(&sub->applications) == 0) {
      if (endpoint && !ast_strlen_zero(ast_endpoint_get_resource(endpoint))) {
         ao2_unlink(endpoint_subscriptions, sub);
      } else {
         ast_rwlock_wrlock(&tech_subscriptions_lock);
         AST_VECTOR_REMOVE_CMP_UNORDERED(&tech_subscriptions, endpoint ? ast_endpoint_get_id(endpoint) : TECH_WILDCARD,
            messaging_subscription_cmp, AST_VECTOR_ELEM_CLEANUP_NOOP);
         ast_rwlock_unlock(&tech_subscriptions_lock);
         ao2_ref(sub, -1); /* Release the reference held by tech_subscriptions */
      }
   }
   ao2_unlock(sub);

   ast_debug(3, "App '%s' unsubscribed to messages from endpoint '%s'\n", app_name, endpoint ? ast_endpoint_get_id(endpoint) : "-- ALL --");
   ast_test_suite_event_notify("StasisMessagingSubscription", "SubState: Unsubscribed\r\nAppName: %s\r\nToken: %s\r\n",
      app_name, endpoint ? ast_endpoint_get_id(endpoint) : "ALL");
}

messaging_cleanup()

int messaging_cleanup

(

void

)

Tidy up the messaging layer.

Return values

0	success
-1	failure

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

{
   ast_msg_handler_unregister(&ari_msg_handler);
   ao2_ref(endpoint_subscriptions, -1);
   AST_VECTOR_FREE(&tech_subscriptions);
   ast_rwlock_destroy(&tech_subscriptions_lock);\

   return 0;
}

messaging_init()

int messaging_init

(

void

)

Initialize the messaging layer.

Return values

0	success
-1	failure

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

{
   endpoint_subscriptions = ao2_t_container_alloc_hash(AO2_ALLOC_OPT_LOCK_RWLOCK, 0,
      ENDPOINTS_NUM_BUCKETS, message_subscription_hash_cb, NULL,
      message_subscription_compare_cb, "Endpoint messaging subscription container creation");
   if (!endpoint_subscriptions) {
      return -1;
   }

   if (AST_VECTOR_INIT(&tech_subscriptions, 4)) {
      ao2_ref(endpoint_subscriptions, -1);
      return -1;
   }

   if (ast_rwlock_init(&tech_subscriptions_lock)) {
      ao2_ref(endpoint_subscriptions, -1);
      AST_VECTOR_FREE(&tech_subscriptions);
      return -1;
   }

   if (ast_msg_handler_register(&ari_msg_handler)) {
      ao2_ref(endpoint_subscriptions, -1);
      AST_VECTOR_FREE(&tech_subscriptions);
      ast_rwlock_destroy(&tech_subscriptions_lock);
      return -1;
   }

   return 0;
}