res_pjsip_outbound_publish.h File Reference

#include "asterisk/linkedlists.h"

Include dependency graph for res_pjsip_outbound_publish.h:

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

Go to the source code of this file.

Data Structures
struct	ast_sip_event_publisher_handler
	Callbacks that event publisher handlers will define. More...

Functions
int	ast_sip_publish_client_add_datastore (struct ast_sip_outbound_publish_client *client, struct ast_datastore *datastore)
	Add a datastore to a SIP event publisher. More...
struct ast_datastore *	ast_sip_publish_client_alloc_datastore (const struct ast_datastore_info *info, const char *uid)
	Alternative for ast_datastore_alloc() More...
struct ast_sip_outbound_publish_client *	ast_sip_publish_client_get (const char *name)
	Find a publish client using its name. More...
struct ast_datastore *	ast_sip_publish_client_get_datastore (struct ast_sip_outbound_publish_client *client, const char *name)
	Retrieve an event publisher datastore. More...
const char *	ast_sip_publish_client_get_from_uri (struct ast_sip_outbound_publish_client *client)
	Get the From URI the client will use. More...
const char *	ast_sip_publish_client_get_to_uri (struct ast_sip_outbound_publish_client *client)
	Get the To URI the client will use. More...
const char *	ast_sip_publish_client_get_user_from_uri (struct ast_sip_outbound_publish_client *client, const char *user, char *uri, size_t size)
	Get the From URI the client will use for a specific user. More...
const char *	ast_sip_publish_client_get_user_to_uri (struct ast_sip_outbound_publish_client *client, const char *user, char *uri, size_t size)
	Get the To URI the client will use for a specific user. More...
void	ast_sip_publish_client_remove (struct ast_sip_outbound_publish_client *client, const char *user)
	Remove the user from the client (stopping it from publishing) More...
void	ast_sip_publish_client_remove_datastore (struct ast_sip_outbound_publish_client *client, const char *name)
	Remove a publication datastore from an event publisher. More...
int	ast_sip_publish_client_send (struct ast_sip_outbound_publish_client *client, const struct ast_sip_body *body)
	Send an outgoing PUBLISH message using a client. More...
int	ast_sip_publish_client_user_send (struct ast_sip_outbound_publish_client *client, const char *user, const struct ast_sip_body *body)
	Send an outgoing PUBLISH message based on the user. More...
int	ast_sip_register_event_publisher_handler (struct ast_sip_event_publisher_handler *handler)
	Register an event publisher handler. More...
void	ast_sip_unregister_event_publisher_handler (struct ast_sip_event_publisher_handler *handler)
	Unregister a publish handler. More...

Function Documentation

ast_sip_publish_client_add_datastore()

int ast_sip_publish_client_add_datastore	(	struct ast_sip_outbound_publish_client *	client,
		struct ast_datastore *	datastore
	)

Add a datastore to a SIP event publisher.

Note that SIP uses reference counted datastores. The datastore passed into this function must have been allocated using ao2_alloc() or there will be serious problems.

Parameters

client	The publication client to add the datastore to
datastore	The datastore to be added to the subscription

Return values

0	Success
-1	Failure

Definition at line 724 of file res_pjsip_outbound_publish.c.

References ao2_link, ast_assert, ast_strlen_zero, ast_sip_outbound_publish_client::datastores, ast_datastore::info, NULL, and ast_datastore::uid.

Referenced by asterisk_start_devicestate_publishing(), and asterisk_start_mwi_publishing().

{
   ast_assert(datastore != NULL);
   ast_assert(datastore->info != NULL);
   ast_assert(!ast_strlen_zero(datastore->uid));

   if (!ao2_link(client->datastores, datastore)) {
      return -1;
   }
   return 0;
}

ast_sip_publish_client_alloc_datastore()

struct ast_datastore* ast_sip_publish_client_alloc_datastore	(	const struct ast_datastore_info *	info,
		const char *	uid
	)

Alternative for ast_datastore_alloc()

There are two major differences between this and ast_datastore_alloc() 1) This allocates a refcounted object 2) This will fill in a uid if one is not provided

DO NOT call ast_datastore_free() on a datastore allocated in this way since that function will attempt to free the datastore rather than play nicely with its refcount.

Parameters

info	Callbacks for datastore
uid	Identifier for datastore

Return values

NULL	Failed to allocate datastore
non-NULL	Newly allocated datastore

Definition at line 694 of file res_pjsip_outbound_publish.c.

References ao2_alloc, ao2_cleanup, ao2_ref, ast_strdup, ast_strlen_zero, ast_uuid_generate_str(), AST_UUID_STR_LEN, sip_to_pjsip::info(), NULL, RAII_VAR, sip_outbound_publish_datastore_destroy(), and ast_datastore::uid.

Referenced by asterisk_start_devicestate_publishing(), and asterisk_start_mwi_publishing().

{
   RAII_VAR(struct ast_datastore *, datastore, NULL, ao2_cleanup);
   const char *uid_ptr = uid;
   char uuid_buf[AST_UUID_STR_LEN];

   if (!info) {
      return NULL;
   }

   datastore = ao2_alloc(sizeof(*datastore), sip_outbound_publish_datastore_destroy);
   if (!datastore) {
      return NULL;
   }

   datastore->info = info;
   if (ast_strlen_zero(uid)) {
      /* They didn't provide an ID so we'll provide one ourself */
      uid_ptr = ast_uuid_generate_str(uuid_buf, sizeof(uuid_buf));
   }

   datastore->uid = ast_strdup(uid_ptr);
   if (!datastore->uid) {
      return NULL;
   }

   ao2_ref(datastore, +1);
   return datastore;
}

ast_sip_publish_client_get()

struct ast_sip_outbound_publish_client* ast_sip_publish_client_get

(

const char *

name

)

Find a publish client using its name.

Parameters

name	The name of the publish client

Return values

NULL	failure
non-NULL	success

Note

The publish client is returned with its reference count increased and must be released using ao2_cleanup.

Definition at line 528 of file res_pjsip_outbound_publish.c.

References ao2_ref, ast_sip_outbound_publish_state::client, NULL, and sip_publish_state_get().

Referenced by asterisk_publication_devicestate_refresh(), asterisk_publication_mwi_refresh(), and send_refresh_cb().

{
   struct ast_sip_outbound_publish_state *state = sip_publish_state_get(name);

   if (!state) {
      return NULL;
   }

   ao2_ref(state->client, +1);
   ao2_ref(state, -1);
   return state->client;
}

ast_sip_publish_client_get_datastore()

struct ast_datastore* ast_sip_publish_client_get_datastore	(	struct ast_sip_outbound_publish_client *	client,
		const char *	name
	)

Retrieve an event publisher datastore.

The datastore retrieved will have its reference count incremented. When the caller is done with the datastore, the reference counted needs to be decremented using ao2_ref().

Parameters

client	The publication client from which to retrieve the datastore
name	The name of the datastore to retrieve

Return values

NULL	Failed to find the specified datastore
non-NULL	The specified datastore

Definition at line 737 of file res_pjsip_outbound_publish.c.

References ao2_find, ast_sip_outbound_publish_client::datastores, and OBJ_SEARCH_KEY.

Referenced by asterisk_publication_devicestate_refresh(), asterisk_publication_mwi_refresh(), asterisk_stop_devicestate_publishing(), and asterisk_stop_mwi_publishing().

{
   return ao2_find(client->datastores, name, OBJ_SEARCH_KEY);
}

ast_sip_publish_client_get_from_uri()

const char* ast_sip_publish_client_get_from_uri

(

struct ast_sip_outbound_publish_client *

client

)

Get the From URI the client will use.

Since

14.0.0

Parameters

client

The publication client to get the From URI

Return values

From-uri	on success
Empty-string	on failure

Definition at line 541 of file res_pjsip_outbound_publish.c.

References sip_outbound_publisher::client, ast_sip_outbound_publish::from_uri, ast_sip_outbound_publish_client::publish, publish, S_OR, ast_sip_outbound_publish::server_uri, and sip_outbound_publish_client_add_publisher().

{
   struct ast_sip_outbound_publish *publish = client->publish;

   return S_OR(publish->from_uri, S_OR(publish->server_uri, ""));
}

ast_sip_publish_client_get_to_uri()

const char* ast_sip_publish_client_get_to_uri

(

struct ast_sip_outbound_publish_client *

client

)

Get the To URI the client will use.

Since

14.0.0

Parameters

client

The publication client to get the To URI

Return values

From-uri	on success
Empty-string	on failure

Definition at line 591 of file res_pjsip_outbound_publish.c.

References ast_sip_outbound_publish_client::publish, publish, S_OR, ast_sip_outbound_publish::server_uri, and ast_sip_outbound_publish::to_uri.

{
   struct ast_sip_outbound_publish *publish = client->publish;

   return S_OR(publish->to_uri, S_OR(publish->server_uri, ""));
}

ast_sip_publish_client_get_user_from_uri()

const char* ast_sip_publish_client_get_user_from_uri	(	struct ast_sip_outbound_publish_client *	client,
		const char *	user,
		char *	uri,
		size_t	size
	)

Get the From URI the client will use for a specific user.

Since

14.0.0

Parameters

client	The publication client to get the From URI of a user
user	The user to retrieve the From URI for
uri	A buffer to place the URI into
size	The size of the buffer

Return values

From-uri	on success
Empty-string	on failure

Definition at line 575 of file res_pjsip_outbound_publish.c.

References ao2_ref, ast_copy_string(), sip_outbound_publisher::from_uri, NULL, and sip_outbound_publish_client_get_publisher().

Referenced by exten_state_publisher_cb().

{
   struct sip_outbound_publisher *publisher;

   publisher = sip_outbound_publish_client_get_publisher(client, user);
   if (!publisher) {
      return NULL;
   }

   ast_copy_string(uri, publisher->from_uri, size);
   ao2_ref(publisher, -1);

   return uri;
}

ast_sip_publish_client_get_user_to_uri()

const char* ast_sip_publish_client_get_user_to_uri	(	struct ast_sip_outbound_publish_client *	client,
		const char *	user,
		char *	uri,
		size_t	size
	)

Get the To URI the client will use for a specific user.

Since

14.0.0

Parameters

client	The publication client to get the To URI of a user
user	The user to retrieve the To URI for
uri	A buffer to place the URI into
size	The size of the buffer

Return values

To-uri	on success
Empty-string	on failure

Definition at line 598 of file res_pjsip_outbound_publish.c.

References ao2_ref, ast_copy_string(), NULL, sip_outbound_publish_client_get_publisher(), and sip_outbound_publisher::to_uri.

Referenced by exten_state_publisher_cb().

{
   struct sip_outbound_publisher *publisher;

   publisher = sip_outbound_publish_client_get_publisher(client, user);
   if (!publisher) {
      return NULL;
   }

   ast_copy_string(uri, publisher->to_uri, size);
   ao2_ref(publisher, -1);

   return uri;
}

ast_sip_publish_client_remove()

void ast_sip_publish_client_remove	(	struct ast_sip_outbound_publish_client *	client,
		const char *	user
	)

Remove the user from the client (stopping it from publishing)

Parameters

client	The publication client
user	The user to remove

Definition at line 1125 of file res_pjsip_outbound_publish.c.

References ao2_find, load_lock, lock, OBJ_NODATA, OBJ_SEARCH_KEY, OBJ_UNLINK, ast_sip_outbound_publish_client::publishers, and SCOPED_WRLOCK.

{
   SCOPED_WRLOCK(lock, &load_lock);
   ao2_find(client->publishers, user, OBJ_SEARCH_KEY | OBJ_UNLINK | OBJ_NODATA);
}

ast_sip_publish_client_remove_datastore()

void ast_sip_publish_client_remove_datastore	(	struct ast_sip_outbound_publish_client *	client,
		const char *	name
	)

Remove a publication datastore from an event publisher.

This operation may cause the datastore's free() callback to be called if the reference count reaches zero.

Parameters

client	The publication client to remove the datastore from
name	The name of the datastore to remove

Definition at line 743 of file res_pjsip_outbound_publish.c.

References ao2_find, ast_sip_outbound_publish_client::datastores, OBJ_NODATA, OBJ_SEARCH_KEY, and OBJ_UNLINK.

Referenced by asterisk_start_devicestate_publishing(), asterisk_start_mwi_publishing(), asterisk_stop_devicestate_publishing(), and asterisk_stop_mwi_publishing().

{
   ao2_find(client->datastores, name, OBJ_SEARCH_KEY | OBJ_UNLINK | OBJ_NODATA);
}

ast_sip_publish_client_send()

int ast_sip_publish_client_send	(	struct ast_sip_outbound_publish_client *	client,
		const struct ast_sip_body *	body
	)

Send an outgoing PUBLISH message using a client.

Parameters

client	The publication client to send from
body	An optional body to add to the PUBLISH

Return values

-1	failure
0	success

Definition at line 842 of file res_pjsip_outbound_publish.c.

References ao2_callback_data, lock, OBJ_NODATA, publisher_client_send(), ast_sip_outbound_publish_client::publishers, and SCOPED_AO2LOCK.

Referenced by asterisk_publisher_devstate_cb(), asterisk_publisher_mwistate_cb(), and send_refresh_cb().

{
   SCOPED_AO2LOCK(lock, client);
   int res = 0;

   ao2_callback_data(client->publishers, OBJ_NODATA,
           publisher_client_send, (void *)body, &res);
   return res;
}

ast_sip_publish_client_user_send()

int ast_sip_publish_client_user_send	(	struct ast_sip_outbound_publish_client *	client,
		const char *	user,
		const struct ast_sip_body *	body
	)

Send an outgoing PUBLISH message based on the user.

Parameters

client	The publication client to send from
user	The user to send to
body	An optional body to add to the PUBLISH

Return values

-1	failure
0	success

Definition at line 1109 of file res_pjsip_outbound_publish.c.

References ao2_ref, publisher_client_send(), and sip_outbound_publish_client_get_publisher().

Referenced by exten_state_publisher_cb().

{
   struct sip_outbound_publisher *publisher;
   int res;

   publisher = sip_outbound_publish_client_get_publisher(client, user);
   if (!publisher) {
      return -1;
   }

   publisher_client_send(publisher, (void *)body, &res, 0);
   ao2_ref(publisher, -1);
   return res;
}

ast_sip_register_event_publisher_handler()

int ast_sip_register_event_publisher_handler

(

struct ast_sip_event_publisher_handler *

handler

)

Register an event publisher handler.

Return values

0	Handler was registered successfully
non-zero	Handler was not registered successfully

Definition at line 614 of file res_pjsip_outbound_publish.c.

References ast_log, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_strlen_zero, ast_sip_event_publisher_handler::event_name, find_publisher_handler_for_event_name(), lock, LOG_ERROR, NULL, SCOPED_LOCK, sip_outbound_publish_synchronize(), ast_sip_event_publisher_handler::start_publishing, ast_sip_event_publisher_handler::stop_publishing, and sub_add_handler().

Referenced by load_module().

{
   struct ast_sip_event_publisher_handler *existing;
   SCOPED_LOCK(lock, &publisher_handlers, AST_RWLIST_WRLOCK, AST_RWLIST_UNLOCK);

   if (!handler->start_publishing || !handler->stop_publishing) {
      ast_log(LOG_ERROR, "Handler does not implement required callbacks. Cannot register\n");
      return -1;
   } else if (ast_strlen_zero(handler->event_name)) {
      ast_log(LOG_ERROR, "No event package specified for event publisher handler. Cannot register\n");
      return -1;
   }

   existing = find_publisher_handler_for_event_name(handler->event_name);
   if (existing) {
      ast_log(LOG_ERROR, "Unable to register event publisher handler for event %s. "
            "A handler is already registered\n", handler->event_name);
      return -1;
   }

   sub_add_handler(handler);

   sip_outbound_publish_synchronize(NULL);

   return 0;
}

ast_sip_unregister_event_publisher_handler()

void ast_sip_unregister_event_publisher_handler

(

struct ast_sip_event_publisher_handler *

handler

)

Unregister a publish handler.

Definition at line 641 of file res_pjsip_outbound_publish.c.

References AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, lock, sip_outbound_publish_message::next, SCOPED_LOCK, and sip_outbound_publish_synchronize().

Referenced by load_module(), and unload_module().

{
   struct ast_sip_event_publisher_handler *iter;
   SCOPED_LOCK(lock, &publisher_handlers, AST_RWLIST_WRLOCK, AST_RWLIST_UNLOCK);
   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&publisher_handlers, iter, next) {
      if (handler == iter) {
         AST_RWLIST_REMOVE_CURRENT(next);
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;

   sip_outbound_publish_synchronize(handler);
}