Asterisk - The Open Source Telephony Project
21.4.1
|
Asterisk MWI API. More...
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... | |
Asterisk MWI API.
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.
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:
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:
Or call ast_mwi_unsubscribe (or _and_join), which combines those two steps into a single call.
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.
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.
#define ast_delete_mwi_state | ( | mailbox, | |
context | |||
) | ast_delete_mwi_state_full(mailbox, context, NULL) |
#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.
[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 |
0 | Success |
-1 | Failure |
Definition at line 378 of file mwi.h.
Referenced by notify_message().
#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.
[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 |
0 | Success |
-1 | Failure |
typedef int(* on_mwi_state) (struct ast_mwi_state *mwi_state, void *data) |
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.
[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 |
0 | Success |
-1 | Failure |
Definition at line 404 of file mwi.c.
References ast_eid_default, ast_mwi_state_cache(), ast_mwi_state_type(), 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.
int ast_mwi_add_observer | ( | struct ast_mwi_observer * | observer | ) |
Add an observer to receive MWI state related events.
observer | The observer handling events |
0 | if successfully registered |
-1 | otherwise |
Definition at line 301 of file mwi.c.
References stasis_state_add_observer().
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.
mailbox | The mailbox id to publish to |
NULl | on error |
Definition at line 295 of file mwi.c.
References stasis_state_add_publisher().
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.
mailbox | The subscription state mailbox id |
NULL | on error |
Definition at line 229 of file mwi.c.
References stasis_state_add_subscriber().
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.
"type"
field describing the blob. It should also be treated as immutable and not modified after it is put into the message.mwi_state | MWI state associated with the update |
message_type | The type of message to create |
blob | JSON object representing the data. |
NULL | on error |
Definition at line 467 of file mwi.c.
References ao2_ref, ast_json_ref(), ast_mwi_blob::blob, ast_mwi_blob::mwi_state, and stasis_message_create().
struct ast_mwi_state* ast_mwi_create | ( | const char * | mailbox, |
const char * | context | ||
) |
Create a ast_mwi_state object.
[in] | mailbox | The mailbox identifier string. |
[in] | context | The context this mailbox resides in (NULL or "" if only using mailbox) |
NULL | on error |
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.
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 |
0 | on success |
-1 | on failure |
Definition at line 358 of file mwi.c.
References ao2_ref, stasis_state_publish(), and stasis_state_publisher_id().
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.
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 |
0 | on success |
-1 | on failure |
Definition at line 375 of file mwi.c.
References ao2_ref, stasis_message_data(), stasis_state_publish_by_id(), and ast_mwi_state::uniqueid.
Referenced by ast_publish_mwi_state_full().
void ast_mwi_remove_observer | ( | struct ast_mwi_observer * | observer | ) |
Remove an MWI state observer.
observer | The observer being removed |
Definition at line 307 of file mwi.c.
References stasis_state_remove_observer().
struct stasis_cache* ast_mwi_state_cache | ( | void | ) |
Backend cache for ast_mwi_topic_cached().
Definition at line 94 of file mwi.c.
Referenced by ast_delete_mwi_state_full(), and update_registry().
void ast_mwi_state_callback_all | ( | on_mwi_state | handler, |
void * | data | ||
) |
For each managed mailbox call the given handler.
handler | The mwi state handler to call for each managed mailbox |
data | User to data to pass on to the handler |
Definition at line 338 of file mwi.c.
References stasis_state_callback_all().
void ast_mwi_state_callback_subscribed | ( | on_mwi_state | handler, |
void * | data | ||
) |
For each managed mailbox that has a subscriber call the given handler.
handler | The mwi state handler to call for each managed mailbox |
data | User to data to pass on to the handler |
Definition at line 348 of file mwi.c.
References stasis_state_callback_subscribed().
struct stasis_message_type* ast_mwi_state_type | ( | void | ) |
Get the Stasis Message Bus API message type for MWI messages.
NULL | on error |
Referenced by ast_delete_mwi_state_full(), ast_mwi_subscribe_pool(), manager_mwi_init(), mwi_init(), update_registry(), xmpp_init_event_distribution(), and xmpp_pubsub_mwi_cb().
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.
mailbox | The subscription state mailbox id |
callback | The stasis subscription callback |
data | A user data object passed to the stasis subscription |
NULL | on error |
Definition at line 235 of file mwi.c.
References ast_mwi_state_type(), ast_mwi_subscriber_subscription(), stasis_state_subscribe_pool(), stasis_subscription_accept_message_type(), STASIS_SUBSCRIPTION_FILTER_SELECTIVE, and stasis_subscription_set_filter().
Referenced by build_peer(), and mkintf().
struct ast_mwi_state* ast_mwi_subscriber_data | ( | struct ast_mwi_subscriber * | sub | ) |
Retrieves the state data object associated with the MWI subscriber.
sub | An MWI subscriber |
Definition at line 269 of file mwi.c.
References stasis_state_subscriber_data(), and stasis_state_subscriber_id().
struct stasis_subscription* ast_mwi_subscriber_subscription | ( | struct ast_mwi_subscriber * | sub | ) |
Retrieve the stasis MWI topic subscription if available.
sub | An MWI subscriber |
NULL | if no subscription available |
Definition at line 277 of file mwi.c.
References stasis_state_subscriber_subscription().
Referenced by ast_mwi_subscribe_pool().
struct stasis_topic* ast_mwi_subscriber_topic | ( | struct ast_mwi_subscriber * | sub | ) |
Retrieves the MWI subscriber's topic.
sub | An MWI subscriber |
Definition at line 264 of file mwi.c.
References stasis_state_subscriber_topic().
struct stasis_topic* ast_mwi_topic | ( | const char * | uniqueid | ) |
Get the Stasis Message Bus API topic for MWI messages on a unique ID.
uniqueid | The unique id for which to get the topic |
NULL | if it failed to be found or allocated |
Definition at line 104 of file mwi.c.
References stasis_state_topic().
struct stasis_topic* ast_mwi_topic_all | ( | void | ) |
Get the Stasis Message Bus API topic for MWI messages.
NULL | if it has not been allocated |
Definition at line 89 of file mwi.c.
References stasis_state_all_topic().
Referenced by manager_mwi_init(), mwi_init(), and xmpp_init_event_distribution().
struct stasis_topic* ast_mwi_topic_cached | ( | void | ) |
Get the Stasis Message Bus API caching topic for MWI messages.
NULL | if it has not been allocated |
Definition at line 99 of file mwi.c.
References stasis_caching_get_topic().
void* ast_mwi_unsubscribe | ( | struct ast_mwi_subscriber * | sub | ) |
Unsubscribe from the stasis topic and MWI.
sub | An MWI subscriber |
Definition at line 254 of file mwi.c.
References stasis_state_unsubscribe().
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.
sub | An MWI subscriber |
Definition at line 259 of file mwi.c.
References stasis_state_unsubscribe_and_join().
Referenced by sig_pri_stop_pri().
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".
NULL | on error |
Referenced by manager_mwi_init(), and mwi_init().
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.
[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 |
0 | Success |
-1 | Failure |
Definition at line 393 of file mwi.c.
References ast_mwi_publish_by_mailbox().
Referenced by publish_mwi_to_stasis(), and xmpp_pubsub_handle_event().
int mwi_init | ( | void | ) |
Initialize the mwi core.
0 | Success |
-1 | Failure |
Definition at line 507 of file mwi.c.
References ast_mwi_state_type(), ast_mwi_topic_all(), ast_mwi_vm_app_type(), ast_register_cleanup(), stasis_cache_create(), stasis_caching_topic_create(), STASIS_MESSAGE_TYPE_INIT, and stasis_state_manager_create().