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_DEVICE_FEATURE_SYNC_DATA   "ast_sip_device_feature_sync_data"
#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_DEVICE_FEATURE_SYNC_DATA

#define AST_SIP_DEVICE_FEATURE_SYNC_DATA   "ast_sip_device_feature_sync_data"

Type used for device feature synchronization

Definition at line 236 of file res_pjsip_pubsub.h.

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.

AST_SIP_MAX_ACCEPT

#define AST_SIP_MAX_ACCEPT   32

Definition at line 219 of file res_pjsip_pubsub.h.

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.

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

handler	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 2116 of file res_pjsip_pubsub.c.

{
    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, NULL, 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;
}

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(), sip_subscription_tree::dlg, sip_subscription_tree::endpoint, sip_subscription_tree::evsub, handler(), LOG_WARNING, NULL, pubsub_cb, sub, subscription_setup_dialog(), and ast_sip_contact::uri.

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 2920 of file res_pjsip_pubsub.c.

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

References ast_datastores_add(), and ast_sip_publication::datastores.

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 2925 of file res_pjsip_pubsub.c.

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

References ast_datastores_find(), ast_sip_publication::datastores, and 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 2935 of file res_pjsip_pubsub.c.

{
    return publication->datastores;
}

References ast_sip_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 3694 of file res_pjsip_pubsub.c.

{
    return pub->endpoint;
}

References ast_sip_publication::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 3704 of file res_pjsip_pubsub.c.

{
    return pub->event_configuration_name;
}

References ast_sip_publication::event_configuration_name.

Referenced by asterisk_publication_devicestate_state_change(), and asterisk_publication_mwi_state_change().

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 3699 of file res_pjsip_pubsub.c.

{
    return pub->resource;
}

References ast_sip_publication::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 2930 of file res_pjsip_pubsub.c.

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

References ast_datastores_remove(), ast_sip_publication::datastores, and 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 3793 of file res_pjsip_pubsub.c.

{
    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;
}

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, ast_sip_pubsub_body_generator::list, LOG_WARNING, str, 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, type, 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().

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 3709 of file res_pjsip_pubsub.c.

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

References find_body_generator_type_subtype(), and type.

Referenced by publisher_start().

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 3714 of file res_pjsip_pubsub.c.

{
    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;
}

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

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

supplement

Body generator to register

Return values

0	Success
-1	Failure

Definition at line 3759 of file res_pjsip_pubsub.c.

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

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

Referenced by load_module().

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 3744 of file res_pjsip_pubsub.c.

{
    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);
}

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

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

supplement

Body generator to unregister

Definition at line 3768 of file res_pjsip_pubsub.c.

{
    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);
}

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

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 2989 of file res_pjsip_pubsub.c.

{
    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;
}

References AO2_ALLOC_OPT_LOCK_MUTEX, ao2_container_alloc_hash, ast_log, ast_strlen_zero(), handler(), LOG_ERROR, NULL, publication_cmp_fn(), publication_hash_fn(), PUBLICATIONS_BUCKETS, and publish_add_handler().

Referenced by load_module().

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 3048 of file res_pjsip_pubsub.c.

{
    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;
}

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

Referenced by load_module().

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 2900 of file res_pjsip_pubsub.c.

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

References ast_datastores_add(), and ast_sip_subscription::datastores.

Referenced by add_datastore(), and add_mwi_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 2895 of file res_pjsip_pubsub.c.

{
    return ast_datastores_alloc_datastore(info, uid);
}

References ast_datastores_alloc_datastore(), sip_to_pjsip::info(), and ast_datastore::uid.

Referenced by add_datastore(), and add_mwi_datastore().

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

Definition at line 1636 of file res_pjsip_pubsub.c.

{
    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);
}

References ao2_cleanup, ast_debug, ast_sorcery_object_get_id(), and sub.

Referenced by exten_state_subscription_destructor(), and mwi_subscription_destructor().

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 3788 of file res_pjsip_pubsub.c.

{
    return sub->body_generator->subtype;
}

References sub.

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

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 3783 of file res_pjsip_pubsub.c.

{
    return sub->body_generator->type;
}

References sub.

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

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 2905 of file res_pjsip_pubsub.c.

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

References ast_datastores_find(), ast_sip_subscription::datastores, and name.

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

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 2915 of file res_pjsip_pubsub.c.

{
    return subscription->datastores;
}

References ast_sip_subscription::datastores.

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

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 2178 of file res_pjsip_pubsub.c.

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

References ast_assert, NULL, and sub.

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

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 2184 of file res_pjsip_pubsub.c.

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

References ao2_bump, ast_assert, NULL, and sub.

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

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 2102 of file res_pjsip_pubsub.c.

{
    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);
}

References ast_sip_mod_data_get, MOD_DATA_MSG, name, NULL, pubsub_module, and sub.

Referenced by get_user_agent().

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 2849 of file res_pjsip_pubsub.c.

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

References buf, and sub.

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

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 2957 of file res_pjsip_pubsub.c.

{
    return subscription->persistence_data;
}

References ast_sip_subscription::persistence_data.

Referenced by dialog_info_generate_body_content().

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 2854 of file res_pjsip_pubsub.c.

{
    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';
    }
}

References buf, sip_subscription_tree::dlg, and sub.

Referenced by exten_state_data_alloc(), and notify_task().

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 2867 of file res_pjsip_pubsub.c.

{
    return sub->resource;
}

References sub.

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

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 2190 of file res_pjsip_pubsub.c.

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

References ast_assert, NULL, and sub.

Referenced by exten_state_subscription_alloc(), and send_notify().

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 2844 of file res_pjsip_pubsub.c.

{
    return sub->uri;
}

References sub.

Referenced by mwi_get_notify_data(), and send_mwi_notify().

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 2872 of file res_pjsip_pubsub.c.

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

References sub.

Referenced by notify_task(), and state_changed().

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 2800 of file res_pjsip_pubsub.c.

{
    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;
}

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, schedule_notification(), send_notify(), SIP_SUB_TREE_NORMAL, SIP_SUB_TREE_TERMINATE_IN_PROGRESS, SIP_SUB_TREE_TERMINATE_PENDING, and sub.

Referenced by notify_task(), and send_mwi_notify().

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 2910 of file res_pjsip_pubsub.c.

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

References ast_datastores_remove(), ast_sip_subscription::datastores, and name.

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

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 2940 of file res_pjsip_pubsub.c.

{
    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));
    }
}

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

Referenced by dialog_info_generate_body_content().

ast_sip_unregister_publish_handler()

void ast_sip_unregister_publish_handler

(

struct ast_sip_publish_handler *

handler

)

Unregister a publish handler.

Definition at line 3009 of file res_pjsip_pubsub.c.

{
    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);
}

References ao2_cleanup, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, handler(), and ast_sip_publish_handler::next.

Referenced by load_module(), and unload_module().

ast_sip_unregister_subscription_handler()

void ast_sip_unregister_subscription_handler

(

struct ast_sip_subscription_handler *

handler

)

Unregister a subscription handler.

Definition at line 3081 of file res_pjsip_pubsub.c.

{
    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);
}

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

Referenced by unload_module().