bridge_roles.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  * Jonathan Rose <jrose@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 /*! \file
00020  * \brief Channel Bridging Roles API
00021  * \author Jonathan Rose <jrose@digium.com>
00022  */
00023 
00024 #ifndef _ASTERISK_BRIDGING_ROLES_H
00025 #define _ASTERISK_BRIDGING_ROLES_H
00026 
00027 #if defined(__cplusplus) || defined(c_plusplus)
00028 extern "C" {
00029 #endif
00030 
00031 #include "asterisk/linkedlists.h"
00032 
00033 #define AST_ROLE_LEN 32
00034 
00035 /*!
00036  * \brief Adds a bridge role to a channel
00037  *
00038  * \param chan Acquirer of the requested role
00039  * \param role_name Name of the role being attached
00040  *
00041  * \retval 0 on success
00042  * \retval -1 on failure
00043  */
00044 int ast_channel_add_bridge_role(struct ast_channel *chan, const char *role_name);
00045 
00046 /*!
00047  * \brief Removes a bridge role from a channel
00048  *
00049  * \param chan Channel the role is being removed from
00050  * \param role_name Name of the role being removed
00051  */
00052 void ast_channel_remove_bridge_role(struct ast_channel *chan, const char *role_name);
00053 
00054 /*!
00055  * \brief Removes all bridge roles currently on a channel
00056  *
00057  * \param chan Channel the roles are being removed from
00058  */
00059 void ast_channel_clear_bridge_roles(struct ast_channel *chan);
00060 
00061 /*!
00062  * \brief Set a role option on a channel
00063  * \param channel Channel receiving the role option
00064  * \param role_name Role the role option is applied to
00065  * \param option Name of the option
00066  * \param value Value of the option
00067  *
00068  * \param 0 on success
00069  * \retval -1 on failure
00070  */
00071 int ast_channel_set_bridge_role_option(struct ast_channel *channel, const char *role_name, const char *option, const char *value);
00072 
00073 /*!
00074  * \brief Check if a role exists on a channel
00075  *
00076  * \param channel The channel to check
00077  * \param role_name The name of the role to search for
00078  *
00079  * \retval 0 The requested role does not exist on the channel
00080  * \retval 1 The requested role exists on the channel
00081  *
00082  * This is an alternative to \ref ast_bridge_channel_has_role that is useful if bridge
00083  * roles have not yet been established on a channel's bridge_channel. A possible example of
00084  * when this could be used is in a bridge v_table's push() callback.
00085  */
00086 int ast_channel_has_role(struct ast_channel *channel, const char *role_name);
00087 
00088 /*!
00089  * \brief Retrieve the value of a requested role option from a channel
00090  *
00091  * \param channel The channel to retrieve the requested option from
00092  * \param role_name The role to which the option belongs
00093  * \param option The name of the option to retrieve
00094  *
00095  * \retval NULL The option does not exist
00096  * \retval non-NULL The value of the option
00097  *
00098  * This is an alternative to \ref ast_bridge_channel_get_role_option that is useful if bridge
00099  * roles have not yet been esstablished on a channel's bridge_channel. A possible example of
00100  * when this could be used is in a bridge v_table's push() callback.
00101  */
00102 const char *ast_channel_get_role_option(struct ast_channel *channel, const char *role_name, const char *option);
00103 
00104 /*!
00105  * \brief Check to see if a bridge channel inherited a specific role from its channel
00106  *
00107  * \param bridge_channel The bridge channel being checked
00108  * \param role_name Name of the role being checked
00109  *
00110  * \retval 0 The bridge channel does not have the requested role
00111  * \retval 1 The bridge channel does have the requested role
00112  *
00113  * \note Before a bridge_channel can effectively check roles against a bridge, ast_bridge_channel_establish_roles
00114  *       should be called on the bridge_channel so that roles and their respective role options can be copied from the channel
00115  *       datastore into the bridge_channel roles list. Otherwise this function will just return 0 because the list will be NULL.
00116  */
00117 int ast_bridge_channel_has_role(struct ast_bridge_channel *bridge_channel, const char *role_name);
00118 
00119 /*!
00120  * \brief Retrieve the value of a requested role option from a bridge channel
00121  *
00122  * \param bridge_channel The bridge channel we are retrieving the option from
00123  * \param role_name Name of the role the option will be retrieved from
00124  * \param option Name of the option we are retrieving the value of
00125  *
00126  * \retval NULL If either the role does not exist on the bridge_channel or the role does exist but the option has not been set
00127  * \retval The value of the option
00128  *
00129  * \note See ast_channel_set_role_option note about the need to call ast_bridge_channel_establish_roles.
00130  *
00131  * \note The returned character pointer is only valid as long as the bridge_channel is guaranteed to be alive and hasn't had
00132  *       ast_bridge_channel_clear_roles called against it (as this will free all roles and role options in the bridge
00133  *       channel). If you need this value after one of these destruction events occurs, you must make a local copy while it is
00134  *       still valid.
00135  */
00136 const char *ast_bridge_channel_get_role_option(struct ast_bridge_channel *bridge_channel, const char *role_name, const char *option);
00137 
00138 /*!
00139  * \brief Clone the roles from a bridge_channel's attached ast_channel onto the bridge_channel's role list
00140  *
00141  * \param bridge_channel The bridge channel that we are preparing
00142  *
00143  * \retval 0 on success
00144  * \retval -1 on failure
00145  *
00146  * \details
00147  * This function should always be called when the bridge_channel binds to an ast_channel at some point before the bridge_channel
00148  * joins or is imparted onto a bridge. Failure to do so will result in an empty role list. While the list remains established,
00149  * changes to roles on the ast_channel will not propogate to the bridge channel and roles can not be re-established on the bridge
00150  * channel without first clearing the roles with ast_bridge_roles_bridge_channel_clear_roles.
00151  */
00152 int ast_bridge_channel_establish_roles(struct ast_bridge_channel *bridge_channel);
00153 
00154 /*!
00155  * \brief Clear all roles from a bridge_channel's role list
00156  *
00157  * \param bridge_channel the bridge channel that we are scrubbing
00158  *
00159  * \details
00160  * If roles are already established on a bridge channel, ast_bridge_channel_establish_roles will fail unconditionally
00161  * without changing any roles. In order to update a bridge channel's roles, they must first be cleared from the bridge channel using
00162  * this function.
00163  *
00164  * \note
00165  * ast_bridge_channel_clear_roles also serves as the destructor for the role list of a bridge channel.
00166  */
00167 void ast_bridge_channel_clear_roles(struct ast_bridge_channel *bridge_channel);
00168 
00169 #if defined(__cplusplus) || defined(c_plusplus)
00170 }
00171 #endif
00172 
00173 #endif /* _ASTERISK_BRIDGING_ROLES_H */

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