01e5812422d8e2acb56d62ef8992277f14474148
[asterisk/asterisk.git] / include / asterisk / stasis_internal.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * Matt Jordan <mjordan@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 STASIS_INTERNAL_H_
20 #define STASIS_INTERNAL_H_
21
22 /*! \file
23  *
24  * \brief Internal Stasis APIs.
25  *
26  * This header file is used to define functions that are shared between files that make
27  * up \ref stasis. Functions declared here should not be used by any module outside of
28  * Stasis.
29  *
30  * If you find yourself needing to call one of these functions directly, something has
31  * probably gone horribly wrong.
32  *
33  * \author Matt Jordan <mjordan@digium.com>
34  */
35
36 struct stasis_topic;
37 struct stasis_subscription;
38 struct stasis_message;
39
40 /*!
41  * \brief Create a subscription.
42  *
43  * In addition to being AO2 managed memory (requiring an ao2_cleanup() to free
44  * up this reference), the subscription must be explicitly unsubscribed from its
45  * topic using stasis_unsubscribe().
46  *
47  * The invocations of the callback are serialized, but may not always occur on
48  * the same thread. The invocation order of different subscriptions is
49  * unspecified.
50  *
51  * Note: modules outside of Stasis should use \ref stasis_subscribe.
52  *
53  * \param topic Topic to subscribe to.
54  * \param callback Callback function for subscription messages.
55  * \param data Data to be passed to the callback, in addition to the message.
56  * \param needs_mailbox Determines whether or not the subscription requires a mailbox.
57  *  Subscriptions with mailboxes will be delivered on a thread in the Stasis threadpool;
58  *  subscriptions without mailboxes will be delivered on the publisher thread.
59  * \return New \ref stasis_subscription object.
60  * \return \c NULL on error.
61  * \since 12
62  */
63 struct stasis_subscription *internal_stasis_subscribe(
64         struct stasis_topic *topic,
65         void (*stasis_subscription_cb)(void *data, struct stasis_subscription *sub, struct stasis_message *message),
66         void *data,
67         int needs_mailbox);
68
69 #endif /* STASIS_INTERNAL_H_ */