mwi.h File Reference

Asterisk MWI API. More...

#include "asterisk/utils.h"
#include "asterisk/stasis_state.h"

Include dependency graph for mwi.h:

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

Go to the source code of this file.

Data Structures
struct	ast_mwi_blob
	Object that represents an MWI update with some additional application defined data. More...
struct	ast_mwi_observer
	MWI state event interface. More...
struct	ast_mwi_state
	The structure that contains MWI state. More...

Macros
#define	ast_delete_mwi_state(mailbox, context)    ast_delete_mwi_state_full(mailbox, context, NULL)
	Delete MWI state cached by stasis. More...
#define	AST_MAX_MAILBOX_UNIQUEID   (AST_MAX_EXTENSION + AST_MAX_CONTEXT + 2)
#define	ast_publish_mwi_state(mailbox, context, new_msgs, old_msgs)    ast_publish_mwi_state_full(mailbox, context, new_msgs, old_msgs, NULL, NULL)
	Publish a MWI state update via stasis. More...
#define	ast_publish_mwi_state_channel(mailbox, context, new_msgs, old_msgs, channel_id)    ast_publish_mwi_state_full(mailbox, context, new_msgs, old_msgs, channel_id, NULL)
	Publish a MWI state update associated with some channel. More...

Typedefs
typedef int(*	on_mwi_state) (struct ast_mwi_state *mwi_state, void *data)
	The delegate called for each managed mailbox state. More...

Functions
int	ast_delete_mwi_state_full (const char *mailbox, const char *context, struct ast_eid *eid)
	Delete MWI state cached by stasis with all parameters. More...
int	ast_mwi_add_observer (struct ast_mwi_observer *observer)
	Add an observer to receive MWI state related events. More...
struct ast_mwi_publisher *	ast_mwi_add_publisher (const char *mailbox)
	Add an MWI state publisher to the mailbox. More...
struct ast_mwi_subscriber *	ast_mwi_add_subscriber (const char *mailbox)
	Add an MWI state subscriber to the mailbox. More...
struct stasis_message *	ast_mwi_blob_create (struct ast_mwi_state *mwi_state, struct stasis_message_type *message_type, struct ast_json *blob)
	Creates a ast_mwi_blob message. More...
struct ast_mwi_state *	ast_mwi_create (const char *mailbox, const char *context)
	Create a ast_mwi_state object. More...
int	ast_mwi_publish (struct ast_mwi_publisher *publisher, int urgent_msgs, int new_msgs, int old_msgs, const char *channel_id, struct ast_eid *eid)
	Publish MWI for the given mailbox. More...
int	ast_mwi_publish_by_mailbox (const char *mailbox, const char *context, int urgent_msgs, int new_msgs, int old_msgs, const char *channel_id, struct ast_eid *eid)
	Publish MWI for the given mailbox. More...
void	ast_mwi_remove_observer (struct ast_mwi_observer *observer)
	Remove an MWI state observer. More...
struct stasis_cache *	ast_mwi_state_cache (void)
	Backend cache for ast_mwi_topic_cached(). More...
void	ast_mwi_state_callback_all (on_mwi_state handler, void *data)
	For each managed mailbox call the given handler. More...
void	ast_mwi_state_callback_subscribed (on_mwi_state handler, void *data)
	For each managed mailbox that has a subscriber call the given handler. More...
struct stasis_message_type *	ast_mwi_state_type (void)
	Get the Stasis Message Bus API message type for MWI messages. More...
struct ast_mwi_subscriber *	ast_mwi_subscribe_pool (const char *mailbox, stasis_subscription_cb callback, void *data)
	Add an MWI state subscriber, and stasis subscription to the mailbox. More...
struct ast_mwi_state *	ast_mwi_subscriber_data (struct ast_mwi_subscriber *sub)
	Retrieves the state data object associated with the MWI subscriber. More...
struct stasis_subscription *	ast_mwi_subscriber_subscription (struct ast_mwi_subscriber *sub)
	Retrieve the stasis MWI topic subscription if available. More...
struct stasis_topic *	ast_mwi_subscriber_topic (struct ast_mwi_subscriber *sub)
	Retrieves the MWI subscriber's topic. More...
struct stasis_topic *	ast_mwi_topic (const char *uniqueid)
	Get the Stasis Message Bus API topic for MWI messages on a unique ID. More...
struct stasis_topic *	ast_mwi_topic_all (void)
	Get the Stasis Message Bus API topic for MWI messages. More...
struct stasis_topic *	ast_mwi_topic_cached (void)
	Get the Stasis Message Bus API caching topic for MWI messages. More...
void *	ast_mwi_unsubscribe (struct ast_mwi_subscriber *sub)
	Unsubscribe from the stasis topic and MWI. More...
void *	ast_mwi_unsubscribe_and_join (struct ast_mwi_subscriber *sub)
	Unsubscribe from the stasis topic, block until the final message is received, and then unsubscribe from MWI. More...
struct stasis_message_type *	ast_mwi_vm_app_type (void)
	Get the Stasis Message Bus API message type for voicemail application specific messages. More...
int	ast_publish_mwi_state_full (const char *mailbox, const char *context, int new_msgs, int old_msgs, const char *channel_id, struct ast_eid *eid)
	Publish a MWI state update via stasis with all parameters. More...
int	mwi_init (void)
	Initialize the mwi core. More...

Detailed Description

Asterisk MWI API.

Intro

This module manages, and processes all things MWI. Defined are mechanisms for subscribing and publishing to MWI topics. User modules wishing to receive MWI updates for a particular mailbox should do so by adding an MWI subscriber to that mailbox, followed by subscribing to the mailbox's topic. Likewise, user modules that want to publish MWI updates about a particular mailbox should first add a publisher for that mailbox prior to publishing.

MWI state is managed via an underlying stasis_state_manager (if interested see the stasis_state.c module for the gory details). As such all last known mailbox state can be retrieve and iterated over by using the ast_mwi_subscribe_pool function.

ast_mwi_subscriber

Created via ast_mwi_add_subscriber, a subscriber subscribes to a given mailbox in order to receive updates about the given mailbox. Adding a subscriber will create the underlying topic, and associated state data if those do not already exist for it. The topic, and last known state data is guaranteed to exist for the lifetime of the subscriber. State data can be NULL if nothing has been published to the mailbox's topic yet.

NOTE, currently adding a subscriber here will either create, or add a reference to the underlying stasis state (and associated topic). However, it does not actually subscribe to the stasis topic itself. You still need to explicitly call stasis_subscribe, or similar on the topic if you wish to receive published event updates.

So given that when subscribing to an MWI topic the following order should be adhered to:

1. Add an MWI state subscriber using ast_mwi_add_subscriber
2. Retrieve the topic from the subscriber using ast_mwi_subscriber_topic
3. Subscribe to the topic itself using stasis_subscribe or stasis_subscribe_pool

Or simply call ast_mwi_subscribe_pool, which combines those steps into a single call and returns the subscriber that is now subscribed to both the stasis topic and state.

Similarly, releasing the subscriber's reference removes a reference to the underlying state, but does not unsubscribe from the MWI topic. This should be done separately and prior to removing the subscriber's state reference:

1. Unsubscribe from the stasis topic subscription using stasis_unsubscribe or stasis_unsubscribe_and_join
2. Remove the MWI subscriber reference

Or call ast_mwi_unsubscribe (or _and_join), which combines those two steps into a single call.

ast_mwi_publisher

Before publishing to a particular topic a publisher should be created. This can be achieved by using ast_mwi_add_publisher. Publishing to a mailbox should then be done using the ast_mwi_publish function. This ensures the message is published to the appropriate topic, and the last known state is maintained.

Publishing by mailbox id alone is also allowed. However, it is not recommended to do so, and exists mainly for backwards compatibility, and legacy subsystems. If, and when this method of publishing is employed a call to one of the ast_delete_mwi_state functions should also be called for a given mailbox id after no more publishing will be done for that id. Otherwise a memory leak on the underlying stasis_state object will occur.

ast_mwi_observer

Add an observer in order to watch for particular MWI module related events. For instance if a submodule needs to know when a subscription is added to any mailbox an observer can be added to watch for that.

Definition in file mwi.h.

Macro Definition Documentation

ast_delete_mwi_state

#define ast_delete_mwi_state	(		mailbox,
			context
	)		ast_delete_mwi_state_full(mailbox, context, NULL)

Delete MWI state cached by stasis.

Since

12.2.0

Parameters

[in]	mailbox	The mailbox identifier string.
[in]	context	The context this mailbox resides in (NULL or "" if only using mailbox)

Return values

0	Success
-1	Failure

Definition at line 431 of file mwi.h.

AST_MAX_MAILBOX_UNIQUEID

#define AST_MAX_MAILBOX_UNIQUEID   (AST_MAX_EXTENSION + AST_MAX_CONTEXT + 2)

Definition at line 572 of file mwi.h.

ast_publish_mwi_state

#define ast_publish_mwi_state	(		mailbox,
			context,
			new_msgs,
			old_msgs
	)		ast_publish_mwi_state_full(mailbox, context, new_msgs, old_msgs, NULL, NULL)

Publish a MWI state update via stasis.

Since

12

Parameters

[in]	mailbox	The mailbox identifier string.
[in]	context	The context this mailbox resides in (NULL or "" if only using mailbox)
[in]	new_msgs	The number of new messages in this mailbox
[in]	old_msgs	The number of old messages in this mailbox

Return values

0	Success
-1	Failure

Definition at line 378 of file mwi.h.

ast_publish_mwi_state_channel

#define ast_publish_mwi_state_channel	(		mailbox,
			context,
			new_msgs,
			old_msgs,
			channel_id
	)		ast_publish_mwi_state_full(mailbox, context, new_msgs, old_msgs, channel_id, NULL)

Publish a MWI state update associated with some channel.

Since

12

Parameters

[in]	mailbox	The mailbox identifier string.
[in]	context	The context this mailbox resides in (NULL or "" if only using mailbox)
[in]	new_msgs	The number of new messages in this mailbox
[in]	old_msgs	The number of old messages in this mailbox
[in]	channel_id	A unique identifier for a channel associated with this change in mailbox state

Return values

0	Success
-1	Failure

Definition at line 395 of file mwi.h.

Typedef Documentation

on_mwi_state

typedef int(* on_mwi_state) (struct ast_mwi_state *mwi_state, void *data)

The delegate called for each managed mailbox state.

Parameters

mwi_state	The mwi state object
data	User data passed in by the initiator

Return values

0	to continue traversing
CMP_STOP	(2) to stop traversing

Since

13.28.0

16.5.0

Definition at line 301 of file mwi.h.

Function Documentation

ast_delete_mwi_state_full()

int ast_delete_mwi_state_full	(	const char *	mailbox,
		const char *	context,
		struct ast_eid *	eid
	)

Delete MWI state cached by stasis with all parameters.

Since

12.2.0

Parameters

[in]	mailbox	The mailbox identifier string.
[in]	context	The context this mailbox resides in (NULL or "" if only using mailbox)
[in]	eid	The EID of the server that originally published the message

Return values

0	Success
-1	Failure

Definition at line 404 of file mwi.c.

{
    RAII_VAR(struct stasis_message *, msg, NULL, ao2_cleanup);
    struct stasis_message *cached_msg;
    struct stasis_message *clear_msg;
    struct ast_mwi_state *mwi_state;
 
    msg = mwi_state_create_message(mailbox, context, 0, 0, 0, NULL, eid);
    if (!msg) {
        return -1;
    }
 
    mwi_state = stasis_message_data(msg);
 
    /*
     * XXX As far as stasis is concerned, all MWI events are local.
     *
     * For now, it is assumed that there is only one entity
     * maintaining the state of a particular mailbox.
     *
     * If we ever have multiple MWI event entities maintaining
     * the same mailbox that wish to delete their cached entry
     * we will need to do something about the race condition
     * potential between checking the cache and removing the
     * cache entry.
     */
    cached_msg = stasis_cache_get_by_eid(ast_mwi_state_cache(),
        ast_mwi_state_type(), mwi_state->uniqueid, &ast_eid_default);
    if (!cached_msg) {
        /* Nothing to clear from the cache, but still need to remove state */
        stasis_state_remove_publish_by_id(mwi_state_manager, mwi_state->uniqueid, eid, NULL);
        return -1;
    }
    ao2_cleanup(cached_msg);
 
    clear_msg = stasis_cache_clear_create(msg);
    stasis_state_remove_publish_by_id(mwi_state_manager, mwi_state->uniqueid, eid, clear_msg);
    ao2_cleanup(clear_msg);
 
    return 0;
}

References ao2_cleanup, ast_eid_default, ast_mwi_state_cache(), ast_mwi_state_type(), voicemailpwcheck::context, ast_mwi_state::eid, voicemailpwcheck::mailbox, mwi_state_create_message(), mwi_state_manager, NULL, RAII_VAR, stasis_cache_clear_create(), stasis_cache_get_by_eid(), stasis_message_data(), stasis_state_remove_publish_by_id(), and ast_mwi_state::uniqueid.

Referenced by free_user_final(), and mwi_handle_unsubscribe2().

ast_mwi_add_observer()

int ast_mwi_add_observer

(

struct ast_mwi_observer *

observer

)

Add an observer to receive MWI state related events.

Parameters

observer

The observer handling events

Return values

0	if successfully registered
-1	otherwise

Since

13.28.0

16.5.0

Definition at line 301 of file mwi.c.

{
    return stasis_state_add_observer(mwi_state_manager,
        (struct stasis_state_observer *)observer);
}

References mwi_state_manager, observer, and stasis_state_add_observer().

Referenced by start_poll_thread(), and subscriptions_create().

ast_mwi_add_publisher()

struct ast_mwi_publisher * ast_mwi_add_publisher

(

const char *

mailbox

)

Add an MWI state publisher to the mailbox.

Adding a publisher to a mailbox will create a stasis topic for the mailbox if one does not already exist. A publisher can be removed by releasing its reference. Doing so releases its underlying reference to the MWI state.

Parameters

mailbox

The mailbox id to publish to

Returns

An MWI publisher object

Return values

NULl

on error

Since

13.28.0

16.5.0

Definition at line 295 of file mwi.c.

{
    return (struct ast_mwi_publisher *)stasis_state_add_publisher(
        mwi_state_manager, mailbox);
}

References voicemailpwcheck::mailbox, mwi_state_manager, and stasis_state_add_publisher().

Referenced by publishers_create().

ast_mwi_add_subscriber()

struct ast_mwi_subscriber * ast_mwi_add_subscriber

(

const char *

mailbox

)

Add an MWI state subscriber to the mailbox.

Adding a subscriber to a mailbox will create a stasis topic for the mailbox if one does not already exist. It does not however subscribe to the topic itself. This is done separately using a call to stasis_subscribe or stasis_subscribe_pool.

A subscriber can be removed by releasing its reference. Doing so releases its underlying reference to the MWI state. It does not unsubscribe from the topic. Unsubscribing from a topic should be done prior to unsubscribing the state.

Parameters

mailbox

The subscription state mailbox id

Returns

An MWI subscriber object

Return values

NULL

on error

Since

13.28.0

16.5.0

Definition at line 229 of file mwi.c.

{
    return (struct ast_mwi_subscriber *)stasis_state_add_subscriber(
        mwi_state_manager, mailbox);
}

References voicemailpwcheck::mailbox, mwi_state_manager, and stasis_state_add_subscriber().

ast_mwi_blob_create()

struct stasis_message * ast_mwi_blob_create	(	struct ast_mwi_state *	mwi_state,
		struct stasis_message_type *	message_type,
		struct ast_json *	blob
	)

Creates a ast_mwi_blob message.

Since

12

The blob JSON object requires a "type" field describing the blob. It should also be treated as immutable and not modified after it is put into the message.

Parameters

mwi_state	MWI state associated with the update
message_type	The type of message to create
blob	JSON object representing the data.

Returns

ast_mwi_blob message.

Return values

NULL

on error

Definition at line 467 of file mwi.c.

{
    struct ast_mwi_blob *obj;
    struct stasis_message *msg;
 
    ast_assert(blob != NULL);
 
    if (!message_type) {
        return NULL;
    }
 
    obj = ao2_alloc(sizeof(*obj), mwi_blob_dtor);
    if (!obj) {
        return NULL;
    }
 
    obj->mwi_state = mwi_state;
    ao2_ref(obj->mwi_state, +1);
    obj->blob = ast_json_ref(blob);
 
    /* This is not a normal MWI event.  Only used by the MinivmNotify app. */
    msg = stasis_message_create(message_type, obj);
    ao2_ref(obj, -1);
 
    return msg;
}

References ao2_alloc, ao2_ref, ast_assert, ast_json_ref(), ast_mwi_blob::blob, mwi_blob_dtor(), ast_mwi_blob::mwi_state, NULL, and stasis_message_create().

Referenced by notify_new_message().

ast_mwi_create()

struct ast_mwi_state * ast_mwi_create	(	const char *	mailbox,
		const char *	context
	)

Create a ast_mwi_state object.

Since

12

Parameters

[in]	mailbox	The mailbox identifier string.
[in]	context	The context this mailbox resides in (NULL or "" if only using mailbox)

Returns

ast_mwi_state object on success

Return values

NULL

on error

Definition at line 152 of file mwi.c.

{
    return mwi_create_state(mailbox, context, 0, 0, 0);
}

References voicemailpwcheck::context, voicemailpwcheck::mailbox, and mwi_create_state().

Referenced by notify_new_message().

ast_mwi_publish()

int ast_mwi_publish	(	struct ast_mwi_publisher *	publisher,
		int	urgent_msgs,
		int	new_msgs,
		int	old_msgs,
		const char *	channel_id,
		struct ast_eid *	eid
	)

Publish MWI for the given mailbox.

Parameters

publisher	The publisher to publish a mailbox update on
urgent_msgs	The number of urgent messages in this mailbox
new_msgs	The number of new messages in this mailbox
old_msgs	The number of old messages in this mailbox
channel_id	A unique identifier for a channel associated with this change in mailbox state
eid	The EID of the server that originally published the message

Return values

0	on success
-1	on failure

Since

13.28.0

16.5.0

Definition at line 358 of file mwi.c.

{
    struct stasis_state_publisher *p = (struct stasis_state_publisher *)pub;
    struct stasis_message *msg = mwi_state_create_message(stasis_state_publisher_id(p),
        NULL, urgent_msgs, new_msgs, old_msgs, channel_id, eid);
 
    if (!msg) {
        return -1;
    }
 
    stasis_state_publish(p, msg);
    ao2_ref(msg, -1);
 
    return 0;
}

References ao2_ref, stasis_message::eid, mwi_state_create_message(), NULL, stasis_state_publish(), and stasis_state_publisher_id().

Referenced by explicit_publish_cb().

ast_mwi_publish_by_mailbox()

int ast_mwi_publish_by_mailbox	(	const char *	mailbox,
		const char *	context,
		int	urgent_msgs,
		int	new_msgs,
		int	old_msgs,
		const char *	channel_id,
		struct ast_eid *	eid
	)

Publish MWI for the given mailbox.

Parameters

mailbox	The mailbox identifier string.
context	The context this mailbox resides in (NULL or "" if only using mailbox)
urgent_msgs	The number of urgent messages in this mailbox
new_msgs	The number of new messages in this mailbox
old_msgs	The number of old messages in this mailbox
channel_id	A unique identifier for a channel associated with this change in mailbox state
eid	The EID of the server that originally published the message

Return values

0	on success
-1	on failure

Since

13.28.0

16.5.0

Definition at line 375 of file mwi.c.

{
    struct ast_mwi_state *mwi_state;
    struct stasis_message *msg = mwi_state_create_message(
        mailbox, context, urgent_msgs, new_msgs, old_msgs, channel_id, eid);
 
    if (!msg) {
        return -1;
    }
 
    mwi_state = stasis_message_data(msg);
    stasis_state_publish_by_id(mwi_state_manager, mwi_state->uniqueid, NULL, msg);
    ao2_ref(msg, -1);
 
    return 0;
}

References ao2_ref, voicemailpwcheck::context, stasis_message::eid, voicemailpwcheck::mailbox, mwi_state_create_message(), mwi_state_manager, NULL, stasis_message_data(), stasis_state_publish_by_id(), and ast_mwi_state::uniqueid.

Referenced by ast_publish_mwi_state_full(), and implicit_publish_cb().

ast_mwi_remove_observer()

void ast_mwi_remove_observer

(

struct ast_mwi_observer *

observer

)

Remove an MWI state observer.

Parameters

observer

The observer being removed

Since

13.28.0

16.5.0

Definition at line 307 of file mwi.c.

{
    stasis_state_remove_observer(mwi_state_manager,
        (struct stasis_state_observer *)observer);
}

References mwi_state_manager, observer, and stasis_state_remove_observer().

Referenced by stop_poll_thread(), and subscriptions_destroy().

ast_mwi_state_cache()

struct stasis_cache * ast_mwi_state_cache

(

void

)

Backend cache for ast_mwi_topic_cached().

Returns

Cache of ast_mwi_state.

Definition at line 94 of file mwi.c.

{
    return mwi_state_cache;
}

References mwi_state_cache.

Referenced by ast_delete_mwi_state_full(), asterisk_publication_mwi_refresh(), asterisk_start_mwi_publishing(), has_voicemail(), load_module(), unistim_send_mwi_to_peer(), and update_registry().

ast_mwi_state_callback_all()

void ast_mwi_state_callback_all	(	on_mwi_state	handler,
		void *	data
	)

For each managed mailbox call the given handler.

Parameters

handler	The mwi state handler to call for each managed mailbox
data	User to data to pass on to the handler

Since

13.28.0

16.5.0

Definition at line 338 of file mwi.c.

{
    struct mwi_handler_data d = {
        .handler = handler,
        .data = data
    };
 
    stasis_state_callback_all(mwi_state_manager, handle_mwi_state, &d);
}

References d, mwi_handler_data::data, handle_mwi_state(), handler(), mwi_state_manager, and stasis_state_callback_all().

Referenced by actual_load_config(), manager_voicemail_refresh(), publish(), and unload_module().

ast_mwi_state_callback_subscribed()

void ast_mwi_state_callback_subscribed	(	on_mwi_state	handler,
		void *	data
	)

For each managed mailbox that has a subscriber call the given handler.

Parameters

handler	The mwi state handler to call for each managed mailbox
data	User to data to pass on to the handler

Since

13.28.0

16.5.0

Definition at line 348 of file mwi.c.

{
    struct mwi_handler_data d = {
        .handler = handler,
        .data = data
    };
 
    stasis_state_callback_subscribed(mwi_state_manager, handle_mwi_state, &d);
}

References d, mwi_handler_data::data, handle_mwi_state(), handler(), mwi_state_manager, and stasis_state_callback_subscribed().

Referenced by mb_poll_thread().

ast_mwi_state_type()

struct stasis_message_type * ast_mwi_state_type

(

void

)

Get the Stasis Message Bus API message type for MWI messages.

Returns

The message type structure for MWI messages

Return values

NULL

on error

Since

12

Referenced by ast_delete_mwi_state_full(), ast_mwi_subscribe_pool(), asterisk_publisher_mwistate_cb(), asterisk_start_mwi_publishing(), has_voicemail(), load_module(), manager_mwi_init(), mwi_cleanup(), mwi_init(), mwi_stasis_cb(), mwi_state_create_message(), mwi_state_get_id(), mwi_update_cb(), unistim_send_mwi_to_peer(), update_registry(), xmpp_init_event_distribution(), and xmpp_pubsub_mwi_cb().

ast_mwi_subscribe_pool()

struct ast_mwi_subscriber * ast_mwi_subscribe_pool	(	const char *	mailbox,
		stasis_subscription_cb	callback,
		void *	data
	)

Add an MWI state subscriber, and stasis subscription to the mailbox.

Adding a subscriber to a mailbox will create a stasis topic for the mailbox if one does not already exist. Once successfully create the underlying stasis topic is then subscribed to as well.

A subscriber can be removed by releasing its reference. Doing so releases its underlying reference to the MWI state. It does not unsubscribe from the topic. Unsubscribing from a topic should be done prior to unsubscribing the state.

Parameters

mailbox	The subscription state mailbox id
callback	The stasis subscription callback
data	A user data object passed to the stasis subscription

Returns

An MWI subscriber object

Return values

NULL

on error

Since

13.28.0

16.5.0

Definition at line 235 of file mwi.c.

{
    struct stasis_subscription *stasis_sub;
    struct ast_mwi_subscriber *sub = (struct ast_mwi_subscriber *)stasis_state_subscribe_pool(
        mwi_state_manager, mailbox, callback, data);
 
    if (!sub) {
        return NULL;
    }
 
    stasis_sub = ast_mwi_subscriber_subscription(sub);
 
    stasis_subscription_accept_message_type(stasis_sub, ast_mwi_state_type());
    stasis_subscription_set_filter(stasis_sub, STASIS_SUBSCRIPTION_FILTER_SELECTIVE);
 
    return sub;
}

References ast_mwi_state_type(), ast_mwi_subscriber_subscription(), voicemailpwcheck::mailbox, mwi_state_manager, NULL, stasis_state_subscribe_pool(), stasis_subscription_accept_message_type(), STASIS_SUBSCRIPTION_FILTER_SELECTIVE, stasis_subscription_set_filter(), and sub.

Referenced by build_peer(), mkintf(), mwi_stasis_subscription_alloc(), and subscriptions_create().

ast_mwi_subscriber_data()

struct ast_mwi_state * ast_mwi_subscriber_data

(

struct ast_mwi_subscriber *

sub

)

Retrieves the state data object associated with the MWI subscriber.

Note

Returned data's reference count is incremented

Parameters

sub	An MWI subscriber

Returns

The state data object

Since

13.28.0

16.5.0

Definition at line 269 of file mwi.c.

{
    struct stasis_state_subscriber *s = (struct stasis_state_subscriber *)sub;
    struct ast_mwi_state *mwi_state = stasis_state_subscriber_data(s);
 
    return mwi_state ?: mwi_retrieve_then_create_state(stasis_state_subscriber_id(s));
}

References mwi_retrieve_then_create_state(), stasis_state_subscriber_data(), stasis_state_subscriber_id(), and sub.

Referenced by get_message_count(), handle_validate(), mwi_handle_subscribe(), and mwi_handle_unsubscribe().

ast_mwi_subscriber_subscription()

struct stasis_subscription * ast_mwi_subscriber_subscription

(

struct ast_mwi_subscriber *

sub

)

Retrieve the stasis MWI topic subscription if available.

Parameters

sub	An MWI subscriber

Returns

The subscriber's stasis subscription

Return values

NULL	if no subscription available

Since

13.28.0

16.5.0

Definition at line 277 of file mwi.c.

{
    return stasis_state_subscriber_subscription((struct stasis_state_subscriber *)sub);
}

References stasis_state_subscriber_subscription(), and sub.

Referenced by ast_mwi_subscribe_pool(), and mwi_stasis_subscription_alloc().

ast_mwi_subscriber_topic()

struct stasis_topic * ast_mwi_subscriber_topic

(

struct ast_mwi_subscriber *

sub

)

Retrieves the MWI subscriber's topic.

Note

Returned topic's reference count is NOT incremented. However, the topic is guaranteed to live for the lifetime of the subscriber.

Parameters

sub	An MWI subscriber

Returns

A stasis topic subscribed to by the subscriber

Since

13.28.0

16.5.0

Definition at line 264 of file mwi.c.

{
    return stasis_state_subscriber_topic((struct stasis_state_subscriber *)sub);
}

References stasis_state_subscriber_topic(), and sub.

ast_mwi_topic()

struct stasis_topic * ast_mwi_topic

(

const char *

uniqueid

)

Get the Stasis Message Bus API topic for MWI messages on a unique ID.

Parameters

uniqueid

The unique id for which to get the topic

Returns

The topic structure for MWI messages for a given uniqueid

Return values

NULL	if it failed to be found or allocated

Since

12

Definition at line 104 of file mwi.c.

{
    return stasis_state_topic(mwi_state_manager, uniqueid);
}

References mwi_state_manager, and stasis_state_topic().

Referenced by notify_new_message().

ast_mwi_topic_all()

struct stasis_topic * ast_mwi_topic_all

(

void

)

Get the Stasis Message Bus API topic for MWI messages.

Returns

The topic structure for MWI messages

Return values

NULL	if it has not been allocated

Since

12

Definition at line 89 of file mwi.c.

{
    return stasis_state_all_topic(mwi_state_manager);
}

References mwi_state_manager, and stasis_state_all_topic().

Referenced by asterisk_start_mwi_publishing(), load_module(), manager_mwi_init(), mwi_init(), and xmpp_init_event_distribution().

ast_mwi_topic_cached()

struct stasis_topic * ast_mwi_topic_cached

(

void

)

Get the Stasis Message Bus API caching topic for MWI messages.

Returns

The caching topic structure for MWI messages

Return values

NULL	if it has not been allocated

Since

12

Definition at line 99 of file mwi.c.

{
    return stasis_caching_get_topic(mwi_topic_cached);
}

References mwi_topic_cached, and stasis_caching_get_topic().

ast_mwi_unsubscribe()

void * ast_mwi_unsubscribe

(

struct ast_mwi_subscriber *

sub

)

Unsubscribe from the stasis topic and MWI.

Parameters

sub	An MWI subscriber

Since

13.28.0

16.5.0

Definition at line 254 of file mwi.c.

{
    return stasis_state_unsubscribe((struct stasis_state_subscriber *)sub);
}

References stasis_state_unsubscribe(), and sub.

Referenced by destroy_dahdi_pvt(), and peer_destructor().

ast_mwi_unsubscribe_and_join()

void * ast_mwi_unsubscribe_and_join

(

struct ast_mwi_subscriber *

sub

)

Unsubscribe from the stasis topic, block until the final message is received, and then unsubscribe from MWI.

Parameters

sub	An MWI subscriber

Since

13.28.0

16.5.0

Definition at line 259 of file mwi.c.

{
    return stasis_state_unsubscribe_and_join((struct stasis_state_subscriber *)sub);
}

References stasis_state_unsubscribe_and_join(), and sub.

Referenced by subscriptions_destroy(), and unsubscribe_stasis().

ast_mwi_vm_app_type()

struct stasis_message_type * ast_mwi_vm_app_type

(

void

)

Get the Stasis Message Bus API message type for voicemail application specific messages.

This message type exists for those messages a voicemail application may wish to send that have no logical relationship with other voicemail applications. Voicemail apps that use this message type must pass a ast_mwi_blob. Any extraneous information in the JSON blob must be packed as key/value pair tuples of strings.

At least one key/value tuple must have a key value of "Event".

Returns

The stasis_message_type for voicemail application specific messages

Return values

NULL

on error

Since

12

Referenced by manager_mwi_init(), mwi_cleanup(), mwi_init(), and notify_new_message().

ast_publish_mwi_state_full()

int ast_publish_mwi_state_full	(	const char *	mailbox,
		const char *	context,
		int	new_msgs,
		int	old_msgs,
		const char *	channel_id,
		struct ast_eid *	eid
	)

Publish a MWI state update via stasis with all parameters.

Since

12

Parameters

[in]	mailbox	The mailbox identifier string.
[in]	context	The context this mailbox resides in (NULL or "" if only using mailbox)
[in]	new_msgs	The number of new messages in this mailbox
[in]	old_msgs	The number of old messages in this mailbox
[in]	channel_id	A unique identifier for a channel associated with this change in mailbox state
[in]	eid	The EID of the server that originally published the message

Return values

0	Success
-1	Failure

Definition at line 393 of file mwi.c.

{
    return ast_mwi_publish_by_mailbox(mailbox, context, 0, new_msgs, old_msgs, channel_id, eid);
}

References ast_mwi_publish_by_mailbox(), voicemailpwcheck::context, stasis_message::eid, and voicemailpwcheck::mailbox.

Referenced by asterisk_publication_mailboxstate(), publish_mwi_to_stasis(), and xmpp_pubsub_handle_event().

mwi_init()

int mwi_init

(

void

)

Initialize the mwi core.

Return values

0	Success
-1	Failure

Since

13.27.0

16.4.0

Definition at line 507 of file mwi.c.

{
    ast_register_cleanup(mwi_cleanup);
 
    if (STASIS_MESSAGE_TYPE_INIT(ast_mwi_state_type) != 0) {
        return -1;
    }
 
    if (STASIS_MESSAGE_TYPE_INIT(ast_mwi_vm_app_type) != 0) {
        return -1;
    }
 
    mwi_state_manager = stasis_state_manager_create("mwi:all");
    if (!mwi_state_manager) {
        return -1;
    }
 
    mwi_state_cache = stasis_cache_create(mwi_state_get_id);
    if (!mwi_state_cache) {
        return -1;
    }
 
    mwi_topic_cached = stasis_caching_topic_create(ast_mwi_topic_all(), mwi_state_cache);
    if (!mwi_topic_cached) {
        return -1;
    }
 
    return 0;
}

References ast_mwi_state_type(), ast_mwi_topic_all(), ast_mwi_vm_app_type(), ast_register_cleanup(), mwi_cleanup(), mwi_state_cache, mwi_state_get_id(), mwi_state_manager, mwi_topic_cached, stasis_cache_create(), stasis_caching_topic_create(), STASIS_MESSAGE_TYPE_INIT, and stasis_state_manager_create().

Referenced by asterisk_daemon().