529aa12bbdd1715bc993fc1d8584f470bf85ece2
[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
175 /*! @{ */
176
177 /*!
178  * \brief Metadata about a \ref stasis_message.
179  * \since 12
180  */
181 struct stasis_message_type;
182
183 /*!
184  * \brief Opaque type for a Stasis message.
185  * \since 12
186  */
187 struct stasis_message;
188
189 /*!
190  * \brief Virtual table providing methods for messages.
191  * \since 12
192  */
193 struct stasis_message_vtable {
194         /*!
195          * \brief Build the JSON representation of the message.
196          *
197          * May be \c NULL, or may return \c NULL, to indicate no representation.
198          * The returned object should be ast_json_unref()'ed.
199          *
200          * \param message Message to convert to JSON string.
201          * \return Newly allocated JSON message.
202          * \return \c NULL on error.
203          * \return \c NULL if JSON format is not supported.
204          */
205         struct ast_json *(*to_json)(struct stasis_message *message);
206
207         /*!
208          * \brief Build the AMI representation of the message.
209          *
210          * May be \c NULL, or may return \c NULL, to indicate no representation.
211          * The returned object should be ao2_cleankup()'ed.
212          *
213          * \param message Message to convert to AMI string.
214          * \return Newly allocated \ref ast_manager_event_blob.
215          * \return \c NULL on error.
216          * \return \c NULL if AMI format is not supported.
217          */
218         struct ast_manager_event_blob *(*to_ami)(
219                 struct stasis_message *message);
220 };
221
222 /*!
223  * \brief Create a new message type.
224  *
225  * \ref stasis_message_type is an AO2 object, so ao2_cleanup() when you're done
226  * with it.
227  *
228  * \param name Name of the new type.
229  * \param vtable Virtual table of message methods. May be \c NULL.
230  * \return Pointer to the new type.
231  * \return \c NULL on error.
232  * \since 12
233  */
234 struct stasis_message_type *stasis_message_type_create(const char *name,
235         struct stasis_message_vtable *vtable);
236
237 /*!
238  * \brief Gets the name of a given message type
239  * \param type The type to get.
240  * \return Name of the type.
241  * \return \c NULL if \a type is \c NULL.
242  * \since 12
243  */
244 const char *stasis_message_type_name(const struct stasis_message_type *type);
245
246 /*!
247  * \brief Create a new message.
248  *
249  * This message is an \c ao2 object, and must be ao2_cleanup()'ed when you are done
250  * with it. Messages are also immutable, and must not be modified after they
251  * are initialized. Especially the \a data in the message.
252  *
253  * \param type Type of the message
254  * \param data Immutable data that is the actual contents of the message
255  * \return New message
256  * \return \c NULL on error
257  * \since 12
258  */
259 struct stasis_message *stasis_message_create(struct stasis_message_type *type, void *data);
260
261 /*!
262  * \brief Get the message type for a \ref stasis_message.
263  * \param msg Message to type
264  * \return Type of \a msg
265  * \return \c NULL if \a msg is \c NULL.
266  * \since 12
267  */
268 struct stasis_message_type *stasis_message_type(const struct stasis_message *msg);
269
270 /*!
271  * \brief Get the data contained in a message.
272  * \param msg Message.
273  * \return Immutable data pointer
274  * \return \c NULL if msg is \c NULL.
275  * \since 12
276  */
277 void *stasis_message_data(const struct stasis_message *msg);
278
279 /*!
280  * \brief Get the time when a message was created.
281  * \param msg Message.
282  * \return Pointer to the \a timeval when the message was created.
283  * \return \c NULL if msg is \c NULL.
284  * \since 12
285  */
286 const struct timeval *stasis_message_timestamp(const struct stasis_message *msg);
287
288 /*!
289  * \brief Build the JSON representation of the message.
290  *
291  * May return \c NULL, to indicate no representation. The returned object should
292  * be ast_json_unref()'ed.
293  *
294  * \param message Message to convert to JSON string.
295  * \return Newly allocated string with JSON message.
296  * \return \c NULL on error.
297  * \return \c NULL if JSON format is not supported.
298  */
299 struct ast_json *stasis_message_to_json(struct stasis_message *message);
300
301 /*!
302  * \brief Build the AMI representation of the message.
303  *
304  * May return \c NULL, to indicate no representation. The returned object should
305  * be ao2_cleanup()'ed.
306  *
307  * \param message Message to convert to AMI.
308  * \return \c NULL on error.
309  * \return \c NULL if AMI format is not supported.
310  */
311 struct ast_manager_event_blob *stasis_message_to_ami(
312         struct stasis_message *message);
313
314 /*! @} */
315
316 /*! @{ */
317
318 /*!
319  * \brief A topic to which messages may be posted, and subscribers, well, subscribe
320  * \since 12
321  */
322 struct stasis_topic;
323
324 /*!
325  * \brief Create a new topic.
326  * \param name Name of the new topic.
327  * \return New topic instance.
328  * \return \c NULL on error.
329  * \since 12
330  */
331 struct stasis_topic *stasis_topic_create(const char *name);
332
333 /*!
334  * \brief Return the name of a topic.
335  * \param topic Topic.
336  * \return Name of the topic.
337  * \return \c NULL if topic is \c NULL.
338  * \since 12
339  */
340 const char *stasis_topic_name(const struct stasis_topic *topic);
341
342 /*!
343  * \brief Publish a message to a topic's subscribers.
344  * \param topic Topic.
345  * \param message Message to publish.
346  * \since 12
347  */
348 void stasis_publish(struct stasis_topic *topic, struct stasis_message *message);
349
350 /*!
351  * \brief Wait for all pending messages on a given topic to be processed.
352  * \param topic Topic to await pending messages on.
353  * \return 0 on success.
354  * \return Non-zero on error.
355  * \since 12
356  */
357 int stasis_topic_wait(struct stasis_topic *topic);
358
359 /*! @} */
360
361 /*! @{ */
362
363 /*!
364  * \brief Opaque type for a Stasis subscription.
365  * \since 12
366  */
367 struct stasis_subscription;
368
369 /*!
370  * \brief Callback function type for Stasis subscriptions.
371  * \param data Data field provided with subscription.
372  * \param message Published message.
373  * \since 12
374  */
375 typedef void (*stasis_subscription_cb)(void *data, struct stasis_subscription *sub, struct stasis_message *message);
376
377 /*!
378  * \brief Create a subscription.
379  *
380  * In addition to being AO2 managed memory (requiring an ao2_cleanup() to free
381  * up this reference), the subscription must be explicitly unsubscribed from its
382  * topic using stasis_unsubscribe().
383  *
384  * The invocations of the callback are serialized, but may not always occur on
385  * the same thread. The invocation order of different subscriptions is
386  * unspecified.
387  *
388  * \param topic Topic to subscribe to.
389  * \param callback Callback function for subscription messages.
390  * \param data Data to be passed to the callback, in addition to the message.
391  * \return New \ref stasis_subscription object.
392  * \return \c NULL on error.
393  * \since 12
394  */
395 struct stasis_subscription *stasis_subscribe(struct stasis_topic *topic,
396         stasis_subscription_cb callback, void *data);
397
398 /*!
399  * \brief Cancel a subscription.
400  *
401  * Note that in an asynchronous system, there may still be messages queued or
402  * in transit to the subscription's callback. These will still be delivered.
403  * There will be a final 'SubscriptionCancelled' message, indicating the
404  * delivery of the final message.
405  *
406  * \param subscription Subscription to cancel.
407  * \return \c NULL for convenience
408  * \since 12
409  */
410 struct stasis_subscription *stasis_unsubscribe(
411         struct stasis_subscription *subscription);
412
413 /*!
414  * \brief Block until the last message is processed on a subscription.
415  *
416  * This function will not return until the \a subscription's callback for the
417  * stasis_subscription_final_message() completes. This allows cleanup routines
418  * to run before unblocking the joining thread.
419  *
420  * \param subscription Subscription to block on.
421  * \since 12
422  */
423 void stasis_subscription_join(struct stasis_subscription *subscription);
424
425 /*!
426  * \brief Returns whether \a subscription has received its final message.
427  *
428  * Note that a subscription is considered done even while the
429  * stasis_subscription_final_message() is being processed. This allows cleanup
430  * routines to check the status of the subscription.
431  *
432  * \param subscription Subscription.
433  * \return True (non-zero) if stasis_subscription_final_message() has been
434  *         received.
435  * \return False (zero) if waiting for the end.
436  */
437 int stasis_subscription_is_done(struct stasis_subscription *subscription);
438
439 /*!
440  * \brief Cancel a subscription, blocking until the last message is processed.
441  *
442  * While normally it's recommended to stasis_unsubscribe() and wait for
443  * stasis_subscription_final_message(), there are times (like during a module
444  * unload) where you have to wait for the final message (otherwise you'll call
445  * a function in a shared module that no longer exists).
446  *
447  * \param subscription Subscription to cancel.
448  * \return \c NULL for convenience
449  * \since 12
450  */
451 struct stasis_subscription *stasis_unsubscribe_and_join(
452         struct stasis_subscription *subscription);
453
454 struct stasis_forward;
455
456 /*!
457  * \brief Create a subscription which forwards all messages from one topic to
458  * another.
459  *
460  * Note that the \a topic parameter of the invoked callback will the be \a topic
461  * the message was sent to, not the topic the subscriber subscribed to.
462  *
463  * \param from_topic Topic to forward.
464  * \param to_topic Destination topic of forwarded messages.
465  * \return New forwarding subscription.
466  * \return \c NULL on error.
467  * \since 12
468  */
469 struct stasis_forward *stasis_forward_all(struct stasis_topic *from_topic,
470         struct stasis_topic *to_topic);
471
472 struct stasis_forward *stasis_forward_cancel(struct stasis_forward *forward);
473
474 /*!
475  * \brief Get the unique ID for the subscription.
476  *
477  * \param sub Subscription for which to get the unique ID.
478  * \return Unique ID for the subscription.
479  * \since 12
480  */
481 const char *stasis_subscription_uniqueid(const struct stasis_subscription *sub);
482
483 /*!
484  * \brief Returns whether a subscription is currently subscribed.
485  *
486  * Note that there may still be messages queued up to be dispatched to this
487  * subscription, but the stasis_subscription_final_message() has been enqueued.
488  *
489  * \param sub Subscription to check
490  * \return False (zero) if subscription is not subscribed.
491  * \return True (non-zero) if still subscribed.
492  */
493 int stasis_subscription_is_subscribed(const struct stasis_subscription *sub);
494
495 /*!
496  * \brief Determine whether a message is the final message to be received on a subscription.
497  *
498  * \param sub Subscription on which the message was received.
499  * \param msg Message to check.
500  * \return zero if the provided message is not the final message.
501  * \return non-zero if the provided message is the final message.
502  * \since 12
503  */
504 int stasis_subscription_final_message(struct stasis_subscription *sub, struct stasis_message *msg);
505
506 /*! \addtogroup StasisTopicsAndMessages
507  * @{
508  */
509
510 /*!
511  * \brief Holds details about changes to subscriptions for the specified topic
512  * \since 12
513  */
514 struct stasis_subscription_change {
515         AST_DECLARE_STRING_FIELDS(
516                 AST_STRING_FIELD(uniqueid);     /*!< The unique ID associated with this subscription */
517                 AST_STRING_FIELD(description);  /*!< The description of the change to the subscription associated with the uniqueid */
518         );
519         struct stasis_topic *topic;             /*!< The topic the subscription is/was subscribing to */
520 };
521
522 /*!
523  * \brief Gets the message type for subscription change notices
524  * \return The stasis_message_type for subscription change notices
525  * \since 12
526  */
527 struct stasis_message_type *stasis_subscription_change_type(void);
528
529 /*! @} */
530
531 /*! @{ */
532
533 /*!
534  * \brief Pool for topic aggregation
535  */
536 struct stasis_topic_pool;
537
538 /*!
539  * \brief Create a topic pool that routes messages from dynamically generated topics to the given topic
540  * \param pooled_topic Topic to which messages will be routed
541  * \return the new stasis_topic_pool
542  * \return \c NULL on failure
543  */
544 struct stasis_topic_pool *stasis_topic_pool_create(struct stasis_topic *pooled_topic);
545
546 /*!
547  * \brief Find or create a topic in the pool
548  * \param pool Pool for which to get the topic
549  * \param topic_name Name of the topic to get
550  * \return The already stored or newly allocated topic
551  * \return \c NULL if the topic was not found and could not be allocated
552  */
553 struct stasis_topic *stasis_topic_pool_get_topic(struct stasis_topic_pool *pool, const char *topic_name);
554
555 /*! @} */
556
557 /*! \addtogroup StasisTopicsAndMessages
558  * @{
559  */
560
561 /*!
562  * \brief Message type for cache update messages.
563  * \return Message type for cache update messages.
564  * \since 12
565  */
566 struct stasis_message_type *stasis_cache_update_type(void);
567
568 /*!
569  * \brief Cache update message
570  * \since 12
571  */
572 struct stasis_cache_update {
573         /*! \brief Convenience reference to snapshot type */
574         struct stasis_message_type *type;
575         /*! \brief Old value from the cache */
576         struct stasis_message *old_snapshot;
577         /*! \brief New value */
578         struct stasis_message *new_snapshot;
579 };
580
581 /*!
582  * \brief Message type for clearing a message from a stasis cache.
583  * \since 12
584  */
585 struct stasis_message_type *stasis_cache_clear_type(void);
586
587 /*! @} */
588
589 /*! @{ */
590
591 /*!
592  * \brief A message cache, for use with \ref stasis_caching_topic.
593  * \since 12
594  */
595 struct stasis_cache;
596
597 /*!
598  * \brief A topic wrapper, which caches certain messages.
599  * \since 12
600  */
601 struct stasis_caching_topic;
602
603
604 /*!
605  * \brief Callback extract a unique identity from a snapshot message.
606  *
607  * This identity is unique to the underlying object of the snapshot, such as the
608  * UniqueId field of a channel.
609  *
610  * \param message Message to extract id from.
611  * \return String representing the snapshot's id.
612  * \return \c NULL if the message_type of the message isn't a handled snapshot.
613  * \since 12
614  */
615 typedef const char *(*snapshot_get_id)(struct stasis_message *message);
616
617 /*!
618  * \brief Create a cache.
619  *
620  * This is the backend store for a \ref stasis_caching_topic. The cache is
621  * thread safe, allowing concurrent reads and writes.
622  *
623  * The returned object is AO2 managed, so ao2_cleanup() when you're done.
624  *
625  * \param id_fn Callback to extract the id from a snapshot message.
626  * \return New cache indexed by \a id_fn.
627  * \return \c NULL on error
628  * \since 12
629  */
630 struct stasis_cache *stasis_cache_create(snapshot_get_id id_fn);
631
632 /*!
633  * \brief Create a topic which monitors and caches messages from another topic.
634  *
635  * The idea is that some topics publish 'snapshots' of some other object's state
636  * that should be cached. When these snapshot messages are received, the cache
637  * is updated, and a stasis_cache_update() message is forwarded, which has both
638  * the original snapshot message and the new message.
639  *
640  * The returned object is AO2 managed, so ao2_cleanup() when done with it.
641  *
642  * \param original_topic Topic publishing snapshot messages.
643  * \param cache Backend cache in which to keep snapshots.
644  * \return New topic which changes snapshot messages to stasis_cache_update()
645  *         messages, and forwards all other messages from the original topic.
646  * \return \c NULL on error
647  * \since 12
648  */
649 struct stasis_caching_topic *stasis_caching_topic_create(
650         struct stasis_topic *original_topic, struct stasis_cache *cache);
651
652 /*!
653  * \brief Unsubscribes a caching topic from its upstream topic.
654  *
655  * This function returns immediately, so be sure to cleanup when
656  * stasis_subscription_final_message() is received.
657  *
658  * \param caching_topic Caching topic to unsubscribe
659  * \return \c NULL for convenience
660  * \since 12
661  */
662 struct stasis_caching_topic *stasis_caching_unsubscribe(
663         struct stasis_caching_topic *caching_topic);
664
665 /*!
666  * \brief Unsubscribes a caching topic from its upstream topic, blocking until
667  * all messages have been forwarded.
668  *
669  * See stasis_unsubscriben_and_join() for more info on when to use this as
670  * opposed to stasis_caching_unsubscribe().
671  *
672  * \param caching_topic Caching topic to unsubscribe
673  * \return \c NULL for convenience
674  * \since 12
675  */
676 struct stasis_caching_topic *stasis_caching_unsubscribe_and_join(
677         struct stasis_caching_topic *caching_topic);
678
679 /*!
680  * \brief Returns the topic of cached events from a caching topics.
681  * \param caching_topic The caching topic.
682  * \return The topic that publishes cache update events, along with passthrough
683  *         events from the underlying topic.
684  * \return \c NULL if \a caching_topic is \c NULL.
685  * \since 12
686  */
687 struct stasis_topic *stasis_caching_get_topic(
688         struct stasis_caching_topic *caching_topic);
689
690 /*!
691  * \brief A message which instructs the caching topic to remove an entry from
692  * its cache.
693  *
694  * \param message Message representative of the cache entry that should be
695  *                cleared. This will become the data held in the
696  *                stasis_cache_clear message.
697  *
698  * \return Message which, when sent to a \ref stasis_caching_topic, will clear
699  *         the item from the cache.
700  * \return \c NULL on error.
701  * \since 12
702  */
703 struct stasis_message *stasis_cache_clear_create(struct stasis_message *message);
704
705 /*!
706  * \brief Retrieve an item from the cache.
707  *
708  * The returned item is AO2 managed, so ao2_cleanup() when you're done with it.
709  *
710  * \param cache The cache to query.
711  * \param type Type of message to retrieve.
712  * \param id Identity of the snapshot to retrieve.
713  * \return Message from the cache.
714  * \return \c NULL if message is not found.
715  * \since 12
716  */
717 struct stasis_message *stasis_cache_get(
718         struct stasis_cache *cache, struct stasis_message_type *type,
719         const char *id);
720
721 /*!
722  * \brief Dump cached items to a subscription
723  * \param cache The cache to query.
724  * \param type Type of message to dump (any type if \c NULL).
725  * \return ao2_container containing all matches (must be unreffed by caller)
726  * \return \c NULL on allocation error
727  * \since 12
728  */
729 struct ao2_container *stasis_cache_dump(struct stasis_cache *cache,
730         struct stasis_message_type *type);
731
732 /*! @} */
733
734 /*! @{ */
735
736 /*!
737  * \internal
738  * \brief Log a message about invalid attempt to access a type.
739  */
740 void stasis_log_bad_type_access(const char *name);
741
742 /*!
743  * \brief Boiler-plate removing macro for defining message types.
744  *
745  * \code
746  *      STASIS_MESSAGE_TYPE_DEFN(ast_foo_type,
747  *              .to_ami = foo_to_ami,
748  *              .to_json = foo_to_json,
749  *              );
750  * \endcode
751  *
752  * \param name Name of message type.
753  * \param ... Virtual table methods for messages of this type.
754  * \since 12
755  */
756 #define STASIS_MESSAGE_TYPE_DEFN(name, ...)                             \
757         static struct stasis_message_vtable _priv_ ## name ## _v = {    \
758                 __VA_ARGS__                                             \
759         };                                                              \
760         static struct stasis_message_type *_priv_ ## name;              \
761         struct stasis_message_type *name(void) {                        \
762                 if (_priv_ ## name == NULL) {                           \
763                         stasis_log_bad_type_access(#name);              \
764                 }                                                       \
765                 return _priv_ ## name;                                  \
766         }
767
768 /*!
769  * \brief Boiler-plate removing macro for defining local message types.
770  *
771  * \code
772  *      STASIS_MESSAGE_TYPE_DEFN_LOCAL(ast_foo_type,
773  *              .to_ami = foo_to_ami,
774  *              .to_json = foo_to_json,
775  *              );
776  * \endcode
777  *
778  * \param name Name of message type.
779  * \param ... Virtual table methods for messages of this type.
780  * \since 12
781  */
782 #define STASIS_MESSAGE_TYPE_DEFN_LOCAL(name, ...)                       \
783         static struct stasis_message_vtable _priv_ ## name ## _v = {    \
784                 __VA_ARGS__                                             \
785         };                                                              \
786         static struct stasis_message_type *_priv_ ## name;              \
787         static struct stasis_message_type *name(void) {                 \
788                 if (_priv_ ## name == NULL) {                           \
789                         stasis_log_bad_type_access(#name);              \
790                 }                                                       \
791                 return _priv_ ## name;                                  \
792         }
793
794 /*!
795 * \brief Boiler-plate removing macro for initializing message types.
796  *
797  * \code
798  *      if (STASIS_MESSAGE_TYPE_INIT(ast_foo_type) != 0) {
799  *              return -1;
800  *      }
801  * \endcode
802  *
803  * \param name Name of message type.
804  * \return 0 if initialization is successful.
805  * \return Non-zero on failure.
806  * \since 12
807  */
808 #define STASIS_MESSAGE_TYPE_INIT(name)                                  \
809         ({                                                              \
810                 ast_assert(_priv_ ## name == NULL);                     \
811                 _priv_ ## name = stasis_message_type_create(#name,      \
812                         &_priv_ ## name ## _v);                         \
813                 _priv_ ## name ? 0 : -1;                                \
814         })
815
816 /*!
817  * \brief Boiler-plate removing macro for cleaning up message types.
818  *
819  * Note that if your type is defined in core instead of a loadable module, you
820  * should call message type cleanup from an ast_register_cleanup() handler
821  * instead of an ast_register_atexit() handler.
822  *
823  * The reason is that during an immediate shutdown, loadable modules (which may
824  * refer to core message types) are not unloaded. While the atexit handlers are
825  * run, there's a window of time where a module subscription might reference a
826  * core message type after it's been cleaned up. Which is bad.
827  *
828  * \param name Name of message type.
829  * \since 12
830  */
831 #define STASIS_MESSAGE_TYPE_CLEANUP(name)       \
832         ({                                      \
833                 ao2_cleanup(_priv_ ## name);    \
834                 _priv_ ## name = NULL;          \
835         })
836
837 /*! @} */
838
839 /*! @{ */
840
841 /*!
842  * \brief Initialize the Stasis subsystem.
843  * \return 0 on success.
844  * \return Non-zero on error.
845  * \since 12
846  */
847 int stasis_init(void);
848
849 /*! @} */
850
851 /*! @{ */
852
853 /*!
854  * \internal
855  * \brief called by stasis_init() for cache initialization.
856  * \return 0 on success.
857  * \return Non-zero on error.
858  * \since 12
859  */
860 int stasis_cache_init(void);
861
862 /*!
863  * \internal
864  * \brief called by stasis_init() for config initialization.
865  * \return 0 on success.
866  * \return Non-zero on error.
867  * \since 12
868  */
869 int stasis_config_init(void);
870
871 /*!
872  * \internal
873  */
874 int stasis_wait_init(void);
875
876 /*! @} */
877
878 /*!
879  * \defgroup StasisTopicsAndMessages Stasis topics, and their messages.
880  *
881  * This group contains the topics, messages and corresponding message types
882  * found within Asterisk.
883  */
884
885 #endif /* _ASTERISK_STASIS_H */