ARI: Fix endpoint/channel subscription issues; allow for subscriptions to tech
[asterisk/asterisk.git] / include / asterisk / endpoints.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_ENDPOINTS_H
20 #define _ASTERISK_ENDPOINTS_H
21
22 /*! \file
23  *
24  * \brief Endpoint abstractions.
25  *
26  * \author David M. Lee, II <dlee@digium.com>
27  * \since 12
28  *
29  * An endpoint is an external device/system that may offer/accept channels
30  * to/from Asterisk. While this is a very useful concept for end users, it is
31  * surprisingly \a not a core concept within Asterisk iteself.
32  *
33  * This file defines \ref ast_endpoint as a seperate object, which channel
34  * drivers may use to expose their concept of an endpoint. As the channel driver
35  * creates channels, it can use ast_endpoint_add_channel() to associate channels
36  * to the endpoint. This updates the endpoint appropriately, and forwards all of
37  * the channel's events to the endpoint's topic.
38  *
39  * In order to avoid excessive locking on the endpoint object itself, the
40  * mutable state is not accessible via getters. Instead, you can create a
41  * snapshot using ast_endpoint_snapshot_create() to get a consistent snapshot of
42  * the internal state.
43  */
44
45 #include "asterisk/json.h"
46
47 /*!
48  * \brief Valid states for an endpoint.
49  * \since 12
50  */
51 enum ast_endpoint_state {
52         /*! The endpoint state is not known. */
53         AST_ENDPOINT_UNKNOWN,
54         /*! The endpoint is not available. */
55         AST_ENDPOINT_OFFLINE,
56         /*! The endpoint is available. */
57         AST_ENDPOINT_ONLINE,
58 };
59
60 /*!
61  * \brief Returns a string representation of the given endpoint state.
62  *
63  * \param state Endpoint state.
64  * \return String representation of \a state.
65  * \return \c "?" if \a state isn't in \ref ast_endpoint_state.
66  */
67 const char *ast_endpoint_state_to_string(enum ast_endpoint_state state);
68
69 /*!
70  * \brief Opaque struct representing an endpoint.
71  *
72  * An endpoint is an external device/system that may offer/accept channels
73  * to/from Asterisk.
74  *
75  * \since 12
76  */
77 struct ast_endpoint;
78
79 /*!
80  * \brief Finds the endpoint with the given tech[/resource] id.
81  *
82  * Endpoints are refcounted, so ao2_cleanup() when you're done.
83  *
84  * \note The resource portion of an ID is optional. If not provided,
85  *       an aggregate endpoint for the entire technology is returned.
86  *       These endpoints must not be modified, but can be subscribed
87  *       to in order to receive updates for all endpoints of a given
88  *       technology.
89  *
90  * \param id Tech[/resource] id to look for.
91  * \return Associated endpoint.
92  * \return \c NULL if not found.
93  *
94  * \since 12
95  */
96 struct ast_endpoint *ast_endpoint_find_by_id(const char *id);
97
98 /*!
99  * \brief Create an endpoint struct.
100  *
101  * The endpoint is created with a state of UNKNOWN and max_channels of -1
102  * (unlimited). While \ref ast_endpoint is AO2 managed, you have to
103  * shut it down with ast_endpoint_shutdown() to clean up references from
104  * subscriptions.
105  *
106  * \param tech Technology for this endpoint.
107  * \param resource Name of this endpoint.
108  * \return Newly created endpoint.
109  * \return \c NULL on error.
110  * \since 12
111  */
112 struct ast_endpoint *ast_endpoint_create(const char *tech, const char *resource);
113
114 /*!
115  * \brief Shutsdown an \ref ast_endpoint.
116  *
117  * \param endpoint Endpoint to shut down.
118  * \since 12
119  */
120 void ast_endpoint_shutdown(struct ast_endpoint *endpoint);
121
122 /*!
123  * \brief Gets the technology of the given endpoint.
124  *
125  * This is an immutable string describing the channel provider technology
126  * (SIP, IAX2, etc.).
127  *
128  * \param endpoint The endpoint.
129  * \return Tec of the endpoint.
130  * \return \c NULL if endpoint is \c NULL.
131  * \since 12
132  */
133 const char *ast_endpoint_get_tech(const struct ast_endpoint *endpoint);
134
135 /*!
136  * \brief Gets the resource name of the given endpoint.
137  *
138  * This is unique for the endpoint's technology, and immutable.
139  *
140  * \note If the endpoint being queried is a technology aggregate
141  *       endpoint, this will be an empty string.
142  *
143  * \param endpoint The endpoint.
144  * \return Resource name of the endpoint.
145  * \return \c NULL if endpoint is \c NULL.
146  * \since 12
147  */
148 const char *ast_endpoint_get_resource(const struct ast_endpoint *endpoint);
149
150 /*!
151  * \brief Gets the tech/resource id of the given endpoint.
152  *
153  * This is unique across all endpoints, and immutable.
154  *
155  * \param endpoint The endpoint.
156  * \return Tech/resource id of the endpoint.
157  * \return \c NULL if endpoint is \c NULL.
158  * \since 12
159  */
160 const char *ast_endpoint_get_id(const struct ast_endpoint *endpoint);
161
162 /*!
163  * \brief Updates the state of the given endpoint.
164  *
165  * \param endpoint Endpoint to modify.
166  * \param state New state.
167  * \since 12
168  */
169 void ast_endpoint_set_state(struct ast_endpoint *endpoint,
170         enum ast_endpoint_state state);
171
172 /*!
173  * \brief Updates the maximum number of channels an endpoint supports.
174  *
175  * Set to -1 for unlimited channels.
176  *
177  * \param endpoint Endpoint to modify.
178  * \param max_channels Maximum number of concurrent channels this endpoint
179  *        supports.
180  */
181 void ast_endpoint_set_max_channels(struct ast_endpoint *endpoint,
182         int max_channels);
183
184
185 /*!
186  * \since 12
187  * \brief Adds a channel to the given endpoint.
188  *
189  * This updates the endpoint's statistics, as well as forwarding all of the
190  * channel's messages to the endpoint's topic.
191  *
192  * The channel is automagically removed from the endpoint when it is disposed
193  * of.
194  *
195  * \param endpoint
196  * \param chan Channel.
197  * \retval 0 on success.
198  * \retval Non-zero on error.
199  */
200 int ast_endpoint_add_channel(struct ast_endpoint *endpoint,
201         struct ast_channel *chan);
202
203
204 #endif /* _ASTERISK_ENDPOINTS_H */