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