stasis: Add internal filtering of messages.
[asterisk/asterisk.git] / include / asterisk / stasis.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * David M. Lee, II <dlee@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 #ifndef _ASTERISK_STASIS_H
20 #define _ASTERISK_STASIS_H
21
22 /*! \file
23  *
24  * \brief Stasis Message Bus API. See \ref stasis "Stasis Message Bus API" for
25  * detailed documentation.
26  *
27  * \author David M. Lee, II <dlee@digium.com>
28  * \since 12
29  *
30  * \page stasis Stasis Message Bus API
31  *
32  * \par Intro
33  *
34  * The Stasis Message Bus is a loosely typed mechanism for distributing messages
35  * within Asterisk. It is designed to be:
36  *  - Loosely coupled; new message types can be added in seperate modules.
37  *  - Easy to use; publishing and subscribing are straightforward operations.
38  *
39  * There are three main concepts for using the Stasis Message Bus:
40  *  - \ref stasis_message
41  *  - \ref stasis_topic
42  *  - \ref stasis_subscription
43  *
44  * \par stasis_message
45  *
46  * Central to the Stasis Message Bus is the \ref stasis_message, the messages
47  * that are sent on the bus. These messages have:
48  *  - a type (as defined by a \ref stasis_message_type)
49  *  - a value - a \c void pointer to an AO2 object
50  *  - a timestamp when it was created
51  *
52  * Once a \ref stasis_message has been created, it is immutable and cannot
53  * change. The same goes for the value of the message (although this cannot be
54  * enforced in code). Messages themselves are reference-counted, AO2 objects,
55  * along with their values. By being both reference counted and immutable,
56  * messages can be shared throughout the system without any concerns for
57  * threading.
58  *
59  * The type of a message is defined by an instance of \ref stasis_message_type,
60  * which can be created by calling stasis_message_type_create(). Message types
61  * are named, which is useful in debugging. It is recommended that the string
62  * name for a message type match the name of the struct that's stored in the
63  * message. For example, name for \ref stasis_cache_update's message type is \c
64  * "stasis_cache_update".
65  *
66  * \par stasis_topic
67  *
68  * A \ref stasis_topic is an object to which \ref stasis_subscriber's may be
69  * subscribed, and \ref stasis_message's may be published. Any message published
70  * to the topic is dispatched to all of its subscribers. The topic itself may be
71  * named, which is useful in debugging.
72  *
73  * Topics themselves are reference counted objects. Since topics are referred to
74  * by their subscibers, they will not be freed until all of their subscribers
75  * have unsubscribed. Topics are also thread safe, so no worries about
76  * publishing/subscribing/unsubscribing to a topic concurrently from multiple
77  * threads. It's also designed to handle the case of unsubscribing from a topic
78  * from within the subscription handler.
79  *
80  * \par Forwarding
81  *
82  * There is one special case of topics that's worth noting: forwarding
83  * messages. It's a fairly common use case to want to forward all the messages
84  * published on one topic to another one (for example, an aggregator topic that
85  * publishes all the events from a set of other topics). This can be
86  * accomplished easily using stasis_forward_all(). This sets up the forwarding
87  * between the two topics, and returns a \ref stasis_subscription, which can be
88  * unsubscribed to stop the forwarding.
89  *
90  * \par Caching
91  *
92  * Another common use case is to want to cache certain messages that are
93  * published on the bus. Usually these events are snapshots of the current state
94  * in the system, and it's desirable to query that state from the cache without
95  * locking the original object. It's also desirable for subscribers of the
96  * caching topic to receive messages that have both the old cache value and the
97  * new value being put into the cache. For this, we have stasis_cache_create()
98  * and stasis_caching_topic_create(), providing them with the topic which
99  * publishes the messages that you wish to cache, and a function that can
100  * identify cacheable messages.
101  *
102  * The \ref stasis_cache is designed so that it may be shared amongst several
103  * \ref stasis_caching_topic objects. This allows you to have individual caching
104  * topics per-object (i.e. so you can subscribe to updates for a single object),
105  * and still have a single cache to query for the state of all objects. While a
106  * cache may be shared amongst different message types, such a usage is probably
107  * not a good idea.
108  *
109  * The \ref stasis_cache can only be written to by \ref stasis_caching_topics.
110  * It's a thread safe container, so freely use the stasis_cache_get() and
111  * stasis_cache_dump() to query the cache.
112  *
113  * The \ref stasis_caching_topic discards non-cacheable messages. A cacheable
114  * message is wrapped in a \ref stasis_cache_update message which provides the
115  * old snapshot (or \c NULL if this is a new cache entry), and the new snapshot
116  * (or \c NULL if the entry was removed from the cache). A
117  * stasis_cache_clear_create() message must be sent to the topic in order to
118  * remove entries from the cache.
119  *
120  * In order to unsubscribe a \ref stasis_caching_topic from the upstream topic,
121  * call stasis_caching_unsubscribe(). Due to cyclic references, the \ref
122  * stasis_caching_topic will not be freed until after it has been unsubscribed,
123  * and all other ao2_ref()'s have been cleaned up.
124  *
125  * The \ref stasis_cache object is a normal AO2 managed object, which can be
126  * release with ao2_cleanup().
127  *
128  * \par stasis_subscriber
129  *
130  * Any topic may be subscribed to by simply providing stasis_subscribe() the
131  * \ref stasis_topic to subscribe to, a handler function and \c void pointer to
132  * data that is passed back to the handler. Invocations on the subscription's
133  * handler are serialized, but different invocations may occur on different
134  * threads (this usually isn't important unless you use thread locals or
135  * something similar).
136  *
137  * In order to stop receiving messages, call stasis_unsubscribe() with your \ref
138  * stasis_subscription. Due to cyclic references, the \ref
139  * stasis_subscription will not be freed until after it has been unsubscribed,
140  * and all other ao2_ref()'s have been cleaned up.
141  *
142  * \par Shutdown
143  *
144  * Subscriptions have two options for unsubscribing, depending upon the context
145  * in which you need to unsubscribe.
146  *
147  * If your subscription is owned by a module, and you must unsubscribe from the
148  * module_unload() function, then you'll want to use the
149  * stasis_unsubscribe_and_join() function. This will block until the final
150  * message has been received on the subscription. Otherwise, there's the danger
151  * of invoking the callback function after it has been unloaded.
152  *
153  * If your subscription is owned by an object, then your object should have an
154  * explicit shutdown() function, which calls stasis_unsubscribe(). In your
155  * subscription handler, when the stasis_subscription_final_message() has been
156  * received, decrement the refcount on your object. In your object's destructor,
157  * you may assert that stasis_subscription_is_done() to validate that the
158  * subscription's callback will no longer be invoked.
159  *
160  * \b Note: You may be tempted to simply call stasis_unsubscribe_and_join() from
161  * an object's destructor. While code that does this may work most of the time,
162  * it's got one big downside. There's a general assumption that object
163  * destruction is non-blocking. If you block the destruction waiting for the
164  * subscription to complete, there's the danger that the subscription may
165  * process a message which will bump the refcount up by one. Then it does
166  * whatever it does, decrements the refcount, which then proceeds to re-destroy
167  * the object. Now you've got hard to reproduce bugs that only show up under
168  * certain loads.
169  */
170
171 #include "asterisk/json.h"
172 #include "asterisk/manager.h"
173 #include "asterisk/utils.h"
174 #include "asterisk/event.h"
175
176 /*!
177  * \brief Metadata about a \ref stasis_message.
178  * \since 12
179  */
180 struct stasis_message_type;
181
182 /*!
183  * \brief Opaque type for a Stasis message.
184  * \since 12
185  */
186 struct stasis_message;
187
188 /*!
189  * \brief Opaque type for a Stasis subscription.
190  * \since 12
191  */
192 struct stasis_subscription;
193
194 /*!
195  * \brief Structure containing callbacks for Stasis message sanitization
196  *
197  * \note If either callback is implemented, both should be implemented since
198  * not all callers may have access to the full snapshot.
199  */
200 struct stasis_message_sanitizer {
201         /*!
202          * \brief Callback which determines whether a channel should be sanitized from
203          * a message based on the channel's unique ID
204          *
205          * \param channel_id The unique ID of the channel
206          *
207          * \retval non-zero if the channel should be left out of the message
208          * \retval zero if the channel should remain in the message
209          */
210         int (*channel_id)(const char *channel_id);
211
212         /*!
213          * \brief Callback which determines whether a channel should be sanitized from
214          * a message based on the channel's snapshot
215          *
216          * \param snapshot A snapshot generated from the channel
217          *
218          * \retval non-zero if the channel should be left out of the message
219          * \retval zero if the channel should remain in the message
220          */
221         int (*channel_snapshot)(const struct ast_channel_snapshot *snapshot);
222
223         /*!
224          * \brief Callback which determines whether a channel should be sanitized from
225          * a message based on the channel
226          *
227          * \param chan The channel to be checked
228          *
229          * \retval non-zero if the channel should be left out of the message
230          * \retval zero if the channel should remain in the message
231          */
232         int (*channel)(const struct ast_channel *chan);
233 };
234
235 /*!
236  * \brief Virtual table providing methods for messages.
237  * \since 12
238  */
239 struct stasis_message_vtable {
240         /*!
241          * \brief Build the JSON representation of the message.
242          *
243          * May be \c NULL, or may return \c NULL, to indicate no representation.
244          * The returned object should be ast_json_unref()'ed.
245          *
246          * \param message Message to convert to JSON string.
247          * \param sanitize Snapshot sanitization callback.
248          *
249          * \return Newly allocated JSON message.
250          * \return \c NULL on error.
251          * \return \c NULL if JSON format is not supported.
252          */
253         struct ast_json *(*to_json)(struct stasis_message *message, const struct stasis_message_sanitizer *sanitize);
254
255         /*!
256          * \brief Build the AMI representation of the message.
257          *
258          * May be \c NULL, or may return \c NULL, to indicate no representation.
259          * The returned object should be ao2_cleanup()'ed.
260          *
261          * \param message Message to convert to AMI string.
262          * \return Newly allocated \ref ast_manager_event_blob.
263          * \return \c NULL on error.
264          * \return \c NULL if AMI format is not supported.
265          */
266         struct ast_manager_event_blob *(*to_ami)(
267                 struct stasis_message *message);
268
269         /*!
270          * \since 12.3.0
271          * \brief Build the \ref ast_event representation of the message.
272          *
273          * May be \c NULL, or may return \c NULL, to indicate no representation.
274          * The returned object should be free'd.
275          *
276          * \param message Message to convert to an \ref ast_event.
277          * \return Newly allocated \ref ast_event.
278          * \return \c NULL on error.
279          * \return \c NULL if AMI format is not supported.
280          */
281         struct ast_event *(*to_event)(
282                 struct stasis_message *message);
283 };
284
285 /*!
286  * \brief Return code for Stasis message type creation attempts
287  */
288 enum stasis_message_type_result {
289         STASIS_MESSAGE_TYPE_ERROR = -1, /*!< Message type was not created due to allocation failure */
290         STASIS_MESSAGE_TYPE_SUCCESS,    /*!< Message type was created successfully */
291         STASIS_MESSAGE_TYPE_DECLINED,   /*!< Message type was not created due to configuration */
292 };
293
294 /*!
295  * \brief Stasis subscription message filters
296  */
297 enum stasis_subscription_message_filter {
298         STASIS_SUBSCRIPTION_FILTER_NONE = 0,    /*!< No filter is in place, all messages are raised */
299         STASIS_SUBSCRIPTION_FILTER_FORCED_NONE, /*!< No filter is in place or can be set, all messages are raised */
300         STASIS_SUBSCRIPTION_FILTER_SELECTIVE,   /*!< Only messages of allowed message types are raised */
301 };
302
303 /*!
304  * \brief Create a new message type.
305  *
306  * \ref stasis_message_type is an AO2 object, so ao2_cleanup() when you're done
307  * with it.
308  *
309  * \param name Name of the new type.
310  * \param vtable Virtual table of message methods. May be \c NULL.
311  * \param[out] result The location where the new message type will be placed
312  *
313  * \note Stasis message type creation may be declined if the message type is disabled
314  *
315  * \returns A stasis_message_type_result enum
316  * \since 12
317  */
318 enum stasis_message_type_result stasis_message_type_create(const char *name,
319         struct stasis_message_vtable *vtable, struct stasis_message_type **result);
320
321 /*!
322  * \brief Gets the name of a given message type
323  * \param type The type to get.
324  * \return Name of the type.
325  * \return \c NULL if \a type is \c NULL.
326  * \since 12
327  */
328 const char *stasis_message_type_name(const struct stasis_message_type *type);
329
330 /*!
331  * \brief Gets the hash of a given message type
332  * \param type The type to get the hash of.
333  * \return The hash
334  * \since 13.24.0
335  */
336 unsigned int stasis_message_type_hash(const struct stasis_message_type *type);
337
338 /*!
339  * \brief Gets the id of a given message type
340  * \param type The type to get the id of.
341  * \return The id
342  * \since 17.0.0
343  */
344 int stasis_message_type_id(const struct stasis_message_type *type);
345
346 /*!
347  * \brief Check whether a message type is declined
348  *
349  * \param name The name of the message type to check
350  *
351  * \retval zero The message type is not declined
352  * \retval non-zero The message type is declined
353  */
354 int stasis_message_type_declined(const char *name);
355
356 /*!
357  * \brief Create a new message.
358  *
359  * This message is an \c ao2 object, and must be ao2_cleanup()'ed when you are done
360  * with it. Messages are also immutable, and must not be modified after they
361  * are initialized. Especially the \a data in the message.
362  *
363  * \param type Type of the message
364  * \param data Immutable data that is the actual contents of the message
365  *
366  * \return New message
367  * \return \c NULL on error
368  *
369  * \since 12
370  */
371 struct stasis_message *stasis_message_create(struct stasis_message_type *type, void *data);
372
373 /*!
374  * \brief Create a new message for an entity.
375  *
376  * This message is an \c ao2 object, and must be ao2_cleanup()'ed when you are done
377  * with it. Messages are also immutable, and must not be modified after they
378  * are initialized. Especially the \a data in the message.
379  *
380  * \param type Type of the message
381  * \param data Immutable data that is the actual contents of the message
382  * \param eid What entity originated this message. (NULL for aggregate)
383  *
384  * \note An aggregate message is a combined representation of the local
385  * and remote entities publishing the message data.  e.g., An aggregate
386  * device state represents the combined device state from the local and
387  * any remote entities publishing state for a device.  e.g., An aggregate
388  * MWI message is the old/new MWI counts accumulated from the local and
389  * any remote entities publishing to a mailbox.
390  *
391  * \retval New message
392  * \retval \c NULL on error
393  *
394  * \since 12.2.0
395  */
396 struct stasis_message *stasis_message_create_full(struct stasis_message_type *type, void *data, const struct ast_eid *eid);
397
398 /*!
399  * \brief Get the entity id for a \ref stasis_message.
400  * \since 12.2.0
401  *
402  * \param msg Message to get eid.
403  *
404  * \retval Entity id of \a msg
405  * \retval \c NULL if \a msg is an aggregate or \a msg is \c NULL.
406  */
407 const struct ast_eid *stasis_message_eid(const struct stasis_message *msg);
408
409 /*!
410  * \brief Get the message type for a \ref stasis_message.
411  * \param msg Message to type
412  * \return Type of \a msg
413  * \return \c NULL if \a msg is \c NULL.
414  * \since 12
415  */
416 struct stasis_message_type *stasis_message_type(const struct stasis_message *msg);
417
418 /*!
419  * \brief Get the data contained in a message.
420  * \param msg Message.
421  * \return Immutable data pointer
422  * \return \c NULL if msg is \c NULL.
423  * \since 12
424  */
425 void *stasis_message_data(const struct stasis_message *msg);
426
427 /*!
428  * \brief Get the time when a message was created.
429  * \param msg Message.
430  * \return Pointer to the \a timeval when the message was created.
431  * \return \c NULL if msg is \c NULL.
432  * \since 12
433  */
434 const struct timeval *stasis_message_timestamp(const struct stasis_message *msg);
435
436 /*!
437  * \brief Build the JSON representation of the message.
438  *
439  * May return \c NULL, to indicate no representation. The returned object should
440  * be ast_json_unref()'ed.
441  *
442  * \param msg Message to convert to JSON string.
443  * \param sanitize Snapshot sanitization callback.
444  *
445  * \return Newly allocated string with JSON message.
446  * \return \c NULL on error.
447  * \return \c NULL if JSON format is not supported.
448  */
449 struct ast_json *stasis_message_to_json(struct stasis_message *msg, struct stasis_message_sanitizer *sanitize);
450
451 /*!
452  * \brief Build the AMI representation of the message.
453  *
454  * May return \c NULL, to indicate no representation. The returned object should
455  * be ao2_cleanup()'ed.
456  *
457  * \param msg Message to convert to AMI.
458  * \return \c NULL on error.
459  * \return \c NULL if AMI format is not supported.
460  */
461 struct ast_manager_event_blob *stasis_message_to_ami(struct stasis_message *msg);
462
463 /*!
464  * \brief Determine if the given message can be converted to AMI.
465  *
466  * \param msg Message to see if can be converted to AMI.
467  *
468  * \retval 0 Cannot be converted
469  * \retval non-zero Can be converted
470  */
471 int stasis_message_can_be_ami(struct stasis_message *msg);
472
473 /*!
474  * \brief Build the \ref AstGenericEvents representation of the message.
475  *
476  * May return \c NULL, to indicate no representation. The returned object should
477  * be disposed of via \ref ast_event_destroy.
478  *
479  * \param msg Message to convert to AMI.
480  * \return \c NULL on error.
481  * \return \c NULL if AMI format is not supported.
482  */
483 struct ast_event *stasis_message_to_event(struct stasis_message *msg);
484
485 /*!
486  * \brief A topic to which messages may be posted, and subscribers, well, subscribe
487  * \since 12
488  */
489 struct stasis_topic;
490
491 /*!
492  * \brief Create a new topic.
493  * \param name Name of the new topic.
494  * \return New topic instance.
495  * \return \c NULL on error.
496  * \since 12
497  *
498  * \note There is no explicit ability to unsubscribe all subscribers
499  * from a topic and destroy it. As a result the topic can persist until
500  * the last subscriber unsubscribes itself even if there is no
501  * publisher.
502  */
503 struct stasis_topic *stasis_topic_create(const char *name);
504
505 /*!
506  * \brief Return the name of a topic.
507  * \param topic Topic.
508  * \return Name of the topic.
509  * \return \c NULL if topic is \c NULL.
510  * \since 12
511  */
512 const char *stasis_topic_name(const struct stasis_topic *topic);
513
514 /*!
515  * \brief Return the number of subscribers of a topic.
516  * \param topic Topic.
517  * \return Number of subscribers of the topic.
518  * \since 17.0.0
519  */
520 size_t stasis_topic_subscribers(const struct stasis_topic *topic);
521
522 /*!
523  * \brief Publish a message to a topic's subscribers.
524  * \param topic Topic.
525  * \param message Message to publish.
526  *
527  * This call is asynchronous and will return immediately upon queueing
528  * the message for delivery to the topic's subscribers.
529  *
530  * \since 12
531  */
532 void stasis_publish(struct stasis_topic *topic, struct stasis_message *message);
533
534 /*!
535  * \brief Publish a message to a topic's subscribers, synchronizing
536  * on the specified subscriber
537  * \param sub Subscription to synchronize on.
538  * \param message Message to publish.
539  *
540  * The caller of stasis_publish_sync will block until the specified
541  * subscriber completes handling of the message.
542  *
543  * All other subscribers to the topic the \ref stasis_subpscription
544  * is subscribed to are also delivered the message; this delivery however
545  * happens asynchronously.
546  *
547  * \since 12.1.0
548  */
549 void stasis_publish_sync(struct stasis_subscription *sub, struct stasis_message *message);
550
551 /*!
552  * \brief Callback function type for Stasis subscriptions.
553  * \param data Data field provided with subscription.
554  * \param message Published message.
555  * \since 12
556  */
557 typedef void (*stasis_subscription_cb)(void *data, struct stasis_subscription *sub, struct stasis_message *message);
558
559 /*!
560  * \brief Stasis subscription callback function that does nothing.
561  *
562  * \note This callback should be used for events are not directly processed, but need
563  * to be generated so data can be retrieved from cache later.  Subscriptions with this
564  * callback can be released with \ref stasis_unsubscribe, even during module unload.
565  *
566  * \since 13.5
567  */
568 void stasis_subscription_cb_noop(void *data, struct stasis_subscription *sub, struct stasis_message *message);
569
570 /*!
571  * \brief Create a subscription.
572  *
573  * In addition to being AO2 managed memory (requiring an ao2_cleanup() to free
574  * up this reference), the subscription must be explicitly unsubscribed from its
575  * topic using stasis_unsubscribe().
576  *
577  * The invocations of the callback are serialized, but may not always occur on
578  * the same thread. The invocation order of different subscriptions is
579  * unspecified.
580  *
581  * \param topic Topic to subscribe to.
582  * \param callback Callback function for subscription messages.
583  * \param data Data to be passed to the callback, in addition to the message.
584  * \return New \ref stasis_subscription object.
585  * \return \c NULL on error.
586  * \since 12
587  *
588  * \note This callback will receive a callback with a message indicating it
589  * has been subscribed. This occurs immediately before accepted message
590  * types can be set and the callback must expect to receive it.
591  */
592 struct stasis_subscription *stasis_subscribe(struct stasis_topic *topic,
593         stasis_subscription_cb callback, void *data);
594
595 /*!
596  * \brief Create a subscription whose callbacks occur on a thread pool
597  *
598  * In addition to being AO2 managed memory (requiring an ao2_cleanup() to free
599  * up this reference), the subscription must be explicitly unsubscribed from its
600  * topic using stasis_unsubscribe().
601  *
602  * The invocations of the callback are serialized, but will almost certainly not
603  * always happen on the same thread. The invocation order of different subscriptions
604  * is unspecified.
605  *
606  * Unlike \ref stasis_subscribe, this function will explicitly use a threadpool to
607  * dispatch items to its \c callback. This form of subscription should be used
608  * when many subscriptions may be made to the specified \c topic.
609  *
610  * \param topic Topic to subscribe to.
611  * \param callback Callback function for subscription messages.
612  * \param data Data to be passed to the callback, in addition to the message.
613  * \return New \ref stasis_subscription object.
614  * \return \c NULL on error.
615  * \since 12.8.0
616  *
617  * \note This callback will receive a callback with a message indicating it
618  * has been subscribed. This occurs immediately before accepted message
619  * types can be set and the callback must expect to receive it.
620  */
621 struct stasis_subscription *stasis_subscribe_pool(struct stasis_topic *topic,
622         stasis_subscription_cb callback, void *data);
623
624 /*!
625  * \brief Indicate to a subscription that we are interested in a message type.
626  *
627  * This will cause the subscription to allow the given message type to be
628  * raised to our subscription callback. This enables internal filtering in
629  * the stasis message bus to reduce messages.
630  *
631  * \param subscription Subscription to add message type to.
632  * \param type The message type we wish to receive.
633  * \retval 0 on success
634  * \retval -1 failure
635  *
636  * \since 17.0.0
637  *
638  * \note If you are wanting to use stasis_final_message you will need to accept
639  * \ref stasis_subscription_change_type as a message type.
640  *
641  * \note Until the subscription is set to selective filtering it is possible for it
642  * to receive messages of message types that would not normally be accepted.
643  */
644 int stasis_subscription_accept_message_type(struct stasis_subscription *subscription,
645         const struct stasis_message_type *type);
646
647 /*!
648  * \brief Indicate to a subscription that we are not interested in a message type.
649  *
650  * \param subscription Subscription to remove message type from.
651  * \param type The message type we don't wish to receive.
652  * \retval 0 on success
653  * \retval -1 failure
654  *
655  * \since 17.0.0
656  */
657 int stasis_subscription_decline_message_type(struct stasis_subscription *subscription,
658         const struct stasis_message_type *type);
659
660 /*!
661  * \brief Set the message type filtering level on a subscription
662  *
663  * This will cause the subscription to filter messages according to the
664  * provided filter level. For example if selective is used then only
665  * messages matching those provided to \ref stasis_subscription_accept_message_type
666  * will be raised to the subscription callback.
667  *
668  * \param subscription Subscription that should receive all messages.
669  * \param filter What filter to use
670  * \retval 0 on success
671  * \retval -1 failure
672  *
673  * \since 17.0.0
674  */
675 int stasis_subscription_set_filter(struct stasis_subscription *subscription,
676         enum stasis_subscription_message_filter filter);
677
678 /*!
679  * \brief Cancel a subscription.
680  *
681  * Note that in an asynchronous system, there may still be messages queued or
682  * in transit to the subscription's callback. These will still be delivered.
683  * There will be a final 'SubscriptionCancelled' message, indicating the
684  * delivery of the final message.
685  *
686  * \param subscription Subscription to cancel.
687  * \return \c NULL for convenience
688  * \since 12
689  */
690 struct stasis_subscription *stasis_unsubscribe(
691         struct stasis_subscription *subscription);
692
693 /*!
694  * \brief Set the high and low alert water marks of the stasis subscription.
695  * \since 13.10.0
696  *
697  * \param subscription Pointer to a stasis subscription
698  * \param low_water New queue low water mark. (-1 to set as 90% of high_water)
699  * \param high_water New queue high water mark.
700  *
701  * \retval 0 on success.
702  * \retval -1 on error (water marks not changed).
703  */
704 int stasis_subscription_set_congestion_limits(struct stasis_subscription *subscription,
705         long low_water, long high_water);
706
707 /*!
708  * \brief Block until the last message is processed on a subscription.
709  *
710  * This function will not return until the \a subscription's callback for the
711  * stasis_subscription_final_message() completes. This allows cleanup routines
712  * to run before unblocking the joining thread.
713  *
714  * \param subscription Subscription to block on.
715  * \since 12
716  */
717 void stasis_subscription_join(struct stasis_subscription *subscription);
718
719 /*!
720  * \brief Returns whether \a subscription has received its final message.
721  *
722  * Note that a subscription is considered done even while the
723  * stasis_subscription_final_message() is being processed. This allows cleanup
724  * routines to check the status of the subscription.
725  *
726  * \param subscription Subscription.
727  * \return True (non-zero) if stasis_subscription_final_message() has been
728  *         received.
729  * \return False (zero) if waiting for the end.
730  */
731 int stasis_subscription_is_done(struct stasis_subscription *subscription);
732
733 /*!
734  * \brief Cancel a subscription, blocking until the last message is processed.
735  *
736  * While normally it's recommended to stasis_unsubscribe() and wait for
737  * stasis_subscription_final_message(), there are times (like during a module
738  * unload) where you have to wait for the final message (otherwise you'll call
739  * a function in a shared module that no longer exists).
740  *
741  * \param subscription Subscription to cancel.
742  * \return \c NULL for convenience
743  * \since 12
744  */
745 struct stasis_subscription *stasis_unsubscribe_and_join(
746         struct stasis_subscription *subscription);
747
748 struct stasis_forward;
749
750 /*!
751  * \brief Create a subscription which forwards all messages from one topic to
752  * another.
753  *
754  * Note that the \a topic parameter of the invoked callback will the be the
755  * \a topic the message was sent to, not the topic the subscriber subscribed to.
756  *
757  * \param from_topic Topic to forward.
758  * \param to_topic Destination topic of forwarded messages.
759  * \return New forwarding subscription.
760  * \return \c NULL on error.
761  * \since 12
762  */
763 struct stasis_forward *stasis_forward_all(struct stasis_topic *from_topic,
764         struct stasis_topic *to_topic);
765
766 struct stasis_forward *stasis_forward_cancel(struct stasis_forward *forward);
767
768 /*!
769  * \brief Get the unique ID for the subscription.
770  *
771  * \param sub Subscription for which to get the unique ID.
772  * \return Unique ID for the subscription.
773  * \since 12
774  */
775 const char *stasis_subscription_uniqueid(const struct stasis_subscription *sub);
776
777 /*!
778  * \brief Returns whether a subscription is currently subscribed.
779  *
780  * Note that there may still be messages queued up to be dispatched to this
781  * subscription, but the stasis_subscription_final_message() has been enqueued.
782  *
783  * \param sub Subscription to check
784  * \return False (zero) if subscription is not subscribed.
785  * \return True (non-zero) if still subscribed.
786  */
787 int stasis_subscription_is_subscribed(const struct stasis_subscription *sub);
788
789 /*!
790  * \brief Determine whether a message is the final message to be received on a subscription.
791  *
792  * \param sub Subscription on which the message was received.
793  * \param msg Message to check.
794  * \return zero if the provided message is not the final message.
795  * \return non-zero if the provided message is the final message.
796  * \since 12
797  */
798 int stasis_subscription_final_message(struct stasis_subscription *sub, struct stasis_message *msg);
799
800 /*! \addtogroup StasisTopicsAndMessages
801  * @{
802  */
803
804 /*!
805  * \brief Holds details about changes to subscriptions for the specified topic
806  * \since 12
807  */
808 struct stasis_subscription_change {
809         AST_DECLARE_STRING_FIELDS(
810                 AST_STRING_FIELD(uniqueid);     /*!< The unique ID associated with this subscription */
811                 AST_STRING_FIELD(description);  /*!< The description of the change to the subscription associated with the uniqueid */
812         );
813         struct stasis_topic *topic;             /*!< The topic the subscription is/was subscribing to */
814 };
815
816 /*!
817  * \brief Gets the message type for subscription change notices
818  * \return The stasis_message_type for subscription change notices
819  * \since 12
820  */
821 struct stasis_message_type *stasis_subscription_change_type(void);
822
823 /*! @} */
824
825 /*!
826  * \brief Pool for topic aggregation
827  */
828 struct stasis_topic_pool;
829
830 /*!
831  * \brief Create a topic pool that routes messages from dynamically generated topics to the given topic
832  * \param pooled_topic Topic to which messages will be routed
833  * \return the new stasis_topic_pool
834  * \return \c NULL on failure
835  */
836 struct stasis_topic_pool *stasis_topic_pool_create(struct stasis_topic *pooled_topic);
837
838 /*!
839  * \brief Find or create a topic in the pool
840  * \param pool Pool for which to get the topic
841  * \param topic_name Name of the topic to get
842  * \return The already stored or newly allocated topic
843  * \return \c NULL if the topic was not found and could not be allocated
844  */
845 struct stasis_topic *stasis_topic_pool_get_topic(struct stasis_topic_pool *pool, const char *topic_name);
846
847 /*!
848  * \brief Delete a topic from the topic pool
849  *
850  * \param pool Pool from which to delete the topic
851  * \param topic_name Name of the topic to delete
852  *
853  * \since 13.24
854  * \since 15.6
855  * \since 16.1
856  */
857 void stasis_topic_pool_delete_topic(struct stasis_topic_pool *pool, const char *topic_name);
858
859 /*!
860  * \brief Check if a topic exists in a pool
861  * \param pool Pool to check
862  * \param topic_name Name of the topic to check
863  * \retval 1 exists
864  * \retval 0 does not exist
865  * \since 13.23.0
866  */
867 int stasis_topic_pool_topic_exists(const struct stasis_topic_pool *pool, const char *topic_name);
868
869 /*! \addtogroup StasisTopicsAndMessages
870  * @{
871  */
872
873 /*!
874  * \brief Message type for cache update messages.
875  * \return Message type for cache update messages.
876  * \since 12
877  */
878 struct stasis_message_type *stasis_cache_update_type(void);
879
880 /*!
881  * \brief Cache update message
882  * \since 12
883  */
884 struct stasis_cache_update {
885         /*! \brief Convenience reference to snapshot type */
886         struct stasis_message_type *type;
887         /*! \brief Old value from the cache */
888         struct stasis_message *old_snapshot;
889         /*! \brief New value */
890         struct stasis_message *new_snapshot;
891 };
892
893 /*!
894  * \brief Message type for clearing a message from a stasis cache.
895  * \since 12
896  */
897 struct stasis_message_type *stasis_cache_clear_type(void);
898
899 /*! @} */
900
901 /*!
902  * \brief A message cache, for use with \ref stasis_caching_topic.
903  * \since 12
904  */
905 struct stasis_cache;
906
907 /*! Cache entry used for calculating the aggregate snapshot. */
908 struct stasis_cache_entry;
909
910 /*!
911  * \brief A topic wrapper, which caches certain messages.
912  * \since 12
913  */
914 struct stasis_caching_topic;
915
916
917 /*!
918  * \brief Callback extract a unique identity from a snapshot message.
919  *
920  * This identity is unique to the underlying object of the snapshot, such as the
921  * UniqueId field of a channel.
922  *
923  * \param message Message to extract id from.
924  * \return String representing the snapshot's id.
925  * \return \c NULL if the message_type of the message isn't a handled snapshot.
926  * \since 12
927  */
928 typedef const char *(*snapshot_get_id)(struct stasis_message *message);
929
930 /*!
931  * \brief Callback to calculate the aggregate cache entry.
932  * \since 12.2.0
933  *
934  * \param entry Cache entry to calculate a new aggregate snapshot.
935  * \param new_snapshot The shapshot that is being updated.
936  *
937  * \note Return a ref bumped pointer from stasis_cache_entry_get_aggregate()
938  * if a new aggregate could not be calculated because of error.
939  *
940  * \note An aggregate message is a combined representation of the local
941  * and remote entities publishing the message data.  e.g., An aggregate
942  * device state represents the combined device state from the local and
943  * any remote entities publishing state for a device.  e.g., An aggregate
944  * MWI message is the old/new MWI counts accumulated from the local and
945  * any remote entities publishing to a mailbox.
946  *
947  * \return New aggregate-snapshot calculated on success.
948  * Caller has a reference on return.
949  */
950 typedef struct stasis_message *(*cache_aggregate_calc_fn)(struct stasis_cache_entry *entry, struct stasis_message *new_snapshot);
951
952 /*!
953  * \brief Callback to publish the aggregate cache entry message.
954  * \since 12.2.0
955  *
956  * \details
957  * Once an aggregate message is calculated.  This callback publishes the
958  * message so subscribers will know the new value of an aggregated state.
959  *
960  * \param topic The aggregate message may be published to this topic.
961  *        It is the topic to which the cache itself is subscribed.
962  * \param aggregate The aggregate shapshot message to publish.
963  *
964  * \note It is up to the function to determine if there is a better topic
965  * the aggregate message should be published over.
966  *
967  * \note An aggregate message is a combined representation of the local
968  * and remote entities publishing the message data.  e.g., An aggregate
969  * device state represents the combined device state from the local and
970  * any remote entities publishing state for a device.  e.g., An aggregate
971  * MWI message is the old/new MWI counts accumulated from the local and
972  * any remote entities publishing to a mailbox.
973  *
974  * \return Nothing
975  */
976 typedef void (*cache_aggregate_publish_fn)(struct stasis_topic *topic, struct stasis_message *aggregate);
977
978 /*!
979  * \brief Get the aggregate cache entry snapshot.
980  * \since 12.2.0
981  *
982  * \param entry Cache entry to get the aggregate snapshot.
983  *
984  * \note A reference is not given to the returned pointer so don't unref it.
985  *
986  * \note An aggregate message is a combined representation of the local
987  * and remote entities publishing the message data.  e.g., An aggregate
988  * device state represents the combined device state from the local and
989  * any remote entities publishing state for a device.  e.g., An aggregate
990  * MWI message is the old/new MWI counts accumulated from the local and
991  * any remote entities publishing to a mailbox.
992  *
993  * \retval Aggregate-snapshot in cache.
994  * \retval NULL if not present.
995  */
996 struct stasis_message *stasis_cache_entry_get_aggregate(struct stasis_cache_entry *entry);
997
998 /*!
999  * \brief Get the local entity's cache entry snapshot.
1000  * \since 12.2.0
1001  *
1002  * \param entry Cache entry to get the local entity's snapshot.
1003  *
1004  * \note A reference is not given to the returned pointer so don't unref it.
1005  *
1006  * \retval Internal-snapshot in cache.
1007  * \retval NULL if not present.
1008  */
1009 struct stasis_message *stasis_cache_entry_get_local(struct stasis_cache_entry *entry);
1010
1011 /*!
1012  * \brief Get a remote entity's cache entry snapshot by index.
1013  * \since 12.2.0
1014  *
1015  * \param entry Cache entry to get a remote entity's snapshot.
1016  * \param idx Which remote entity's snapshot to get.
1017  *
1018  * \note A reference is not given to the returned pointer so don't unref it.
1019  *
1020  * \retval Remote-entity-snapshot in cache.
1021  * \retval NULL if not present.
1022  */
1023 struct stasis_message *stasis_cache_entry_get_remote(struct stasis_cache_entry *entry, int idx);
1024
1025 /*!
1026  * \brief Create a cache.
1027  *
1028  * This is the backend store for a \ref stasis_caching_topic. The cache is
1029  * thread safe, allowing concurrent reads and writes.
1030  *
1031  * The returned object is AO2 managed, so ao2_cleanup() when you're done.
1032  *
1033  * \param id_fn Callback to extract the id from a snapshot message.
1034  *
1035  * \retval New cache indexed by \a id_fn.
1036  * \retval \c NULL on error
1037  *
1038  * \since 12
1039  */
1040 struct stasis_cache *stasis_cache_create(snapshot_get_id id_fn);
1041
1042 /*!
1043  * \brief Create a cache.
1044  *
1045  * This is the backend store for a \ref stasis_caching_topic. The cache is
1046  * thread safe, allowing concurrent reads and writes.
1047  *
1048  * The returned object is AO2 managed, so ao2_cleanup() when you're done.
1049  *
1050  * \param id_fn Callback to extract the id from a snapshot message.
1051  * \param aggregate_calc_fn Callback to calculate the aggregate cache entry.
1052  * \param aggregate_publish_fn Callback to publish the aggregate cache entry.
1053  *
1054  * \note An aggregate message is a combined representation of the local
1055  * and remote entities publishing the message data.  e.g., An aggregate
1056  * device state represents the combined device state from the local and
1057  * any remote entities publishing state for a device.  e.g., An aggregate
1058  * MWI message is the old/new MWI counts accumulated from the local and
1059  * any remote entities publishing to a mailbox.
1060  *
1061  * \retval New cache indexed by \a id_fn.
1062  * \retval \c NULL on error
1063  *
1064  * \since 12.2.0
1065  */
1066 struct stasis_cache *stasis_cache_create_full(snapshot_get_id id_fn, cache_aggregate_calc_fn aggregate_calc_fn, cache_aggregate_publish_fn aggregate_publish_fn);
1067
1068 /*!
1069  * \brief Create a topic which monitors and caches messages from another topic.
1070  *
1071  * The idea is that some topics publish 'snapshots' of some other object's state
1072  * that should be cached. When these snapshot messages are received, the cache
1073  * is updated, and a stasis_cache_update() message is forwarded, which has both
1074  * the original snapshot message and the new message.
1075  *
1076  * The returned object is AO2 managed, so ao2_cleanup() when done with it.
1077  *
1078  * \param original_topic Topic publishing snapshot messages.
1079  * \param cache Backend cache in which to keep snapshots.
1080  * \return New topic which changes snapshot messages to stasis_cache_update()
1081  *         messages, and forwards all other messages from the original topic.
1082  * \return \c NULL on error
1083  * \since 12
1084  */
1085 struct stasis_caching_topic *stasis_caching_topic_create(
1086         struct stasis_topic *original_topic, struct stasis_cache *cache);
1087
1088 /*!
1089  * \brief Unsubscribes a caching topic from its upstream topic.
1090  *
1091  * This function returns immediately, so be sure to cleanup when
1092  * stasis_subscription_final_message() is received.
1093  *
1094  * \param caching_topic Caching topic to unsubscribe
1095  * \return \c NULL for convenience
1096  * \since 12
1097  */
1098 struct stasis_caching_topic *stasis_caching_unsubscribe(
1099         struct stasis_caching_topic *caching_topic);
1100
1101 /*!
1102  * \brief Unsubscribes a caching topic from its upstream topic, blocking until
1103  * all messages have been forwarded.
1104  *
1105  * See stasis_unsubscriben_and_join() for more info on when to use this as
1106  * opposed to stasis_caching_unsubscribe().
1107  *
1108  * \param caching_topic Caching topic to unsubscribe
1109  * \return \c NULL for convenience
1110  * \since 12
1111  */
1112 struct stasis_caching_topic *stasis_caching_unsubscribe_and_join(
1113         struct stasis_caching_topic *caching_topic);
1114
1115 /*!
1116  * \brief Returns the topic of cached events from a caching topics.
1117  * \param caching_topic The caching topic.
1118  * \return The topic that publishes cache update events, along with passthrough
1119  *         events from the underlying topic.
1120  * \return \c NULL if \a caching_topic is \c NULL.
1121  * \since 12
1122  */
1123 struct stasis_topic *stasis_caching_get_topic(
1124         struct stasis_caching_topic *caching_topic);
1125
1126 /*!
1127  * \brief Indicate to a caching topic that we are interested in a message type.
1128  *
1129  * This will cause the caching topic to receive messages of the given message
1130  * type. This enables internal filtering in the stasis message bus to reduce
1131  * messages.
1132  *
1133  * \param caching_topic The caching topic.
1134  * \param type The message type we wish to receive.
1135  * \retval 0 on success
1136  * \retval -1 failure
1137  *
1138  * \since 17.0.0
1139  */
1140 int stasis_caching_accept_message_type(struct stasis_caching_topic *caching_topic,
1141         struct stasis_message_type *type);
1142
1143 /*!
1144  * \brief Set the message type filtering level on a cache
1145  *
1146  * This will cause the underlying subscription to filter messages according to the
1147  * provided filter level. For example if selective is used then only
1148  * messages matching those provided to \ref stasis_subscription_accept_message_type
1149  * will be raised to the subscription callback.
1150  *
1151  * \param caching_topic The caching topic.
1152  * \param filter What filter to use
1153  * \retval 0 on success
1154  * \retval -1 failure
1155  *
1156  * \since 17.0.0
1157  */
1158 int stasis_caching_set_filter(struct stasis_caching_topic *caching_topic,
1159         enum stasis_subscription_message_filter filter);
1160
1161 /*!
1162  * \brief A message which instructs the caching topic to remove an entry from
1163  * its cache.
1164  *
1165  * \param message Message representative of the cache entry that should be
1166  *                cleared. This will become the data held in the
1167  *                stasis_cache_clear message.
1168  *
1169  * \return Message which, when sent to a \ref stasis_caching_topic, will clear
1170  *         the item from the cache.
1171  * \return \c NULL on error.
1172  * \since 12
1173  */
1174 struct stasis_message *stasis_cache_clear_create(struct stasis_message *message);
1175
1176 /*!
1177  * \brief Retrieve an item from the cache for the ast_eid_default entity.
1178  *
1179  * The returned item is AO2 managed, so ao2_cleanup() when you're done with it.
1180  *
1181  * \param cache The cache to query.
1182  * \param type Type of message to retrieve.
1183  * \param id Identity of the snapshot to retrieve.
1184  *
1185  * \retval Message from the cache.
1186  * \retval \c NULL if message is not found.
1187  *
1188  * \since 12
1189  */
1190 struct stasis_message *stasis_cache_get(struct stasis_cache *cache, struct stasis_message_type *type, const char *id);
1191
1192 /*!
1193  * \brief Retrieve an item from the cache for a specific entity.
1194  *
1195  * The returned item is AO2 managed, so ao2_cleanup() when you're done with it.
1196  *
1197  * \param cache The cache to query.
1198  * \param type Type of message to retrieve.
1199  * \param id Identity of the snapshot to retrieve.
1200  * \param eid Specific entity id to retrieve.  NULL for aggregate.
1201  *
1202  * \note An aggregate message is a combined representation of the local
1203  * and remote entities publishing the message data.  e.g., An aggregate
1204  * device state represents the combined device state from the local and
1205  * any remote entities publishing state for a device.  e.g., An aggregate
1206  * MWI message is the old/new MWI counts accumulated from the local and
1207  * any remote entities publishing to a mailbox.
1208  *
1209  * \retval Message from the cache.
1210  * \retval \c NULL if message is not found.
1211  *
1212  * \since 12.2.0
1213  */
1214 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);
1215
1216 /*!
1217  * \brief Retrieve all matching entity items from the cache.
1218  * \since 12.2.0
1219  *
1220  * \param cache The cache to query.
1221  * \param type Type of message to retrieve.
1222  * \param id Identity of the snapshot to retrieve.
1223  *
1224  * \retval Container of matching items found.
1225  * \retval \c NULL if error.
1226  */
1227 struct ao2_container *stasis_cache_get_all(struct stasis_cache *cache, struct stasis_message_type *type, const char *id);
1228
1229 /*!
1230  * \brief Dump cached items to a subscription for the ast_eid_default entity.
1231  *
1232  * \param cache The cache to query.
1233  * \param type Type of message to dump (any type if \c NULL).
1234  *
1235  * \retval ao2_container containing all matches (must be unreffed by caller)
1236  * \retval \c NULL on allocation error
1237  *
1238  * \since 12
1239  */
1240 struct ao2_container *stasis_cache_dump(struct stasis_cache *cache, struct stasis_message_type *type);
1241
1242 /*!
1243  * \brief Dump cached items to a subscription for a specific entity.
1244  * \since 12.2.0
1245  *
1246  * \param cache The cache to query.
1247  * \param type Type of message to dump (any type if \c NULL).
1248  * \param eid Specific entity id to retrieve.  NULL for aggregate.
1249  *
1250  * \retval ao2_container containing all matches (must be unreffed by caller)
1251  * \retval \c NULL on allocation error
1252  */
1253 struct ao2_container *stasis_cache_dump_by_eid(struct stasis_cache *cache, struct stasis_message_type *type, const struct ast_eid *eid);
1254
1255 /*!
1256  * \brief Dump all entity items from the cache to a subscription.
1257  * \since 12.2.0
1258  *
1259  * \param cache The cache to query.
1260  * \param type Type of message to dump (any type if \c NULL).
1261  *
1262  * \retval ao2_container containing all matches (must be unreffed by caller)
1263  * \retval \c NULL on allocation error
1264  */
1265 struct ao2_container *stasis_cache_dump_all(struct stasis_cache *cache, struct stasis_message_type *type);
1266
1267 /*! \addtogroup StasisTopicsAndMessages
1268  * @{
1269  */
1270
1271 /*!
1272  * \brief Object type code for multi user object snapshots
1273  */
1274 enum stasis_user_multi_object_snapshot_type {
1275         STASIS_UMOS_CHANNEL = 0,     /*!< Channel Snapshots */
1276         STASIS_UMOS_BRIDGE,          /*!< Bridge Snapshots */
1277         STASIS_UMOS_ENDPOINT,        /*!< Endpoint Snapshots */
1278 };
1279
1280 /*! \brief Number of snapshot types */
1281 #define STASIS_UMOS_MAX (STASIS_UMOS_ENDPOINT + 1)
1282
1283 /*!
1284  * \brief Message type for custom user defined events with multi object blobs
1285  * \return The stasis_message_type for user event
1286  * \since 12.3.0
1287  */
1288 struct stasis_message_type *ast_multi_user_event_type(void);
1289
1290 /*!
1291  * \brief Create a stasis multi object blob
1292  * \since 12.3.0
1293  *
1294  * \details
1295  * Multi object blob can store a combination of arbitrary json values
1296  * (the blob) and also snapshots of various other system objects (such
1297  * as channels, bridges, etc) for delivery through a stasis message.
1298  * The multi object blob is first created, then optionally objects
1299  * are added to it, before being attached to a message and delivered
1300  * to stasis topic.
1301  *
1302  * \param blob Json blob
1303  *
1304  * \note When used for an ast_multi_user_event_type message, the
1305  * json blob should contain at minimum {eventname: name}.
1306  *
1307  * \retval ast_multi_object_blob* if succeeded
1308  * \retval NULL if creation failed
1309  */
1310 struct ast_multi_object_blob *ast_multi_object_blob_create(struct ast_json *blob);
1311
1312 /*!
1313  * \brief Add an object to a multi object blob previously created
1314  * \since 12.3.0
1315  *
1316  * \param multi The multi object blob previously created
1317  * \param type Type code for the object such as channel, bridge, etc.
1318  * \param object Snapshot object of the type supplied to typename
1319  *
1320  * \return Nothing
1321  */
1322 void ast_multi_object_blob_add(struct ast_multi_object_blob *multi, enum stasis_user_multi_object_snapshot_type type, void *object);
1323
1324 /*!
1325  * \brief Create and publish a stasis message blob on a channel with it's snapshot
1326  * \since 12.3.0
1327  *
1328  * \details
1329  * For compatibility with app_userevent, this creates a multi object
1330  * blob message, attaches the channel snapshot to it, and publishes it
1331  * to the channel's topic.
1332  *
1333  * \param chan The channel to snapshot and publish event to
1334  * \param type The message type
1335  * \param blob A json blob to publish with the snapshot
1336  *
1337  * \return Nothing
1338  */
1339 void ast_multi_object_blob_single_channel_publish(struct ast_channel *chan, struct stasis_message_type *type, struct ast_json *blob);
1340
1341
1342 /*! @} */
1343
1344 /*!
1345  * \internal
1346  * \brief Log a message about invalid attempt to access a type.
1347  */
1348 void stasis_log_bad_type_access(const char *name);
1349
1350 /*!
1351  * \brief Boiler-plate messaging macro for defining public message types.
1352  *
1353  * \code
1354  *      STASIS_MESSAGE_TYPE_DEFN(ast_foo_type,
1355  *              .to_ami = foo_to_ami,
1356  *              .to_json = foo_to_json,
1357  *              .to_event = foo_to_event,
1358  *              );
1359  * \endcode
1360  *
1361  * \param name Name of message type.
1362  * \param ... Virtual table methods for messages of this type.
1363  * \since 12
1364  */
1365 #define STASIS_MESSAGE_TYPE_DEFN(name, ...)                             \
1366         static struct stasis_message_vtable _priv_ ## name ## _v = {    \
1367                 __VA_ARGS__                                             \
1368         };                                                              \
1369         static struct stasis_message_type *_priv_ ## name;              \
1370         struct stasis_message_type *name(void) {                        \
1371                 if (_priv_ ## name == NULL) {                           \
1372                         stasis_log_bad_type_access(#name);              \
1373                 }                                                       \
1374                 return _priv_ ## name;                                  \
1375         }
1376
1377 /*!
1378  * \brief Boiler-plate messaging macro for defining local message types.
1379  *
1380  * \code
1381  *      STASIS_MESSAGE_TYPE_DEFN_LOCAL(ast_foo_type,
1382  *              .to_ami = foo_to_ami,
1383  *              .to_json = foo_to_json,
1384  *              .to_event = foo_to_event,
1385  *              );
1386  * \endcode
1387  *
1388  * \param name Name of message type.
1389  * \param ... Virtual table methods for messages of this type.
1390  * \since 12
1391  */
1392 #define STASIS_MESSAGE_TYPE_DEFN_LOCAL(name, ...)                       \
1393         static struct stasis_message_vtable _priv_ ## name ## _v = {    \
1394                 __VA_ARGS__                                             \
1395         };                                                              \
1396         static struct stasis_message_type *_priv_ ## name;              \
1397         static struct stasis_message_type *name(void) {                 \
1398                 if (_priv_ ## name == NULL) {                           \
1399                         stasis_log_bad_type_access(#name);              \
1400                 }                                                       \
1401                 return _priv_ ## name;                                  \
1402         }
1403
1404 /*!
1405 * \brief Boiler-plate messaging macro for initializing message types.
1406  *
1407  * \code
1408  *      if (STASIS_MESSAGE_TYPE_INIT(ast_foo_type) != 0) {
1409  *              return -1;
1410  *      }
1411  * \endcode
1412  *
1413  * \param name Name of message type.
1414  * \return 0 if initialization is successful.
1415  * \return Non-zero on failure.
1416  * \since 12
1417  */
1418 #define STASIS_MESSAGE_TYPE_INIT(name)                                  \
1419         ({                                                              \
1420                 ast_assert(_priv_ ## name == NULL);                     \
1421                 stasis_message_type_create(#name,       \
1422                         &_priv_ ## name ## _v, &_priv_ ## name) == STASIS_MESSAGE_TYPE_ERROR ? 1 : 0;   \
1423         })
1424
1425 /*!
1426  * \brief Boiler-plate messaging macro for cleaning up message types.
1427  *
1428  * Note that if your type is defined in core instead of a loadable module, you
1429  * should call message type cleanup from an ast_register_cleanup() handler
1430  * instead of an ast_register_atexit() handler.
1431  *
1432  * The reason is that during an immediate shutdown, loadable modules (which may
1433  * refer to core message types) are not unloaded. While the atexit handlers are
1434  * run, there's a window of time where a module subscription might reference a
1435  * core message type after it's been cleaned up. Which is bad.
1436  *
1437  * \param name Name of message type.
1438  * \since 12
1439  */
1440 #define STASIS_MESSAGE_TYPE_CLEANUP(name)       \
1441         ({                                      \
1442                 ao2_cleanup(_priv_ ## name);    \
1443                 _priv_ ## name = NULL;          \
1444         })
1445
1446 /*!
1447  * \brief Initialize the Stasis subsystem.
1448  * \return 0 on success.
1449  * \return Non-zero on error.
1450  * \since 12
1451  */
1452 int stasis_init(void);
1453
1454 /*!
1455  * \internal
1456  * \brief called by stasis_init() for cache initialization.
1457  * \return 0 on success.
1458  * \return Non-zero on error.
1459  * \since 12
1460  */
1461 int stasis_cache_init(void);
1462
1463 /*!
1464  * \internal
1465  * \brief called by stasis_init() for config initialization.
1466  * \return 0 on success.
1467  * \return Non-zero on error.
1468  * \since 12
1469  */
1470 int stasis_config_init(void);
1471
1472 /*!
1473  * \defgroup StasisTopicsAndMessages Stasis topics, and their messages.
1474  *
1475  * \brief This group contains the topics, messages and corresponding message types
1476  * found within Asterisk.
1477  */
1478
1479 #endif /* _ASTERISK_STASIS_H */