Asterisk - The Open Source Telephony Project GIT-master-55f4e6d
endpoints.h
Go to the documentation of this file.
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 itself.
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 */
52 /*! The endpoint state is not known. */
54 /*! The endpoint is not available. */
56 /*! The endpoint is available. */
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 * \retval "?" if \a state isn't in \ref ast_endpoint_state.
66 */
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 */
77struct 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 * \retval NULL if not found.
93 *
94 * \since 12
95 */
96struct 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 * \retval NULL on error.
110 * \since 12
111 */
112struct 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 */
120void 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 * \retval NULL if endpoint is \c NULL.
131 * \since 12
132 */
133const 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 * \retval NULL if endpoint is \c NULL.
146 * \since 12
147 */
148const 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 * \retval NULL if endpoint is \c NULL.
158 * \since 12
159 */
160const char *ast_endpoint_get_id(const struct ast_endpoint *endpoint);
161
162/*!
163 * \brief Gets the state of the given endpoint.
164 *
165 * \param endpoint The endpoint.
166 * \return state.
167 * \retval AST_ENDPOINT_UNKNOWN if endpoint is \c NULL.
168 * \since 13.4
169 */
170enum ast_endpoint_state ast_endpoint_get_state(const struct ast_endpoint *endpoint);
171
172/*!
173 * \brief Updates the state of the given endpoint.
174 *
175 * \param endpoint Endpoint to modify.
176 * \param state New state.
177 * \since 12
178 */
179void ast_endpoint_set_state(struct ast_endpoint *endpoint,
181
182/*!
183 * \brief Updates the maximum number of channels an endpoint supports.
184 *
185 * Set to -1 for unlimited channels.
186 *
187 * \param endpoint Endpoint to modify.
188 * \param max_channels Maximum number of concurrent channels this endpoint
189 * supports.
190 */
191void ast_endpoint_set_max_channels(struct ast_endpoint *endpoint,
192 int max_channels);
193
194
195/*!
196 * \since 12
197 * \brief Adds a channel to the given endpoint.
198 *
199 * This updates the endpoint's statistics, as well as forwarding all of the
200 * channel's messages to the endpoint's topic.
201 *
202 * The channel is automagically removed from the endpoint when it is disposed
203 * of.
204 *
205 * \param endpoint
206 * \param chan Channel.
207 * \retval 0 on success.
208 * \retval Non-zero on error.
209 */
210int ast_endpoint_add_channel(struct ast_endpoint *endpoint,
211 struct ast_channel *chan);
212
213
214#endif /* _ASTERISK_ENDPOINTS_H */
ast_endpoint_state
Valid states for an endpoint.
Definition: endpoints.h:51
@ AST_ENDPOINT_OFFLINE
Definition: endpoints.h:55
@ AST_ENDPOINT_ONLINE
Definition: endpoints.h:57
@ AST_ENDPOINT_UNKNOWN
Definition: endpoints.h:53
void ast_endpoint_set_state(struct ast_endpoint *endpoint, enum ast_endpoint_state state)
Updates the state of the given endpoint.
struct ast_endpoint * ast_endpoint_find_by_id(const char *id)
Finds the endpoint with the given tech[/resource] id.
const char * ast_endpoint_get_tech(const struct ast_endpoint *endpoint)
Gets the technology of the given endpoint.
void ast_endpoint_shutdown(struct ast_endpoint *endpoint)
Shutsdown an ast_endpoint.
void ast_endpoint_set_max_channels(struct ast_endpoint *endpoint, int max_channels)
Updates the maximum number of channels an endpoint supports.
int ast_endpoint_add_channel(struct ast_endpoint *endpoint, struct ast_channel *chan)
Adds a channel to the given endpoint.
enum ast_endpoint_state ast_endpoint_get_state(const struct ast_endpoint *endpoint)
Gets the state of the given endpoint.
const char * ast_endpoint_get_resource(const struct ast_endpoint *endpoint)
Gets the resource name of the given endpoint.
const char * ast_endpoint_state_to_string(enum ast_endpoint_state state)
Returns a string representation of the given endpoint state.
struct ast_endpoint * ast_endpoint_create(const char *tech, const char *resource)
Create an endpoint struct.
const char * ast_endpoint_get_id(const struct ast_endpoint *endpoint)
Gets the tech/resource id of the given endpoint.
Asterisk JSON abstraction layer.
Main Channel structure associated with a channel.
const ast_string_field tech
int max_channels
Max channels for this endpoint. -1 means unlimited or unknown.
const ast_string_field resource