endpoints.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2013, Digium, Inc.
00005  *
00006  * David M. Lee, II <dlee@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 #ifndef _ASTERISK_ENDPOINTS_H
00020 #define _ASTERISK_ENDPOINTS_H
00021 
00022 /*! \file
00023  *
00024  * \brief Endpoint abstractions.
00025  *
00026  * \author David M. Lee, II <dlee@digium.com>
00027  * \since 12
00028  *
00029  * An endpoint is an external device/system that may offer/accept channels
00030  * to/from Asterisk. While this is a very useful concept for end users, it is
00031  * surprisingly \a not a core concept within Asterisk iteself.
00032  *
00033  * This file defines \ref ast_endpoint as a seperate object, which channel
00034  * drivers may use to expose their concept of an endpoint. As the channel driver
00035  * creates channels, it can use ast_endpoint_add_channel() to associate channels
00036  * to the endpoint. This updates the endpoint appropriately, and forwards all of
00037  * the channel's events to the endpoint's topic.
00038  *
00039  * In order to avoid excessive locking on the endpoint object itself, the
00040  * mutable state is not accessible via getters. Instead, you can create a
00041  * snapshot using ast_endpoint_snapshot_create() to get a consistent snapshot of
00042  * the internal state.
00043  */
00044 
00045 #include "asterisk/json.h"
00046 
00047 /*!
00048  * \brief Valid states for an endpoint.
00049  * \since 12
00050  */
00051 enum ast_endpoint_state {
00052    /*! The endpoint state is not known. */
00053    AST_ENDPOINT_UNKNOWN,
00054    /*! The endpoint is not available. */
00055    AST_ENDPOINT_OFFLINE,
00056    /*! The endpoint is available. */
00057    AST_ENDPOINT_ONLINE,
00058 };
00059 
00060 /*!
00061  * \brief Returns a string representation of the given endpoint state.
00062  *
00063  * \param state Endpoint state.
00064  * \return String representation of \a state.
00065  * \return \c "?" if \a state isn't in \ref ast_endpoint_state.
00066  */
00067 const char *ast_endpoint_state_to_string(enum ast_endpoint_state state);
00068 
00069 /*!
00070  * \brief Opaque struct representing an endpoint.
00071  *
00072  * An endpoint is an external device/system that may offer/accept channels
00073  * to/from Asterisk.
00074  *
00075  * \since 12
00076  */
00077 struct ast_endpoint;
00078 
00079 /*!
00080  * \brief Finds the endpoint with the given tech[/resource] id.
00081  *
00082  * Endpoints are refcounted, so ao2_cleanup() when you're done.
00083  *
00084  * \note The resource portion of an ID is optional. If not provided,
00085  *       an aggregate endpoint for the entire technology is returned.
00086  *       These endpoints must not be modified, but can be subscribed
00087  *       to in order to receive updates for all endpoints of a given
00088  *       technology.
00089  *
00090  * \param id Tech[/resource] id to look for.
00091  * \return Associated endpoint.
00092  * \return \c NULL if not found.
00093  *
00094  * \since 12
00095  */
00096 struct ast_endpoint *ast_endpoint_find_by_id(const char *id);
00097 
00098 /*!
00099  * \brief Create an endpoint struct.
00100  *
00101  * The endpoint is created with a state of UNKNOWN and max_channels of -1
00102  * (unlimited). While \ref ast_endpoint is AO2 managed, you have to
00103  * shut it down with ast_endpoint_shutdown() to clean up references from
00104  * subscriptions.
00105  *
00106  * \param tech Technology for this endpoint.
00107  * \param resource Name of this endpoint.
00108  * \return Newly created endpoint.
00109  * \return \c NULL on error.
00110  * \since 12
00111  */
00112 struct ast_endpoint *ast_endpoint_create(const char *tech, const char *resource);
00113 
00114 /*!
00115  * \brief Shutsdown an \ref ast_endpoint.
00116  *
00117  * \param endpoint Endpoint to shut down.
00118  * \since 12
00119  */
00120 void ast_endpoint_shutdown(struct ast_endpoint *endpoint);
00121 
00122 /*!
00123  * \brief Gets the technology of the given endpoint.
00124  *
00125  * This is an immutable string describing the channel provider technology
00126  * (SIP, IAX2, etc.).
00127  *
00128  * \param endpoint The endpoint.
00129  * \return Tec of the endpoint.
00130  * \return \c NULL if endpoint is \c NULL.
00131  * \since 12
00132  */
00133 const char *ast_endpoint_get_tech(const struct ast_endpoint *endpoint);
00134 
00135 /*!
00136  * \brief Gets the resource name of the given endpoint.
00137  *
00138  * This is unique for the endpoint's technology, and immutable.
00139  *
00140  * \note If the endpoint being queried is a technology aggregate
00141  *       endpoint, this will be an empty string.
00142  *
00143  * \param endpoint The endpoint.
00144  * \return Resource name of the endpoint.
00145  * \return \c NULL if endpoint is \c NULL.
00146  * \since 12
00147  */
00148 const char *ast_endpoint_get_resource(const struct ast_endpoint *endpoint);
00149 
00150 /*!
00151  * \brief Gets the tech/resource id of the given endpoint.
00152  *
00153  * This is unique across all endpoints, and immutable.
00154  *
00155  * \param endpoint The endpoint.
00156  * \return Tech/resource id of the endpoint.
00157  * \return \c NULL if endpoint is \c NULL.
00158  * \since 12
00159  */
00160 const char *ast_endpoint_get_id(const struct ast_endpoint *endpoint);
00161 
00162 /*!
00163  * \brief Updates the state of the given endpoint.
00164  *
00165  * \param endpoint Endpoint to modify.
00166  * \param state New state.
00167  * \since 12
00168  */
00169 void ast_endpoint_set_state(struct ast_endpoint *endpoint,
00170    enum ast_endpoint_state state);
00171 
00172 /*!
00173  * \brief Updates the maximum number of channels an endpoint supports.
00174  *
00175  * Set to -1 for unlimited channels.
00176  *
00177  * \param endpoint Endpoint to modify.
00178  * \param max_channels Maximum number of concurrent channels this endpoint
00179  *        supports.
00180  */
00181 void ast_endpoint_set_max_channels(struct ast_endpoint *endpoint,
00182    int max_channels);
00183 
00184 
00185 /*!
00186  * \since 12
00187  * \brief Adds a channel to the given endpoint.
00188  *
00189  * This updates the endpoint's statistics, as well as forwarding all of the
00190  * channel's messages to the endpoint's topic.
00191  *
00192  * The channel is automagically removed from the endpoint when it is disposed
00193  * of.
00194  *
00195  * \param endpoint
00196  * \param chan Channel.
00197  * \retval 0 on success.
00198  * \retval Non-zero on error.
00199  */
00200 int ast_endpoint_add_channel(struct ast_endpoint *endpoint,
00201    struct ast_channel *chan);
00202 
00203 
00204 #endif /* _ASTERISK_ENDPOINTS_H */

Generated on Thu Apr 16 06:27:33 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6