Asterisk - The Open Source Telephony Project  GIT-master-a24979a
Data Structures | Macros | Typedefs | Functions
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_publisherast_mwi_add_publisher (const char *mailbox)
 Add an MWI state publisher to the mailbox. More...
 
struct ast_mwi_subscriberast_mwi_add_subscriber (const char *mailbox)
 Add an MWI state subscriber to the mailbox. More...
 
struct stasis_messageast_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_stateast_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_cacheast_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_typeast_mwi_state_type (void)
 Get the Stasis Message Bus API message type for MWI messages. More...
 
struct ast_mwi_subscriberast_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_stateast_mwi_subscriber_data (struct ast_mwi_subscriber *sub)
 Retrieves the state data object associated with the MWI subscriber. More...
 
struct stasis_subscriptionast_mwi_subscriber_subscription (struct ast_mwi_subscriber *sub)
 Retrieve the stasis MWI topic subscription if available. More...
 
struct stasis_topicast_mwi_subscriber_topic (struct ast_mwi_subscriber *sub)
 Retrieves the MWI subscriber's topic. More...
 
struct stasis_topicast_mwi_topic (const char *uniqueid)
 Get the Stasis Message Bus API topic for MWI messages on a unique ID. More...
 
struct stasis_topicast_mwi_topic_all (void)
 Get the Stasis Message Bus API topic for MWI messages. More...
 
struct stasis_topicast_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_typeast_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]mailboxThe mailbox identifier string.
[in]contextThe context this mailbox resides in (NULL or "" if only using mailbox)
Return values
0Success
-1Failure

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]mailboxThe mailbox identifier string.
[in]contextThe context this mailbox resides in (NULL or "" if only using mailbox)
[in]new_msgsThe number of new messages in this mailbox
[in]old_msgsThe number of old messages in this mailbox
Return values
0Success
-1Failure

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]mailboxThe mailbox identifier string.
[in]contextThe context this mailbox resides in (NULL or "" if only using mailbox)
[in]new_msgsThe number of new messages in this mailbox
[in]old_msgsThe number of old messages in this mailbox
[in]channel_idA unique identifier for a channel associated with this change in mailbox state
Return values
0Success
-1Failure

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_stateThe mwi state object
dataUser data passed in by the initiator
Return values
0to 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]mailboxThe mailbox identifier string.
[in]contextThe context this mailbox resides in (NULL or "" if only using mailbox)
[in]eidThe EID of the server that originally published the message
Return values
0Success
-1Failure

Definition at line 404 of file mwi.c.

405 {
406  RAII_VAR(struct stasis_message *, msg, NULL, ao2_cleanup);
407  struct stasis_message *cached_msg;
408  struct stasis_message *clear_msg;
409  struct ast_mwi_state *mwi_state;
410 
411  msg = mwi_state_create_message(mailbox, context, 0, 0, 0, NULL, eid);
412  if (!msg) {
413  return -1;
414  }
415 
416  mwi_state = stasis_message_data(msg);
417 
418  /*
419  * XXX As far as stasis is concerned, all MWI events are local.
420  *
421  * For now, it is assumed that there is only one entity
422  * maintaining the state of a particular mailbox.
423  *
424  * If we ever have multiple MWI event entities maintaining
425  * the same mailbox that wish to delete their cached entry
426  * we will need to do something about the race condition
427  * potential between checking the cache and removing the
428  * cache entry.
429  */
432  if (!cached_msg) {
433  /* Nothing to clear from the cache, but still need to remove state */
435  return -1;
436  }
437  ao2_cleanup(cached_msg);
438 
439  clear_msg = stasis_cache_clear_create(msg);
441  ao2_cleanup(clear_msg);
442 
443  return 0;
444 }
#define ao2_cleanup(obj)
Definition: astobj2.h:1934
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:120
static char mailbox[AST_MAX_MAILBOX_UNIQUEID]
Definition: chan_mgcp.c:207
static struct stasis_state_manager * mwi_state_manager
Define Stasis Message Bus API topic objects.
Definition: mwi.c:33
struct stasis_cache * ast_mwi_state_cache(void)
Backend cache for ast_mwi_topic_cached().
Definition: mwi.c:94
static struct stasis_message * mwi_state_create_message(const char *mailbox, const char *context, int urgent_msgs, int new_msgs, int old_msgs, const char *channel_id, struct ast_eid *eid)
Definition: mwi.c:174
struct stasis_message_type * ast_mwi_state_type(void)
Get the Stasis Message Bus API message type for MWI messages.
#define NULL
Definition: resample.c:96
struct stasis_message * stasis_cache_clear_create(struct stasis_message *message)
A message which instructs the caching topic to remove an entry from its cache.
Definition: stasis_cache.c:778
struct stasis_message * stasis_cache_get_by_eid(struct stasis_cache *cache, struct stasis_message_type *type, const char *id, const struct ast_eid *eid)
Retrieve an item from the cache for a specific entity.
Definition: stasis_cache.c:659
void * stasis_message_data(const struct stasis_message *msg)
Get the data contained in a message.
void stasis_state_remove_publish_by_id(struct stasis_state_manager *manager, const char *id, const struct ast_eid *eid, struct stasis_message *msg)
Publish to a managed named by id topic, and remove an implicit publisher.
Definition: stasis_state.c:659
The structure that contains MWI state.
Definition: mwi.h:455
const ast_string_field uniqueid
Definition: mwi.h:458
struct ast_eid eid
Definition: mwi.h:463
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:936
struct ast_eid ast_eid_default
Global EID.
Definition: options.c:93

References ao2_cleanup, ast_eid_default, ast_mwi_state_cache(), ast_mwi_state_type(), context, ast_mwi_state::eid, 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
observerThe observer handling events
Return values
0if successfully registered
-1otherwise
Since
13.28.0
16.5.0

Definition at line 301 of file mwi.c.

302 {
304  (struct stasis_state_observer *)observer);
305 }
struct ast_sorcery_instance_observer observer
int stasis_state_add_observer(struct stasis_state_manager *manager, struct stasis_state_observer *observer)
Add an observer to receive managed state related events.
Definition: stasis_state.c:689
Managed stasis state event interface.
Definition: stasis_state.h:463

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
mailboxThe mailbox id to publish to
Returns
An MWI publisher object
Return values
NULlon error
Since
13.28.0
16.5.0

Definition at line 295 of file mwi.c.

296 {
299 }
struct stasis_state_publisher * stasis_state_add_publisher(struct stasis_state_manager *manager, const char *id)
Add a publisher to the managed state for the given id.
Definition: stasis_state.c:532

References 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
mailboxThe subscription state mailbox id
Returns
An MWI subscriber object
Return values
NULLon error
Since
13.28.0
16.5.0

Definition at line 229 of file mwi.c.

230 {
233 }
struct stasis_state_subscriber * stasis_state_add_subscriber(struct stasis_state_manager *manager, const char *id)
Add a subscriber to the managed stasis state for the given id.
Definition: stasis_state.c:413

References 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_stateMWI state associated with the update
message_typeThe type of message to create
blobJSON object representing the data.
Returns
ast_mwi_blob message.
Return values
NULLon error

Definition at line 467 of file mwi.c.

470 {
471  struct ast_mwi_blob *obj;
472  struct stasis_message *msg;
473 
474  ast_assert(blob != NULL);
475 
476  if (!message_type) {
477  return NULL;
478  }
479 
480  obj = ao2_alloc(sizeof(*obj), mwi_blob_dtor);
481  if (!obj) {
482  return NULL;
483  }
484 
485  obj->mwi_state = mwi_state;
486  ao2_ref(obj->mwi_state, +1);
487  obj->blob = ast_json_ref(blob);
488 
489  /* This is not a normal MWI event. Only used by the MinivmNotify app. */
490  msg = stasis_message_create(message_type, obj);
491  ao2_ref(obj, -1);
492 
493  return msg;
494 }
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
#define ao2_alloc(data_size, destructor_fn)
Definition: astobj2.h:409
struct ast_json * ast_json_ref(struct ast_json *value)
Increase refcount on value.
Definition: json.c:67
static void mwi_blob_dtor(void *obj)
Definition: mwi.c:459
struct stasis_message * stasis_message_create(struct stasis_message_type *type, void *data)
Create a new message.
Object that represents an MWI update with some additional application defined data.
Definition: mwi.h:471
struct ast_mwi_state * mwi_state
Definition: mwi.h:472
struct ast_json * blob
Definition: mwi.h:473
#define ast_assert(a)
Definition: utils.h:734

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]mailboxThe mailbox identifier string.
[in]contextThe context this mailbox resides in (NULL or "" if only using mailbox)
Returns
ast_mwi_state object on success
Return values
NULLon error

Definition at line 152 of file mwi.c.

153 {
154  return mwi_create_state(mailbox, context, 0, 0, 0);
155 }
static struct ast_mwi_state * mwi_create_state(const char *mailbox, const char *context, int urgent_msgs, int new_msgs, int old_msgs)
Definition: mwi.c:109

References context, 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
publisherThe publisher to publish a mailbox update on
urgent_msgsThe number of urgent messages in this mailbox
new_msgsThe number of new messages in this mailbox
old_msgsThe number of old messages in this mailbox
channel_idA unique identifier for a channel associated with this change in mailbox state
eidThe EID of the server that originally published the message
Return values
0on success
-1on failure
Since
13.28.0
16.5.0

Definition at line 358 of file mwi.c.

360 {
361  struct stasis_state_publisher *p = (struct stasis_state_publisher *)pub;
363  NULL, urgent_msgs, new_msgs, old_msgs, channel_id, eid);
364 
365  if (!msg) {
366  return -1;
367  }
368 
369  stasis_state_publish(p, msg);
370  ao2_ref(msg, -1);
371 
372  return 0;
373 }
const char * stasis_state_publisher_id(const struct stasis_state_publisher *pub)
Retrieve the publisher's underlying state's unique id.
Definition: stasis_state.c:553
void stasis_state_publish(struct stasis_state_publisher *pub, struct stasis_message *msg)
Publish to a managed state (topic) using a publisher.
Definition: stasis_state.c:563
struct ast_eid eid

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
mailboxThe mailbox identifier string.
contextThe context this mailbox resides in (NULL or "" if only using mailbox)
urgent_msgsThe number of urgent messages in this mailbox
new_msgsThe number of new messages in this mailbox
old_msgsThe number of old messages in this mailbox
channel_idA unique identifier for a channel associated with this change in mailbox state
eidThe EID of the server that originally published the message
Return values
0on success
-1on failure
Since
13.28.0
16.5.0

Definition at line 375 of file mwi.c.

377 {
378  struct ast_mwi_state *mwi_state;
380  mailbox, context, urgent_msgs, new_msgs, old_msgs, channel_id, eid);
381 
382  if (!msg) {
383  return -1;
384  }
385 
386  mwi_state = stasis_message_data(msg);
388  ao2_ref(msg, -1);
389 
390  return 0;
391 }
void stasis_state_publish_by_id(struct stasis_state_manager *manager, const char *id, const struct ast_eid *eid, struct stasis_message *msg)
Publish to a managed named by id topic, and add an implicit subscriber.
Definition: stasis_state.c:639

References ao2_ref, context, stasis_message::eid, 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
observerThe observer being removed
Since
13.28.0
16.5.0

Definition at line 307 of file mwi.c.

308 {
310  (struct stasis_state_observer *)observer);
311 }
void stasis_state_remove_observer(struct stasis_state_manager *manager, struct stasis_state_observer *observer)
Remove an observer (will no longer receive managed state related events).
Definition: stasis_state.c:701

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.

95 {
96  return mwi_state_cache;
97 }
static struct stasis_cache * mwi_state_cache
Definition: mwi.c:34

References mwi_state_cache.

Referenced by ast_delete_mwi_state_full(), asterisk_publication_mwi_refresh(), asterisk_start_mwi_publishing(), get_cached_mwi(), has_voicemail(), 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
handlerThe mwi state handler to call for each managed mailbox
dataUser to data to pass on to the handler
Since
13.28.0
16.5.0

Definition at line 338 of file mwi.c.

339 {
340  struct mwi_handler_data d = {
341  .handler = handler,
342  .data = data
343  };
344 
346 }
static int handle_mwi_state(const char *id, struct stasis_message *msg, void *user_data)
Definition: mwi.c:318
void stasis_state_callback_all(struct stasis_state_manager *manager, on_stasis_state handler, void *data)
For each managed state call the given handler.
Definition: stasis_state.c:741
void * data
Definition: mwi.c:315
static void handler(const char *name, int response_code, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
Definition: test_ari.c:59
static struct test_val 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
handlerThe mwi state handler to call for each managed mailbox
dataUser to data to pass on to the handler
Since
13.28.0
16.5.0

Definition at line 348 of file mwi.c.

349 {
350  struct mwi_handler_data d = {
351  .handler = handler,
352  .data = data
353  };
354 
356 }
void stasis_state_callback_subscribed(struct stasis_state_manager *manager, on_stasis_state handler, void *data)
For each managed, and explicitly subscribed state call the given handler.
Definition: stasis_state.c:764

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  )

◆ 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
mailboxThe subscription state mailbox id
callbackThe stasis subscription callback
dataA user data object passed to the stasis subscription
Returns
An MWI subscriber object
Return values
NULLon error
Since
13.28.0
16.5.0

Definition at line 235 of file mwi.c.

237 {
238  struct stasis_subscription *stasis_sub;
240  mwi_state_manager, mailbox, callback, data);
241 
242  if (!sub) {
243  return NULL;
244  }
245 
246  stasis_sub = ast_mwi_subscriber_subscription(sub);
247 
250 
251  return sub;
252 }
struct stasis_subscription * ast_mwi_subscriber_subscription(struct ast_mwi_subscriber *sub)
Retrieve the stasis MWI topic subscription if available.
Definition: mwi.c:277
struct stasis_forward * sub
Definition: res_corosync.c:240
@ STASIS_SUBSCRIPTION_FILTER_SELECTIVE
Definition: stasis.h:297
int stasis_subscription_accept_message_type(struct stasis_subscription *subscription, const struct stasis_message_type *type)
Indicate to a subscription that we are interested in a message type.
Definition: stasis.c:1025
int stasis_subscription_set_filter(struct stasis_subscription *subscription, enum stasis_subscription_message_filter filter)
Set the message type filtering level on a subscription.
Definition: stasis.c:1079
struct stasis_state_subscriber * stasis_state_subscribe_pool(struct stasis_state_manager *manager, const char *id, stasis_subscription_cb callback, void *data)
Add a subscriber, and subscribe to its underlying stasis topic.
Definition: stasis_state.c:447

References ast_mwi_state_type(), ast_mwi_subscriber_subscription(), 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 add_peer_mwi_subs(), build_gateway(), build_peer(), config_line(), 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
subAn MWI subscriber
Returns
The state data object
Since
13.28.0
16.5.0

Definition at line 269 of file mwi.c.

270 {
272  struct ast_mwi_state *mwi_state = stasis_state_subscriber_data(s);
273 
275 }
static struct ast_mwi_state * mwi_retrieve_then_create_state(const char *mailbox)
Definition: mwi.c:142
void * stasis_state_subscriber_data(struct stasis_state_subscriber *sub)
Retrieve the last known state stasis message payload for the subscriber.
Definition: stasis_state.c:498
const char * stasis_state_subscriber_id(const struct stasis_state_subscriber *sub)
Retrieve the underlying subscribed to state's unique id.
Definition: stasis_state.c:488

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
subAn MWI subscriber
Returns
The subscriber's stasis subscription
Return values
NULLif no subscription available
Since
13.28.0
16.5.0

Definition at line 277 of file mwi.c.

278 {
280 }
struct stasis_subscription * stasis_state_subscriber_subscription(struct stasis_state_subscriber *sub)
Retrieve the stasis topic subscription if available.
Definition: stasis_state.c:514

References stasis_state_subscriber_subscription(), and sub.

Referenced by add_peer_mwi_subs(), 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
subAn 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.

265 {
267 }
struct stasis_topic * stasis_state_subscriber_topic(struct stasis_state_subscriber *sub)
Retrieve the subscriber's topic.
Definition: stasis_state.c:493

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
uniqueidThe unique id for which to get the topic
Returns
The topic structure for MWI messages for a given uniqueid
Return values
NULLif it failed to be found or allocated
Since
12

Definition at line 104 of file mwi.c.

105 {
106  return stasis_state_topic(mwi_state_manager, uniqueid);
107 }
struct stasis_topic * stasis_state_topic(struct stasis_state_manager *manager, const char *id)
Retrieve a managed topic creating one if not currently managed.
Definition: stasis_state.c:370

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
NULLif it has not been allocated
Since
12

Definition at line 89 of file mwi.c.

90 {
92 }
struct stasis_topic * stasis_state_all_topic(struct stasis_state_manager *manager)
Retrieve the manager's topic (the topic that all state topics get forwarded to)
Definition: stasis_state.c:365

References mwi_state_manager, and stasis_state_all_topic().

Referenced by asterisk_start_mwi_publishing(), 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
NULLif it has not been allocated
Since
12

Definition at line 99 of file mwi.c.

100 {
102 }
static struct stasis_caching_topic * mwi_topic_cached
Definition: mwi.c:35
struct stasis_topic * stasis_caching_get_topic(struct stasis_caching_topic *caching_topic)
Returns the topic of cached events from a caching topics.
Definition: stasis_cache.c:85

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
subAn MWI subscriber
Since
13.28.0
16.5.0

Definition at line 254 of file mwi.c.

255 {
257 }
void * stasis_state_unsubscribe(struct stasis_state_subscriber *sub)
Unsubscribe from the stasis topic and stasis state.
Definition: stasis_state.c:471

References stasis_state_unsubscribe(), and sub.

Referenced by destroy_dahdi_pvt(), destroy_endpoint(), peer_destructor(), and skinny_reload().

◆ 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
subAn MWI subscriber
Since
13.28.0
16.5.0

Definition at line 259 of file mwi.c.

260 {
262 }
void * stasis_state_unsubscribe_and_join(struct stasis_state_subscriber *sub)
Unsubscribe from the stasis topic, block until the final message is received, and then unsubscribe fr...
Definition: stasis_state.c:478

References stasis_state_unsubscribe_and_join(), and sub.

Referenced by destroy_mailbox(), subscriptions_destroy(), unload_module(), 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
NULLon 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]mailboxThe mailbox identifier string.
[in]contextThe context this mailbox resides in (NULL or "" if only using mailbox)
[in]new_msgsThe number of new messages in this mailbox
[in]old_msgsThe number of old messages in this mailbox
[in]channel_idA unique identifier for a channel associated with this change in mailbox state
[in]eidThe EID of the server that originally published the message
Return values
0Success
-1Failure

Definition at line 393 of file mwi.c.

400 {
401  return ast_mwi_publish_by_mailbox(mailbox, context, 0, new_msgs, old_msgs, channel_id, eid);
402 }
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.
Definition: mwi.c:375

References ast_mwi_publish_by_mailbox(), context, stasis_message::eid, and 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
0Success
-1Failure
Since
13.27.0
16.4.0

Definition at line 507 of file mwi.c.

508 {
510 
512  return -1;
513  }
514 
516  return -1;
517  }
518 
520  if (!mwi_state_manager) {
521  return -1;
522  }
523 
525  if (!mwi_state_cache) {
526  return -1;
527  }
528 
530  if (!mwi_topic_cached) {
531  return -1;
532  }
533 
534  return 0;
535 }
int ast_register_cleanup(void(*func)(void))
Register a function to be executed before Asterisk gracefully exits.
Definition: clicompat.c:19
static const char * mwi_state_get_id(struct stasis_message *message)
Definition: mwi.c:446
struct stasis_topic * ast_mwi_topic_all(void)
Get the Stasis Message Bus API topic for MWI messages.
Definition: mwi.c:89
static void mwi_cleanup(void)
Definition: mwi.c:496
struct stasis_message_type * ast_mwi_vm_app_type(void)
Get the Stasis Message Bus API message type for voicemail application specific messages.
struct stasis_caching_topic * stasis_caching_topic_create(struct stasis_topic *original_topic, struct stasis_cache *cache)
Create a topic which monitors and caches messages from another topic.
Definition: stasis_cache.c:948
struct stasis_cache * stasis_cache_create(snapshot_get_id id_fn)
Create a cache.
Definition: stasis_cache.c:360
#define STASIS_MESSAGE_TYPE_INIT(name)
Boiler-plate messaging macro for initializing message types.
Definition: stasis.h:1493
struct stasis_state_manager * stasis_state_manager_create(const char *topic_name)
Create a stasis state manager.
Definition: stasis_state.c:325

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