/usr/include/asterisk/endpoints.h is in asterisk-dev 1:13.1.0~dfsg-1.1ubuntu4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | /*
* 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 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 */
|