Asterisk - The Open Source Telephony Project  18.5.0
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 <[email protected]>
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 <[email protected]>
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  */
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  * \return \c "?" 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  */
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 Gets the state of the given endpoint.
164  *
165  * \param endpoint The endpoint.
166  * \return state.
167  * \return \c AST_ENDPOINT_UNKNOWN if endpoint is \c NULL.
168  * \since 13.4
169  */
170 enum 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  */
179 void 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  */
191 void 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  */
210 int ast_endpoint_add_channel(struct ast_endpoint *endpoint,
211  struct ast_channel *chan);
212 
213 
214 #endif /* _ASTERISK_ENDPOINTS_H */
Main Channel structure associated with a channel.
enum ast_endpoint_state ast_endpoint_get_state(const struct ast_endpoint *endpoint)
Gets the state of the given endpoint.
struct ast_endpoint * ast_endpoint_create(const char *tech, const char *resource)
Create an endpoint struct.
const char * ast_endpoint_get_tech(const struct ast_endpoint *endpoint)
Gets the technology of the given endpoint.
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 ast_string_field resource
ast_endpoint_state
Valid states for an endpoint.
Definition: endpoints.h:51
const char * ast_endpoint_get_resource(const struct ast_endpoint *endpoint)
Gets the resource name of the given endpoint.
Asterisk JSON abstraction layer.
int ast_endpoint_add_channel(struct ast_endpoint *endpoint, struct ast_channel *chan)
Adds a channel to the given endpoint.
const ast_string_field tech
const char * ast_endpoint_state_to_string(enum ast_endpoint_state state)
Returns a string representation of the given endpoint state.
void ast_endpoint_set_max_channels(struct ast_endpoint *endpoint, int max_channels)
Updates the maximum number of channels an endpoint supports.
int max_channels
Max channels for this endpoint. -1 means unlimited or unknown.
void ast_endpoint_shutdown(struct ast_endpoint *endpoint)
Shutsdown an ast_endpoint.
const char * ast_endpoint_get_id(const struct ast_endpoint *endpoint)
Gets the tech/resource id of the given endpoint.