Asterisk - The Open Source Telephony Project GIT-master-d856a3e
Data Structures | Functions
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_datastoreast_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_clientast_sip_publish_client_get (const char *name)
 Find a publish client using its name. More...
 
struct ast_datastoreast_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
clientThe publication client to add the datastore to
datastoreThe datastore to be added to the subscription
Return values
0Success
-1Failure

Definition at line 724 of file res_pjsip_outbound_publish.c.

726{
727 ast_assert(datastore != NULL);
728 ast_assert(datastore->info != NULL);
729 ast_assert(!ast_strlen_zero(datastore->uid));
730
731 if (!ao2_link(client->datastores, datastore)) {
732 return -1;
733 }
734 return 0;
735}
#define ao2_link(container, obj)
Add an object to a container.
Definition: astobj2.h:1532
#define NULL
Definition: resample.c:96
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
const struct ast_datastore_info * info
Definition: datastore.h:67
const char * uid
Definition: datastore.h:65
struct ao2_container * datastores
Publisher datastores set up by handlers.
#define ast_assert(a)
Definition: utils.h:739

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_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
infoCallbacks for datastore
uidIdentifier for datastore
Return values
NULLFailed to allocate datastore
non-NULLNewly allocated datastore

Definition at line 694 of file res_pjsip_outbound_publish.c.

695{
696 RAII_VAR(struct ast_datastore *, datastore, NULL, ao2_cleanup);
697 const char *uid_ptr = uid;
698 char uuid_buf[AST_UUID_STR_LEN];
699
700 if (!info) {
701 return NULL;
702 }
703
704 datastore = ao2_alloc(sizeof(*datastore), sip_outbound_publish_datastore_destroy);
705 if (!datastore) {
706 return NULL;
707 }
708
709 datastore->info = info;
710 if (ast_strlen_zero(uid)) {
711 /* They didn't provide an ID so we'll provide one ourself */
712 uid_ptr = ast_uuid_generate_str(uuid_buf, sizeof(uuid_buf));
713 }
714
715 datastore->uid = ast_strdup(uid_ptr);
716 if (!datastore->uid) {
717 return NULL;
718 }
719
720 ao2_ref(datastore, +1);
721 return datastore;
722}
#define ast_strdup(str)
A wrapper for strdup()
Definition: astmm.h:241
#define ao2_cleanup(obj)
Definition: astobj2.h:1934
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
#define ao2_alloc(data_size, destructor_fn)
Definition: astobj2.h:409
def info(msg)
static void sip_outbound_publish_datastore_destroy(void *obj)
Structure for a data store object.
Definition: datastore.h:64
#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:941
#define AST_UUID_STR_LEN
Definition: uuid.h:27
char * ast_uuid_generate_str(char *buf, size_t size)
Generate a UUID string.
Definition: uuid.c:141

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

◆ 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
nameThe name of the publish client
Return values
NULLfailure
non-NULLsuccess
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.

529{
531
532 if (!state) {
533 return NULL;
534 }
535
536 ao2_ref(state->client, +1);
537 ao2_ref(state, -1);
538 return state->client;
539}
static const char name[]
Definition: format_mp3.c:68
static struct ast_sip_outbound_publish_state * sip_publish_state_get(const char *id)
Outbound publish state information (persists for lifetime of a publish)

References ao2_ref, name, NULL, and sip_publish_state_get().

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

◆ 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
clientThe publication client from which to retrieve the datastore
nameThe name of the datastore to retrieve
Return values
NULLFailed to find the specified datastore
non-NULLThe specified datastore

Definition at line 737 of file res_pjsip_outbound_publish.c.

739{
740 return ao2_find(client->datastores, name, OBJ_SEARCH_KEY);
741}
#define ao2_find(container, arg, flags)
Definition: astobj2.h:1736
@ OBJ_SEARCH_KEY
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101

References ao2_find, ast_sip_outbound_publish_client::datastores, name, and OBJ_SEARCH_KEY.

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

◆ 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
clientThe publication client to get the From URI
Return values
From-urion success
Empty-stringon failure

Definition at line 541 of file res_pjsip_outbound_publish.c.

542{
543 struct ast_sip_outbound_publish *publish = client->publish;
544
545 return S_OR(publish->from_uri, S_OR(publish->server_uri, ""));
546}
unsigned char publish
Definition: res_corosync.c:241
#define S_OR(a, b)
returns the equivalent of logic or for strings: first one if not empty, otherwise second one.
Definition: strings.h:80
struct ast_sip_outbound_publish * publish
Outbound publish information.
Outbound publish information.

References publish, ast_sip_outbound_publish_client::publish, and S_OR.

◆ 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
clientThe publication client to get the To URI
Return values
From-urion success
Empty-stringon failure

Definition at line 591 of file res_pjsip_outbound_publish.c.

592{
593 struct ast_sip_outbound_publish *publish = client->publish;
594
595 return S_OR(publish->to_uri, S_OR(publish->server_uri, ""));
596}

References publish, ast_sip_outbound_publish_client::publish, and S_OR.

◆ 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
clientThe publication client to get the From URI of a user
userThe user to retrieve the From URI for
uriA buffer to place the URI into
sizeThe size of the buffer
Return values
From-urion success
Empty-stringon failure

Definition at line 575 of file res_pjsip_outbound_publish.c.

577{
578 struct sip_outbound_publisher *publisher;
579
581 if (!publisher) {
582 return NULL;
583 }
584
585 ast_copy_string(uri, publisher->from_uri, size);
586 ao2_ref(publisher, -1);
587
588 return uri;
589}
static struct sip_outbound_publisher * sip_outbound_publish_client_get_publisher(struct ast_sip_outbound_publish_client *client, const char *user)
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:425
char * from_uri
The From URI for this specific publisher.
pjsip_publishc * client
Underlying publish client.
structure to hold users read from users.conf

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

Referenced by exten_state_publisher_cb().

◆ 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
clientThe publication client to get the To URI of a user
userThe user to retrieve the To URI for
uriA buffer to place the URI into
sizeThe size of the buffer
Return values
To-urion success
Empty-stringon failure

Definition at line 598 of file res_pjsip_outbound_publish.c.

600{
601 struct sip_outbound_publisher *publisher;
602
604 if (!publisher) {
605 return NULL;
606 }
607
608 ast_copy_string(uri, publisher->to_uri, size);
609 ao2_ref(publisher, -1);
610
611 return uri;
612}
char * to_uri
The To URI for this specific publisher.

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

Referenced by exten_state_publisher_cb().

◆ 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
clientThe publication client
userThe user to remove

Definition at line 1125 of file res_pjsip_outbound_publish.c.

1127{
1130}
ast_mutex_t lock
Definition: app_sla.c:331
@ OBJ_NODATA
Definition: astobj2.h:1044
@ OBJ_UNLINK
Definition: astobj2.h:1039
#define SCOPED_WRLOCK(varname, lock)
scoped lock specialization for write locks
Definition: lock.h:599
static ast_rwlock_t load_lock
Used for locking while loading/reloading.
struct ao2_container * publishers
Container of all the client publishing objects.

References ao2_find, sip_outbound_publisher::client, load_lock, lock, OBJ_NODATA, OBJ_SEARCH_KEY, OBJ_UNLINK, and SCOPED_WRLOCK.

◆ 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
clientThe publication client to remove the datastore from
nameThe 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, name, 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().

◆ 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
clientThe publication client to send from
bodyAn optional body to add to the PUBLISH
Return values
-1failure
0success

Definition at line 842 of file res_pjsip_outbound_publish.c.

844{
845 SCOPED_AO2LOCK(lock, client);
846 int res = 0;
847
849 publisher_client_send, (void *)body, &res);
850 return res;
851}
#define ao2_callback_data(container, flags, cb_fn, arg, data)
Definition: astobj2.h:1723
#define SCOPED_AO2LOCK(varname, obj)
scoped lock specialization for ao2 mutexes.
Definition: lock.h:604
static int publisher_client_send(void *obj, void *arg, void *data, int flags)

References ao2_callback_data, sip_outbound_publish_message::body, 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().

◆ 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
clientThe publication client to send from
userThe user to send to
bodyAn optional body to add to the PUBLISH
Return values
-1failure
0success

Definition at line 1109 of file res_pjsip_outbound_publish.c.

1111{
1112 struct sip_outbound_publisher *publisher;
1113 int res;
1114
1116 if (!publisher) {
1117 return -1;
1118 }
1119
1120 publisher_client_send(publisher, (void *)body, &res, 0);
1121 ao2_ref(publisher, -1);
1122 return res;
1123}

References ao2_ref, sip_outbound_publisher::client, publisher_client_send(), and sip_outbound_publish_client_get_publisher().

Referenced by exten_state_publisher_cb().

◆ 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
0Handler was registered successfully
non-zeroHandler was not registered successfully

Definition at line 614 of file res_pjsip_outbound_publish.c.

615{
616 struct ast_sip_event_publisher_handler *existing;
618
619 if (!handler->start_publishing || !handler->stop_publishing) {
620 ast_log(LOG_ERROR, "Handler does not implement required callbacks. Cannot register\n");
621 return -1;
622 } else if (ast_strlen_zero(handler->event_name)) {
623 ast_log(LOG_ERROR, "No event package specified for event publisher handler. Cannot register\n");
624 return -1;
625 }
626
627 existing = find_publisher_handler_for_event_name(handler->event_name);
628 if (existing) {
629 ast_log(LOG_ERROR, "Unable to register event publisher handler for event %s. "
630 "A handler is already registered\n", handler->event_name);
631 return -1;
632 }
633
635
637
638 return 0;
639}
#define ast_log
Definition: astobj2.c:42
#define LOG_ERROR
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:52
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
#define SCOPED_LOCK(varname, lock, lockfunc, unlockfunc)
Scoped Locks.
Definition: lock.h:583
static struct ast_sip_event_publisher_handler * find_publisher_handler_for_event_name(const char *event_name)
static void sub_add_handler(struct ast_sip_event_publisher_handler *handler)
static void sip_outbound_publish_synchronize(struct ast_sip_event_publisher_handler *removed)
Helper function which starts or stops publish clients when applicable.
Callbacks that event publisher handlers will define.
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

References ast_log, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_strlen_zero(), find_publisher_handler_for_event_name(), handler(), lock, LOG_ERROR, NULL, SCOPED_LOCK, sip_outbound_publish_synchronize(), and sub_add_handler().

Referenced by load_module().

◆ ast_sip_unregister_event_publisher_handler()

void ast_sip_unregister_event_publisher_handler ( struct ast_sip_event_publisher_handler handler)