res_pjsip_pubsub.h File Reference

#include "asterisk/linkedlists.h"

Include dependency graph for res_pjsip_pubsub.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_body_data
	Data used to create bodies for NOTIFY/PUBLISH requests. More...
struct	ast_sip_notifier
struct	ast_sip_publish_handler
	Callbacks that publication handlers will define. More...
struct	ast_sip_pubsub_body_generator
	Pubsub body generator. More...
struct	ast_sip_pubsub_body_supplement
	Body supplement. More...
struct	ast_sip_subscriber
struct	ast_sip_subscription_handler
struct	ast_sip_subscription_response_data
	Data for responses to SUBSCRIBEs and NOTIFIEs. More...

Macros
#define	AST_SIP_EXTEN_STATE_DATA   "ast_sip_exten_state_data"
#define	AST_SIP_MAX_ACCEPT   32
#define	AST_SIP_MESSAGE_ACCUMULATOR   "ast_sip_message_accumulator"

Enumerations
enum	ast_sip_publish_state { AST_SIP_PUBLISH_STATE_INITIALIZED, AST_SIP_PUBLISH_STATE_ACTIVE, AST_SIP_PUBLISH_STATE_TERMINATED }
enum	ast_sip_subscription_notify_reason { AST_SIP_SUBSCRIPTION_NOTIFY_REASON_STARTED, AST_SIP_SUBSCRIPTION_NOTIFY_REASON_RENEWED, AST_SIP_SUBSCRIPTION_NOTIFY_REASON_TERMINATED, AST_SIP_SUBSCRIPTION_NOTIFY_REASON_OTHER }
enum	ast_sip_subscription_role { AST_SIP_SUBSCRIBER, AST_SIP_NOTIFIER }
	Role for the subscription that is being created. More...

Functions
struct ast_sip_subscription *	ast_sip_create_subscription (const struct ast_sip_subscription_handler *handler, struct ast_sip_endpoint *endpoint, const char *resource)
	Create a new ast_sip_subscription structure. More...
int	ast_sip_publication_add_datastore (struct ast_sip_publication *publication, struct ast_datastore *datastore)
	Add a datastore to a SIP publication. More...
struct ast_datastore *	ast_sip_publication_get_datastore (struct ast_sip_publication *publication, const char *name)
	Retrieve a publication datastore. More...
struct ao2_container *	ast_sip_publication_get_datastores (const struct ast_sip_publication *publication)
	Get the datastores container for a publication. More...
struct ast_sip_endpoint *	ast_sip_publication_get_endpoint (struct ast_sip_publication *pub)
	Given a publication, get the associated endpoint. More...
const char *	ast_sip_publication_get_event_configuration (const struct ast_sip_publication *pub)
	Given a publication, get the configuration name for the event type in use. More...
const char *	ast_sip_publication_get_resource (const struct ast_sip_publication *pub)
	Given a publication, get the resource the publication is to. More...
void	ast_sip_publication_remove_datastore (struct ast_sip_publication *publication, const char *name)
	Remove a publication datastore from the publication. More...
int	ast_sip_pubsub_generate_body_content (const char *content_type, const char *content_subtype, struct ast_sip_body_data *data, struct ast_str **str)
	Generate body content for a PUBLISH or NOTIFY. More...
int	ast_sip_pubsub_is_body_generator_registered (const char *type, const char *subtype)
	Is a body generator registered for the given type/subtype. More...
int	ast_sip_pubsub_register_body_generator (struct ast_sip_pubsub_body_generator *generator)
	Register a body generator with the pubsub core. More...
int	ast_sip_pubsub_register_body_supplement (struct ast_sip_pubsub_body_supplement *supplement)
	Register a body generator with the pubsub core. More...
void	ast_sip_pubsub_unregister_body_generator (struct ast_sip_pubsub_body_generator *generator)
	Unregister a body generator with the pubsub core. More...
void	ast_sip_pubsub_unregister_body_supplement (struct ast_sip_pubsub_body_supplement *supplement)
	Unregister a body generator with the pubsub core. More...
int	ast_sip_register_publish_handler (struct ast_sip_publish_handler *handler)
	Register a publish handler. More...
int	ast_sip_register_subscription_handler (struct ast_sip_subscription_handler *handler)
	Register a subscription handler. More...
int	ast_sip_subscription_add_datastore (struct ast_sip_subscription *subscription, struct ast_datastore *datastore)
	Add a datastore to a SIP subscription. More...
struct ast_datastore *	ast_sip_subscription_alloc_datastore (const struct ast_datastore_info *info, const char *uid)
	Alternative for ast_datastore_alloc() More...
void	ast_sip_subscription_destroy (struct ast_sip_subscription *sub)
	Alert the pubsub core that the subscription is ready for destruction. More...
const char *	ast_sip_subscription_get_body_subtype (struct ast_sip_subscription *sub)
	Get the body subtype used for this subscription. More...
const char *	ast_sip_subscription_get_body_type (struct ast_sip_subscription *sub)
	Get the body type used for this subscription. More...
struct ast_datastore *	ast_sip_subscription_get_datastore (struct ast_sip_subscription *subscription, const char *name)
	Retrieve a subscription datastore. More...
struct ao2_container *	ast_sip_subscription_get_datastores (const struct ast_sip_subscription *subscription)
	Get the datastores container for a subscription. More...
pjsip_dialog *	ast_sip_subscription_get_dialog (struct ast_sip_subscription *sub)
	Get the pjsip dialog that is associated with this subscription. More...
struct ast_sip_endpoint *	ast_sip_subscription_get_endpoint (struct ast_sip_subscription *sub)
	Get the endpoint that is associated with this subscription. More...
void *	ast_sip_subscription_get_header (const struct ast_sip_subscription *sub, const char *header)
	Get a header value for a subscription. More...
void	ast_sip_subscription_get_local_uri (struct ast_sip_subscription *sub, char *buf, size_t size)
	Retrieve the local URI for this subscription. More...
const struct ast_json *	ast_sip_subscription_get_persistence_data (const struct ast_sip_subscription *subscription)
	Retrieve persistence data for a subscription. More...
void	ast_sip_subscription_get_remote_uri (struct ast_sip_subscription *sub, char *buf, size_t size)
	Retrive the remote URI for this subscription. More...
const char *	ast_sip_subscription_get_resource_name (struct ast_sip_subscription *sub)
	Get the name of the subscribed resource. More...
struct ast_taskprocessor *	ast_sip_subscription_get_serializer (struct ast_sip_subscription *sub)
	Get the serializer for the subscription. More...
pjsip_sip_uri *	ast_sip_subscription_get_sip_uri (struct ast_sip_subscription *sub)
	Retrieve the local sip uri for this subscription. More...
int	ast_sip_subscription_is_terminated (const struct ast_sip_subscription *sub)
	Get whether the subscription has been terminated or not. More...
int	ast_sip_subscription_notify (struct ast_sip_subscription *sub, struct ast_sip_body_data *notify_data, int terminate)
	Notify a SIP subscription of a state change. More...
void	ast_sip_subscription_remove_datastore (struct ast_sip_subscription *subscription, const char *name)
	Remove a subscription datastore from the subscription. More...
int	ast_sip_subscription_send_request (struct ast_sip_subscription *sub, pjsip_tx_data *tdata)
	Send a request created via a PJSIP evsub method. More...
void	ast_sip_subscription_set_persistence_data (struct ast_sip_subscription *subscription, struct ast_json *persistence_data)
	Set persistence data for a subscription. More...
void	ast_sip_unregister_publish_handler (struct ast_sip_publish_handler *handler)
	Unregister a publish handler. More...
void	ast_sip_unregister_subscription_handler (struct ast_sip_subscription_handler *handler)
	Unregister a subscription handler. More...

Macro Definition Documentation

AST_SIP_EXTEN_STATE_DATA

#define AST_SIP_EXTEN_STATE_DATA   "ast_sip_exten_state_data"

Type used for extension state/presence

Definition at line 232 of file res_pjsip_pubsub.h.

Referenced by exten_state_publisher_cb(), and notify_task().

AST_SIP_MAX_ACCEPT

#define AST_SIP_MAX_ACCEPT   32

Definition at line 219 of file res_pjsip_pubsub.h.

Referenced by ast_sip_register_subscription_handler(), subscription_get_generator_from_rdata(), and subscription_persistence_remove().

AST_SIP_MESSAGE_ACCUMULATOR

#define AST_SIP_MESSAGE_ACCUMULATOR   "ast_sip_message_accumulator"

Type used for conveying mailbox state

Definition at line 234 of file res_pjsip_pubsub.h.

Referenced by send_mwi_notify(), and send_unsolicited_mwi_notify_to_contact().

Enumeration Type Documentation

ast_sip_publish_state

enum ast_sip_publish_state

Enumerator
AST_SIP_PUBLISH_STATE_INITIALIZED	Publication has just been initialized
AST_SIP_PUBLISH_STATE_ACTIVE	Publication is currently active
AST_SIP_PUBLISH_STATE_TERMINATED	Publication has been terminated

Definition at line 37 of file res_pjsip_pubsub.h.

                           {
    /*! Publication has just been initialized */
    AST_SIP_PUBLISH_STATE_INITIALIZED,
    /*! Publication is currently active */
    AST_SIP_PUBLISH_STATE_ACTIVE,
    /*! Publication has been terminated */
    AST_SIP_PUBLISH_STATE_TERMINATED,
};

ast_sip_subscription_notify_reason

enum ast_sip_subscription_notify_reason

Enumerator
AST_SIP_SUBSCRIPTION_NOTIFY_REASON_STARTED	Initial NOTIFY for subscription
AST_SIP_SUBSCRIPTION_NOTIFY_REASON_RENEWED	Subscription has been renewed
AST_SIP_SUBSCRIPTION_NOTIFY_REASON_TERMINATED	Subscription is being terminated
AST_SIP_SUBSCRIPTION_NOTIFY_REASON_OTHER	Other unspecified reason

Definition at line 220 of file res_pjsip_pubsub.h.

                                        {
   /*! Initial NOTIFY for subscription */
   AST_SIP_SUBSCRIPTION_NOTIFY_REASON_STARTED,
   /*! Subscription has been renewed */
   AST_SIP_SUBSCRIPTION_NOTIFY_REASON_RENEWED,
   /*! Subscription is being terminated */
   AST_SIP_SUBSCRIPTION_NOTIFY_REASON_TERMINATED,
   /*! Other unspecified reason */
   AST_SIP_SUBSCRIPTION_NOTIFY_REASON_OTHER
};

ast_sip_subscription_role

enum ast_sip_subscription_role

Role for the subscription that is being created.

Enumerator
AST_SIP_SUBSCRIBER
AST_SIP_NOTIFIER

Definition at line 190 of file res_pjsip_pubsub.h.

                               {
   /* Sending SUBSCRIBEs, receiving NOTIFYs */
   AST_SIP_SUBSCRIBER,
   /* Sending NOTIFYs, receiving SUBSCRIBEs */
   AST_SIP_NOTIFIER,
};

Function Documentation

ast_sip_create_subscription()

struct ast_sip_subscription* ast_sip_create_subscription	(	const struct ast_sip_subscription_handler *	handler,
		struct ast_sip_endpoint *	endpoint,
		const char *	resource
	)

Create a new ast_sip_subscription structure.

When a subscriber wishes to create a subscription, it may call this function to allocate resources and to send the initial SUBSCRIBE out.

Parameters

subscriber	The subscriber that is making the request.
endpoint	The endpoint to whome the SUBSCRIBE will be sent.
resource	The resource to place in the SUBSCRIBE's Request-URI.

Definition at line 1868 of file res_pjsip_pubsub.c.

References add_subscription(), allocate_subscription(), allocate_subscription_tree(), ao2_cleanup, ao2_ref, ast_sip_endpoint::aors, ast_log, ast_sip_create_dialog_uac(), ast_sip_location_retrieve_contact_from_aor_list(), ast_sorcery_object_get_id(), ast_strlen_zero, resource_list::event, ast_sip_subscription_handler::event_name, sip_subscription_tree::evsub, LOG_WARNING, NULL, pubsub_cb, sub, subscription_setup_dialog(), and ast_sip_contact::uri.

{
   struct ast_sip_subscription *sub;
   pjsip_dialog *dlg;
   struct ast_sip_contact *contact;
   pj_str_t event;
   pjsip_tx_data *tdata;
   pjsip_evsub *evsub;
   struct sip_subscription_tree *sub_tree = NULL;

   sub_tree = allocate_subscription_tree(endpoint, NULL);
   if (!sub_tree) {
      return NULL;
   }

   sub = allocate_subscription(handler, resource, sub_tree);
   if (!sub) {
      ao2_cleanup(sub_tree);
      return NULL;
   }

   contact = ast_sip_location_retrieve_contact_from_aor_list(endpoint->aors);
   if (!contact || ast_strlen_zero(contact->uri)) {
      ast_log(LOG_WARNING, "No contacts configured for endpoint %s. Unable to create SIP subsription\n",
            ast_sorcery_object_get_id(endpoint));
      ao2_ref(sub_tree, -1);
      ao2_cleanup(contact);
      return NULL;
   }

   dlg = ast_sip_create_dialog_uac(endpoint, contact->uri, NULL);
   ao2_cleanup(contact);
   if (!dlg) {
      ast_log(LOG_WARNING, "Unable to create dialog for SIP subscription\n");
      ao2_ref(sub_tree, -1);
      return NULL;
   }

   pj_cstr(&event, handler->event_name);
   pjsip_evsub_create_uac(dlg, &pubsub_cb, &event, 0, &sub_tree->evsub);
   subscription_setup_dialog(sub_tree, dlg);

   evsub = sub_tree->evsub;

   if (pjsip_evsub_initiate(evsub, NULL, -1, &tdata) == PJ_SUCCESS) {
      pjsip_evsub_send_request(sub_tree->evsub, tdata);
   } else {
      /* pjsip_evsub_terminate will result in pubsub_on_evsub_state,
       * being called and terminating the subscription. Therefore, we don't
       * need to decrease the reference count of sub here.
       */
      pjsip_evsub_terminate(evsub, PJ_TRUE);
      ao2_ref(sub_tree, -1);
      return NULL;
   }

   add_subscription(sub_tree);

   return sub;
}

ast_sip_publication_add_datastore()

int ast_sip_publication_add_datastore	(	struct ast_sip_publication *	publication,
		struct ast_datastore *	datastore
	)

Add a datastore to a SIP publication.

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

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

Return values

0	Success
-1	Failure

Definition at line 2649 of file res_pjsip_pubsub.c.

References ast_datastores_add(), and ast_sip_publication::datastores.

{
   return ast_datastores_add(publication->datastores, datastore);
}

ast_sip_publication_get_datastore()

struct ast_datastore* ast_sip_publication_get_datastore	(	struct ast_sip_publication *	publication,
		const char *	name
	)

Retrieve a publication 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

publication	The publication 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 2654 of file res_pjsip_pubsub.c.

References ast_datastores_find(), and ast_sip_publication::datastores.

{
   return ast_datastores_find(publication->datastores, name);
}

ast_sip_publication_get_datastores()

struct ao2_container* ast_sip_publication_get_datastores

(

const struct ast_sip_publication *

publication

)

Get the datastores container for a publication.

Parameters

publication

The publication to get the datastores container from

Return values

NULL	datastores container not present
non-NULL	datastores container

Note

The container is NOT returned with reference count bumped

Since

14.0.0

Definition at line 2664 of file res_pjsip_pubsub.c.

References ast_sip_publication::datastores.

{
   return publication->datastores;
}

ast_sip_publication_get_endpoint()

struct ast_sip_endpoint* ast_sip_publication_get_endpoint

(

struct ast_sip_publication *

pub

)

Given a publication, get the associated endpoint.

Parameters

pub	The publication

Return values

NULL	Failure
non-NULL	The associated endpoint

Definition at line 3420 of file res_pjsip_pubsub.c.

References ast_sip_publication::endpoint.

{
   return pub->endpoint;
}

ast_sip_publication_get_event_configuration()

const char* ast_sip_publication_get_event_configuration

(

const struct ast_sip_publication *

pub

)

Given a publication, get the configuration name for the event type in use.

Parameters

pub	The publication

Returns

The configuration name

Definition at line 3430 of file res_pjsip_pubsub.c.

References ast_sip_publication::event_configuration_name.

Referenced by asterisk_publication_devicestate_state_change(), and asterisk_publication_mwi_state_change().

{
   return pub->event_configuration_name;
}

ast_sip_publication_get_resource()

const char* ast_sip_publication_get_resource

(

const struct ast_sip_publication *

pub

)

Given a publication, get the resource the publication is to.

Parameters

pub	The publication

Returns

The resource

Definition at line 3425 of file res_pjsip_pubsub.c.

References ast_sip_publication::resource.

{
   return pub->resource;
}

ast_sip_publication_remove_datastore()

void ast_sip_publication_remove_datastore	(	struct ast_sip_publication *	publication,
		const char *	name
	)

Remove a publication datastore from the publication.

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

Parameters

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

Definition at line 2659 of file res_pjsip_pubsub.c.

References ast_datastores_remove(), and ast_sip_publication::datastores.

{
   ast_datastores_remove(publication->datastores, name);
}

ast_sip_pubsub_generate_body_content()

int ast_sip_pubsub_generate_body_content	(	const char *	content_type,
		const char *	content_subtype,
		struct ast_sip_body_data *	data,
		struct ast_str **	str
	)

Generate body content for a PUBLISH or NOTIFY.

Since

13.0.0 This function takes a pre-allocated body and calls into registered body generators in order to fill in the body with appropriate details. The primary body generator will be called first, followed by the supplementary body generators

Parameters

	content_type	The content type of the body
	content_subtype	The content subtype of the body
	data	The data associated with body generation.
[out]	str	The string representation of the generated body

Return values

0	Success
non-zero	Failure

Definition at line 3519 of file res_pjsip_pubsub.c.

References ast_sip_pubsub_body_generator::allocate_body, ast_log, AST_RWLIST_RDLOCK, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, ast_sip_body_data::body_data, ast_sip_body_data::body_type, ast_sip_pubsub_body_generator::body_type, ast_sip_pubsub_body_generator::destroy_body, end, find_body_generator_type_subtype(), ast_sip_pubsub_body_generator::generate_body_content, generator, ast_sip_pubsub_body_generator::list, LOG_WARNING, ast_sip_pubsub_body_generator::subtype, ast_sip_pubsub_body_supplement::subtype, ast_sip_pubsub_body_supplement::supplement_body, ast_sip_pubsub_body_generator::to_string, ast_sip_pubsub_body_generator::type, and ast_sip_pubsub_body_supplement::type.

Referenced by ast_sip_subscription_notify(), exten_state_publisher_cb(), generate_initial_notify(), and send_unsolicited_mwi_notify_to_contact().

{
   struct ast_sip_pubsub_body_supplement *supplement;
   struct ast_sip_pubsub_body_generator *generator;
   int res = 0;
   void *body;

   generator = find_body_generator_type_subtype(type, subtype);
   if (!generator) {
      ast_log(LOG_WARNING, "Unable to find a body generator for %s/%s\n",
            type, subtype);
      return -1;
   }

   if (strcmp(data->body_type, generator->body_type)) {
      ast_log(LOG_WARNING, "%s/%s body generator does not accept the type of data provided\n",
         type, subtype);
      return -1;
   }

   body = generator->allocate_body(data->body_data);
   if (!body) {
      ast_log(LOG_WARNING, "%s/%s body generator could not to allocate a body\n",
         type, subtype);
      return -1;
   }

   if (generator->generate_body_content(body, data->body_data)) {
      res = -1;
      goto end;
   }

   AST_RWLIST_RDLOCK(&body_supplements);
   AST_RWLIST_TRAVERSE(&body_supplements, supplement, list) {
      if (!strcmp(generator->type, supplement->type) &&
            !strcmp(generator->subtype, supplement->subtype)) {
         res = supplement->supplement_body(body, data->body_data);
         if (res) {
            break;
         }
      }
   }
   AST_RWLIST_UNLOCK(&body_supplements);

   if (!res) {
      generator->to_string(body, str);
   }

end:
   if (generator->destroy_body) {
      generator->destroy_body(body);
   }

   return res;
}

ast_sip_pubsub_is_body_generator_registered()

int ast_sip_pubsub_is_body_generator_registered	(	const char *	type,
		const char *	subtype
	)

Is a body generator registered for the given type/subtype.

Since

14.0.0

Parameters

type	The content type of the body
subtype	The content subtype of the body

Note

In "plain/text", "plain" is the type and "text" is the subtype.

Return values

non-zero

if a generator is registered.

Definition at line 3435 of file res_pjsip_pubsub.c.

References find_body_generator_type_subtype().

Referenced by publisher_start().

{
   return !!find_body_generator_type_subtype(type, subtype);
}

ast_sip_pubsub_register_body_generator()

int ast_sip_pubsub_register_body_generator

(

struct ast_sip_pubsub_body_generator *

generator

)

Register a body generator with the pubsub core.

Since

13.0.0 This may fail if an attempt is made to register a primary body supplement for a given content type if a primary body supplement for that content type has already been registered.

Parameters

generator

Body generator to register

Return values

0	Success
-1	Failure

Definition at line 3440 of file res_pjsip_pubsub.c.

References ast_alloca, AST_LIST_INSERT_HEAD, ast_log, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_sip_get_pjsip_endpoint(), find_body_generator_type_subtype_nolock(), ast_sip_pubsub_body_generator::list, LOG_WARNING, NULL, pubsub_module, ast_sip_pubsub_body_generator::subtype, and ast_sip_pubsub_body_generator::type.

Referenced by load_module().

{
   struct ast_sip_pubsub_body_generator *existing;
   pj_str_t accept;
   pj_size_t accept_len;

   AST_RWLIST_WRLOCK(&body_generators);
   existing = find_body_generator_type_subtype_nolock(generator->type, generator->subtype);
   if (existing) {
      AST_RWLIST_UNLOCK(&body_generators);
      ast_log(LOG_WARNING, "A body generator for %s/%s is already registered.\n",
         generator->type, generator->subtype);
      return -1;
   }
   AST_LIST_INSERT_HEAD(&body_generators, generator, list);
   AST_RWLIST_UNLOCK(&body_generators);

   /* Lengths of type and subtype plus a slash. */
   accept_len = strlen(generator->type) + strlen(generator->subtype) + 1;

   /* Add room for null terminator that sprintf() will set. */
   pj_strset(&accept, ast_alloca(accept_len + 1), accept_len);
   sprintf((char *) pj_strbuf(&accept), "%s/%s", generator->type, generator->subtype);/* Safe */

   pjsip_endpt_add_capability(ast_sip_get_pjsip_endpoint(), &pubsub_module,
         PJSIP_H_ACCEPT, NULL, 1, &accept);

   return 0;
}

ast_sip_pubsub_register_body_supplement()

int ast_sip_pubsub_register_body_supplement

(

struct ast_sip_pubsub_body_supplement *

supplement

)

Register a body generator with the pubsub core.

Since

13.0.0 This may fail if an attempt is made to register a primary body supplement for a given content type if a primary body supplement for that content type has already been registered.

Parameters

generator

Body generator to register

Return values

0	Success
-1	Failure

Definition at line 3485 of file res_pjsip_pubsub.c.

References AST_RWLIST_INSERT_TAIL, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, and ast_sip_pubsub_body_generator::list.

Referenced by load_module().

{
   AST_RWLIST_WRLOCK(&body_supplements);
   AST_RWLIST_INSERT_TAIL(&body_supplements, supplement, list);
   AST_RWLIST_UNLOCK(&body_supplements);

   return 0;
}

ast_sip_pubsub_unregister_body_generator()

void ast_sip_pubsub_unregister_body_generator

(

struct ast_sip_pubsub_body_generator *

generator

)

Unregister a body generator with the pubsub core.

Since

13.0.0

Parameters

generator

Body generator to unregister

Definition at line 3470 of file res_pjsip_pubsub.c.

References AST_LIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, and ast_sip_pubsub_body_generator::list.

Referenced by unload_module(), and unregister_all().

{
   struct ast_sip_pubsub_body_generator *iter;

   AST_RWLIST_WRLOCK(&body_generators);
   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&body_generators, iter, list) {
      if (iter == generator) {
         AST_LIST_REMOVE_CURRENT(list);
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;
   AST_RWLIST_UNLOCK(&body_generators);
}

ast_sip_pubsub_unregister_body_supplement()

void ast_sip_pubsub_unregister_body_supplement

(

struct ast_sip_pubsub_body_supplement *

supplement

)

Unregister a body generator with the pubsub core.

Since

13.0.0

Parameters

generator

Body generator to unregister

Definition at line 3494 of file res_pjsip_pubsub.c.

References AST_LIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, and ast_sip_pubsub_body_supplement::list.

Referenced by unload_module().

{
   struct ast_sip_pubsub_body_supplement *iter;

   AST_RWLIST_WRLOCK(&body_supplements);
   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&body_supplements, iter, list) {
      if (iter == supplement) {
         AST_LIST_REMOVE_CURRENT(list);
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;
   AST_RWLIST_UNLOCK(&body_supplements);
}

ast_sip_register_publish_handler()

int ast_sip_register_publish_handler

(

struct ast_sip_publish_handler *

handler

)

Register a publish handler.

Return values

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

Definition at line 2718 of file res_pjsip_pubsub.c.

References AO2_ALLOC_OPT_LOCK_MUTEX, ao2_container_alloc_hash, ast_log, ast_strlen_zero, ast_sip_publish_handler::event_name, LOG_ERROR, NULL, publication_cmp_fn(), publication_hash_fn(), ast_sip_publish_handler::publications, PUBLICATIONS_BUCKETS, and publish_add_handler().

Referenced by load_module().

{
   if (ast_strlen_zero(handler->event_name)) {
      ast_log(LOG_ERROR, "No event package specified for publish handler. Cannot register\n");
      return -1;
   }

   handler->publications = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_MUTEX, 0,
      PUBLICATIONS_BUCKETS, publication_hash_fn, NULL, publication_cmp_fn);
   if (!handler->publications) {
      ast_log(LOG_ERROR, "Could not allocate publications container for event '%s'\n",
         handler->event_name);
      return -1;
   }

   publish_add_handler(handler);

   return 0;
}

ast_sip_register_subscription_handler()

int ast_sip_register_subscription_handler

(

struct ast_sip_subscription_handler *

handler

)

Register a subscription handler.

Return values

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

Definition at line 2777 of file res_pjsip_pubsub.c.

References ast_sip_subscription_handler::accept, ast_log, AST_SIP_MAX_ACCEPT, ast_strlen_zero, DEFAULT_EXPIRES, resource_list::event, ast_sip_subscription_handler::event_name, find_sub_handler_for_event_name(), LOG_ERROR, pubsub_module, and sub_add_handler().

Referenced by load_module().

{
   pj_str_t event;
   pj_str_t accept[AST_SIP_MAX_ACCEPT] = { {0, }, };
   struct ast_sip_subscription_handler *existing;
   int i = 0;

   if (ast_strlen_zero(handler->event_name)) {
      ast_log(LOG_ERROR, "No event package specified for subscription handler. Cannot register\n");
      return -1;
   }

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

   for (i = 0; i < AST_SIP_MAX_ACCEPT && !ast_strlen_zero(handler->accept[i]); ++i) {
      pj_cstr(&accept[i], handler->accept[i]);
   }

   pj_cstr(&event, handler->event_name);

   pjsip_evsub_register_pkg(&pubsub_module, &event, DEFAULT_EXPIRES, i, accept);

   sub_add_handler(handler);

   return 0;
}

ast_sip_subscription_add_datastore()

int ast_sip_subscription_add_datastore	(	struct ast_sip_subscription *	subscription,
		struct ast_datastore *	datastore
	)

Add a datastore to a SIP subscription.

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

subscription	The ssubscription to add the datastore to
datastore	The datastore to be added to the subscription

Return values

0	Success
-1	Failure

Definition at line 2629 of file res_pjsip_pubsub.c.

References ast_datastores_add(), and ast_sip_subscription::datastores.

Referenced by add_datastore(), and add_mwi_datastore().

{
   return ast_datastores_add(subscription->datastores, datastore);
}

ast_sip_subscription_alloc_datastore()

struct ast_datastore* ast_sip_subscription_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 2624 of file res_pjsip_pubsub.c.

References ast_datastores_alloc_datastore().

Referenced by add_datastore(), and add_mwi_datastore().

{
   return ast_datastores_alloc_datastore(info, uid);
}

ast_sip_subscription_destroy()

void ast_sip_subscription_destroy

(

struct ast_sip_subscription *

sub

)

Alert the pubsub core that the subscription is ready for destruction.

Since

13.6.0

Parameters

sub	The subscription that is complete

Returns

Nothing

Definition at line 1389 of file res_pjsip_pubsub.c.

References ao2_cleanup, ast_debug, ast_sorcery_object_get_id(), sip_subscription_tree::endpoint, and ast_sip_subscription::tree.

Referenced by exten_state_subscription_destructor(), and mwi_subscription_destructor().

{
   ast_debug(3, "Removing subscription %p '%s->%s' reference to subscription tree %p\n",
      sub, ast_sorcery_object_get_id(sub->tree->endpoint), sub->resource, sub->tree);
   ao2_cleanup(sub->tree);
}

ast_sip_subscription_get_body_subtype()

const char* ast_sip_subscription_get_body_subtype

(

struct ast_sip_subscription *

sub

)

Get the body subtype used for this subscription.

Since

13.0.0

Definition at line 3514 of file res_pjsip_pubsub.c.

References ast_sip_subscription::body_generator, and ast_sip_pubsub_body_generator::subtype.

Referenced by ast_sip_subscription_notify(), generate_initial_notify(), and generate_notify_body().

{
   return sub->body_generator->subtype;
}

ast_sip_subscription_get_body_type()

const char* ast_sip_subscription_get_body_type

(

struct ast_sip_subscription *

sub

)

Get the body type used for this subscription.

Since

13.0.0

Definition at line 3509 of file res_pjsip_pubsub.c.

References ast_sip_subscription::body_generator, and ast_sip_pubsub_body_generator::type.

Referenced by ast_sip_subscription_notify(), generate_initial_notify(), and generate_notify_body().

{
   return sub->body_generator->type;
}

ast_sip_subscription_get_datastore()

struct ast_datastore* ast_sip_subscription_get_datastore	(	struct ast_sip_subscription *	subscription,
		const char *	name
	)

Retrieve a subscription 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

subscription	The subscription 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 2634 of file res_pjsip_pubsub.c.

References ast_datastores_find(), and ast_sip_subscription::datastores.

Referenced by get_exten_state_sub(), mwi_get_notify_data(), mwi_subscription_shutdown(), and mwi_to_ami().

{
   return ast_datastores_find(subscription->datastores, name);
}

ast_sip_subscription_get_datastores()

struct ao2_container* ast_sip_subscription_get_datastores

(

const struct ast_sip_subscription *

subscription

)

Get the datastores container for a subscription.

Parameters

subscription

The subscription to get the datastores container from

Return values

NULL	datastores container not present
non-NULL	datastores container

Note

The container is NOT returned with reference count bumped

Since

14.0.0

Definition at line 2644 of file res_pjsip_pubsub.c.

References ast_sip_subscription::datastores.

Referenced by alloc_notify_task_data(), exten_state_data_alloc(), and notify_task().

{
   return subscription->datastores;
}

ast_sip_subscription_get_dialog()

pjsip_dialog* ast_sip_subscription_get_dialog

(

struct ast_sip_subscription *

sub

)

Get the pjsip dialog that is associated with this subscription.

Since

13.9.0

Return values

NULL	Could not get dialog
non-NULL	The dialog

Definition at line 1930 of file res_pjsip_pubsub.c.

References ast_assert, sip_subscription_tree::dlg, NULL, and ast_sip_subscription::tree.

Referenced by dialog_info_generate_body_content(), mwi_get_notify_data(), and send_mwi_notify().

{
   ast_assert(sub->tree->dlg != NULL);
   return sub->tree->dlg;
}

ast_sip_subscription_get_endpoint()

struct ast_sip_endpoint* ast_sip_subscription_get_endpoint

(

struct ast_sip_subscription *

sub

)

Get the endpoint that is associated with this subscription.

This function will increase the reference count of the endpoint. Be sure to release the reference to it when you are finished with the endpoint.

Return values

NULL	Could not get endpoint
non-NULL	The endpoint

Definition at line 1936 of file res_pjsip_pubsub.c.

References ao2_bump, ast_assert, sip_subscription_tree::endpoint, NULL, and ast_sip_subscription::tree.

Referenced by dialog_info_generate_body_content(), mwi_get_notify_data(), mwi_subscription_established(), send_mwi_notify(), and subscription_established().

{
   ast_assert(sub->tree->endpoint != NULL);
   return ao2_bump(sub->tree->endpoint);
}

ast_sip_subscription_get_header()

void* ast_sip_subscription_get_header	(	const struct ast_sip_subscription *	sub,
		const char *	header
	)

Get a header value for a subscription.

For notifiers, the headers of the inbound SUBSCRIBE that started the dialog are stored on the subscription. This method allows access to the header. The return is the same as pjsip_msg_find_hdr_by_name(), meaning that it is dependent on the header being searched for.

Parameters

sub	The subscription to search in.
header	The name of the header to search for.

Returns

The discovered header, or NULL if the header cannot be found.

Definition at line 1854 of file res_pjsip_pubsub.c.

References ast_sip_mod_data_get, sip_subscription_tree::dlg, MOD_DATA_MSG, name, NULL, pubsub_module, and ast_sip_subscription::tree.

Referenced by get_user_agent().

{
   pjsip_dialog *dlg;
   pjsip_msg *msg;
   pj_str_t name;

   dlg = sub->tree->dlg;
   msg = ast_sip_mod_data_get(dlg->mod_data, pubsub_module.id, MOD_DATA_MSG);
   pj_cstr(&name, header);

   return pjsip_msg_find_hdr_by_name(msg, &name, NULL);
}

ast_sip_subscription_get_local_uri()

void ast_sip_subscription_get_local_uri	(	struct ast_sip_subscription *	sub,
		char *	buf,
		size_t	size
	)

Retrieve the local URI for this subscription.

This is the local URI of the subscribed resource.

Parameters

	sub	The subscription
[out]	buf	The buffer into which to store the URI.
	size	The size of the buffer.

Definition at line 2578 of file res_pjsip_pubsub.c.

Referenced by build_rlmi_body(), exten_state_data_alloc(), and notify_task().

{
   pjsip_uri_print(PJSIP_URI_IN_CONTACT_HDR, sub->uri, buf, size);
}

ast_sip_subscription_get_persistence_data()

const struct ast_json* ast_sip_subscription_get_persistence_data

(

const struct ast_sip_subscription *

subscription

)

Retrieve persistence data for a subscription.

Since

13.31.0

16.8.0

17.2.0

Parameters

subscription

The subscription to retrieve persistence data from

Definition at line 2686 of file res_pjsip_pubsub.c.

Referenced by dialog_info_generate_body_content().

{
   return subscription->persistence_data;
}

ast_sip_subscription_get_remote_uri()

void ast_sip_subscription_get_remote_uri	(	struct ast_sip_subscription *	sub,
		char *	buf,
		size_t	size
	)

Retrive the remote URI for this subscription.

This is the remote URI as determined by the underlying SIP dialog.

Parameters

	sub	The subscription
[out]	buf	The buffer into which to store the URI.
	size	The size of the buffer.

Definition at line 2583 of file res_pjsip_pubsub.c.

References sip_subscription_tree::dlg, and ast_sip_subscription::tree.

Referenced by exten_state_data_alloc(), and notify_task().

{
   pjsip_dialog *dlg;
   pjsip_sip_uri *uri;

   dlg = sub->tree->dlg;
   uri = pjsip_uri_get_uri(dlg->remote.info->uri);

   if (pjsip_uri_print(PJSIP_URI_IN_FROMTO_HDR, uri, buf, size) < 0) {
      *buf = '\0';
   }
}

ast_sip_subscription_get_resource_name()

const char* ast_sip_subscription_get_resource_name

(

struct ast_sip_subscription *

sub

)

Get the name of the subscribed resource.

Definition at line 2596 of file res_pjsip_pubsub.c.

Referenced by build_rlmi_body(), mwi_get_notify_data(), mwi_subscription_established(), remove_subscription(), send_mwi_notify(), and subscription_established().

{
   return sub->resource;
}

ast_sip_subscription_get_serializer()

struct ast_taskprocessor* ast_sip_subscription_get_serializer

(

struct ast_sip_subscription *

sub

)

Get the serializer for the subscription.

Tasks that originate outside of a SIP servant thread should get the serializer and push the task to the serializer.

Parameters

sub	The subscription

Return values

NULL	Failure
non-NULL	The subscription's serializer

Definition at line 1942 of file res_pjsip_pubsub.c.

References ast_assert, NULL, sip_subscription_tree::serializer, and ast_sip_subscription::tree.

Referenced by exten_state_subscription_alloc(), and send_notify().

{
   ast_assert(sub->tree->serializer != NULL);
   return sub->tree->serializer;
}

ast_sip_subscription_get_sip_uri()

pjsip_sip_uri* ast_sip_subscription_get_sip_uri

(

struct ast_sip_subscription *

sub

)

Retrieve the local sip uri for this subscription.

Since

13.9.0

This is the local sip URI of the subscribed resource.

Parameters

sub	The subscription

Return values

NULL	Could not get uri
non-NULL	The local pjsip_sip_uri

Definition at line 2573 of file res_pjsip_pubsub.c.

Referenced by mwi_get_notify_data(), and send_mwi_notify().

{
   return sub->uri;
}

ast_sip_subscription_is_terminated()

int ast_sip_subscription_is_terminated

(

const struct ast_sip_subscription *

sub

)

Get whether the subscription has been terminated or not.

Parameters

sub	The subscription.

Return values

0	not terminated.
1	terminated.

Since

13.4.0

Definition at line 2601 of file res_pjsip_pubsub.c.

Referenced by notify_task().

{
   return sub->subscription_state == PJSIP_EVSUB_STATE_TERMINATED ? 1 : 0;
}

ast_sip_subscription_notify()

int ast_sip_subscription_notify	(	struct ast_sip_subscription *	sub,
		struct ast_sip_body_data *	notify_data,
		int	terminate
	)

Notify a SIP subscription of a state change.

This tells the pubsub core that the state of a subscribed resource has changed. The pubsub core will generate an appropriate NOTIFY request to send to the subscriber.

Parameters

sub	The subscription on which a state change is occurring.
notify_data	Event package-specific data used to create the NOTIFY body.
terminate	True if this NOTIFY is intended to terminate the subscription.

Return values

0	Success
non-zero	Failure

Definition at line 2529 of file res_pjsip_pubsub.c.

References ao2_ref, ast_sip_pubsub_generate_body_content(), ast_sip_subscription_get_body_subtype(), ast_sip_subscription_get_body_type(), ast_test_suite_event_notify, sip_subscription_tree::dlg, sip_subscription_tree::notification_batch_interval, sip_subscription_tree::root, schedule_notification(), send_notify(), SIP_SUB_TREE_NORMAL, SIP_SUB_TREE_TERMINATE_IN_PROGRESS, SIP_SUB_TREE_TERMINATE_PENDING, sip_subscription_tree::state, and ast_sip_subscription::tree.

Referenced by notify_task(), and send_mwi_notify().

{
   int res;
   pjsip_dialog *dlg = sub->tree->dlg;

   pjsip_dlg_inc_lock(dlg);

   if (sub->tree->state != SIP_SUB_TREE_NORMAL) {
      pjsip_dlg_dec_lock(dlg);
      return 0;
   }

   if (ast_sip_pubsub_generate_body_content(ast_sip_subscription_get_body_type(sub),
            ast_sip_subscription_get_body_subtype(sub), notify_data, &sub->body_text)) {
      pjsip_dlg_dec_lock(dlg);
      return -1;
   }

   sub->body_changed = 1;
   if (terminate) {
      sub->subscription_state = PJSIP_EVSUB_STATE_TERMINATED;
      sub->tree->state = SIP_SUB_TREE_TERMINATE_PENDING;
   }

   if (sub->tree->notification_batch_interval) {
      res = schedule_notification(sub->tree);
   } else {
      /* See the note in pubsub_on_rx_refresh() for why sub->tree is refbumped here */
      ao2_ref(sub->tree, +1);
      if (terminate) {
         sub->tree->state = SIP_SUB_TREE_TERMINATE_IN_PROGRESS;
      }
      res = send_notify(sub->tree, 0);
      ast_test_suite_event_notify(terminate ? "SUBSCRIPTION_TERMINATED" : "SUBSCRIPTION_STATE_CHANGED",
            "Resource: %s",
            sub->tree->root->resource);
      ao2_ref(sub->tree, -1);
   }

   pjsip_dlg_dec_lock(dlg);
   return res;
}

ast_sip_subscription_remove_datastore()

void ast_sip_subscription_remove_datastore	(	struct ast_sip_subscription *	subscription,
		const char *	name
	)

Remove a subscription datastore from the subscription.

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

Parameters

subscription	The subscription to remove the datastore from
name	The name of the datastore to remove

Definition at line 2639 of file res_pjsip_pubsub.c.

References ast_datastores_remove(), and ast_sip_subscription::datastores.

Referenced by mwi_subscription_established(), mwi_subscription_shutdown(), and subscription_shutdown().

{
   ast_datastores_remove(subscription->datastores, name);
}

ast_sip_subscription_send_request()

int ast_sip_subscription_send_request	(	struct ast_sip_subscription *	sub,
		pjsip_tx_data *	tdata
	)

Send a request created via a PJSIP evsub method.

Callers of this function should take care to do so within a SIP servant thread.

Parameters

sub	The subscription on which to send the request
tdata	The request to send

Return values

0	Success
non-zero	Failure

ast_sip_subscription_set_persistence_data()

void ast_sip_subscription_set_persistence_data	(	struct ast_sip_subscription *	subscription,
		struct ast_json *	persistence_data
	)

Set persistence data for a subscription.

Since

13.31.0

16.8.0

17.2.0

Parameters

subscription	The subscription to set persistence data on
persistence_data	The persistence data to set

Note

This steals the reference to persistence_data

Definition at line 2669 of file res_pjsip_pubsub.c.

References ast_json_object_create(), ast_json_object_set(), ast_json_ref(), ast_json_unref(), subscription_persistence::generator_data, sip_subscription_tree::persistence, and ast_sip_subscription::tree.

Referenced by dialog_info_generate_body_content().

{
   ast_json_unref(subscription->persistence_data);
   subscription->persistence_data = persistence_data;

   if (subscription->tree->persistence) {
      if (!subscription->tree->persistence->generator_data) {
         subscription->tree->persistence->generator_data = ast_json_object_create();
         if (!subscription->tree->persistence->generator_data) {
            return;
         }
      }
      ast_json_object_set(subscription->tree->persistence->generator_data, subscription->resource,
         ast_json_ref(persistence_data));
   }
}

ast_sip_unregister_publish_handler()

void ast_sip_unregister_publish_handler

(

struct ast_sip_publish_handler *

handler

)

Unregister a publish handler.

Definition at line 2738 of file res_pjsip_pubsub.c.

References ao2_cleanup, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_sip_publish_handler::next, and ast_sip_publish_handler::publications.

Referenced by load_module(), and unload_module().

{
   struct ast_sip_publish_handler *iter;

   AST_RWLIST_WRLOCK(&publish_handlers);
   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&publish_handlers, iter, next) {
      if (handler == iter) {
         AST_RWLIST_REMOVE_CURRENT(next);
         ao2_cleanup(handler->publications);
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;
   AST_RWLIST_UNLOCK(&publish_handlers);
}

ast_sip_unregister_subscription_handler()

void ast_sip_unregister_subscription_handler

(

struct ast_sip_subscription_handler *

handler

)

Unregister a subscription handler.

Definition at line 2810 of file res_pjsip_pubsub.c.

References AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, and ast_sip_subscription_handler::next.

Referenced by unload_module().

{
   struct ast_sip_subscription_handler *iter;

   AST_RWLIST_WRLOCK(&subscription_handlers);
   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&subscription_handlers, iter, next) {
      if (handler == iter) {
         AST_RWLIST_REMOVE_CURRENT(next);
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;
   AST_RWLIST_UNLOCK(&subscription_handlers);
}