diff options
author | Matthew Jordan <mjordan@digium.com> | 2013-07-25 04:06:32 +0000 |
---|---|---|
committer | Matthew Jordan <mjordan@digium.com> | 2013-07-25 04:06:32 +0000 |
commit | cafc1158961f28ad54ebcdc5e042bf8094cbc620 (patch) | |
tree | 2e54d30ea5d8db7e007ff5c653c5acd4ed3fb649 /include/asterisk/bridge_roles.h | |
parent | 9d8a5ceb02f6559940bd94aaf163a544ce6e6f4c (diff) |
A great big renaming patch
This patch renames the bridging* files to bridge*. This may seem pedantic
and silly, but it fits better in line with current Asterisk naming conventions:
* channel is not "channeling"
* monitor is not "monitoring"
etc.
A bridge is an object. It is a first class citizen in Asterisk. "Bridging" is
the act of using a bridge on a set of channels - and the API that fulfills that
role is more than just the action.
(closes issue ASTERISK-22130)
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@395378 65c4cc65-6c06-0410-ace0-fbb531ad65f3
Diffstat (limited to 'include/asterisk/bridge_roles.h')
-rw-r--r-- | include/asterisk/bridge_roles.h | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/include/asterisk/bridge_roles.h b/include/asterisk/bridge_roles.h new file mode 100644 index 000000000..d90e564b7 --- /dev/null +++ b/include/asterisk/bridge_roles.h @@ -0,0 +1,166 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2013, Digium, Inc. + * + * Jonathan Rose <jrose@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. + */ + +/*! \file + * \brief Channel Bridging Roles API + * \author Jonathan Rose <jrose@digium.com> + */ + +#ifndef _ASTERISK_BRIDGING_ROLES_H +#define _ASTERISK_BRIDGING_ROLES_H + +#if defined(__cplusplus) || defined(c_plusplus) +extern "C" { +#endif + +#include "asterisk/linkedlists.h" + +#define AST_ROLE_LEN 32 + +/*! + * \brief Adds a bridge role to a channel + * + * \param chan Acquirer of the requested role + * \param role_name Name of the role being attached + * + * \retval 0 on success + * \retval -1 on failure + */ +int ast_channel_add_bridge_role(struct ast_channel *chan, const char *role_name); + +/*! + * \brief Removes a bridge role from a channel + * + * \param chan Channel the role is being removed from + * \param role_name Name of the role being removed + */ +void ast_channel_remove_bridge_role(struct ast_channel *chan, const char *role_name); + +/*! + * \brief Set a role option on a channel + * \param channel Channel receiving the role option + * \param role_name Role the role option is applied to + * \param option Name of the option + * \param value Value of the option + * + * \param 0 on success + * \retval -1 on failure + */ +int ast_channel_set_bridge_role_option(struct ast_channel *channel, const char *role_name, const char *option, const char *value); + +/*! + * \brief Check if a role exists on a channel + * + * \param channel The channel to check + * \param role_name The name of the role to search for + * + * \retval 0 The requested role does not exist on the channel + * \retval 1 The requested role exists on the channel + * + * This is an alternative to \ref ast_bridge_channel_has_role that is useful if bridge + * roles have not yet been established on a channel's bridge_channel. A possible example of + * when this could be used is in a bridge v_table's push() callback. + */ +int ast_channel_has_role(struct ast_channel *channel, const char *role_name); + +/*! + * \brief Retrieve the value of a requested role option from a channel + * + * \param channel The channel to retrieve the requested option from + * \param role_name The role to which the option belongs + * \param option The name of the option to retrieve + * + * \retval NULL The option does not exist + * \retval non-NULL The value of the option + * + * This is an alternative to \ref ast_bridge_channel_get_role_option that is useful if bridge + * roles have not yet been esstablished on a channel's bridge_channel. A possible example of + * when this could be used is in a bridge v_table's push() callback. + */ +const char *ast_channel_get_role_option(struct ast_channel *channel, const char *role_name, const char *option); + +/*! + * \brief Check to see if a bridge channel inherited a specific role from its channel + * + * \param bridge_channel The bridge channel being checked + * \param role_name Name of the role being checked + * + * \retval 0 The bridge channel does not have the requested role + * \retval 1 The bridge channel does have the requested role + * + * \note Before a bridge_channel can effectively check roles against a bridge, ast_bridge_channel_establish_roles + * should be called on the bridge_channel so that roles and their respective role options can be copied from the channel + * datastore into the bridge_channel roles list. Otherwise this function will just return 0 because the list will be NULL. + */ +int ast_bridge_channel_has_role(struct ast_bridge_channel *bridge_channel, const char *role_name); + +/*! + * \brief Retrieve the value of a requested role option from a bridge channel + * + * \param bridge_channel The bridge channel we are retrieving the option from + * \param role_name Name of the role the option will be retrieved from + * \param option Name of the option we are retrieving the value of + * + * \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 + * \retval The value of the option + * + * \note See ast_channel_set_role_option note about the need to call ast_bridge_channel_establish_roles. + * + * \note The returned character pointer is only valid as long as the bridge_channel is guaranteed to be alive and hasn't had + * ast_bridge_channel_clear_roles called against it (as this will free all roles and role options in the bridge + * channel). If you need this value after one of these destruction events occurs, you must make a local copy while it is + * still valid. + */ +const char *ast_bridge_channel_get_role_option(struct ast_bridge_channel *bridge_channel, const char *role_name, const char *option); + +/*! + * \brief Clone the roles from a bridge_channel's attached ast_channel onto the bridge_channel's role list + * + * \param bridge_channel The bridge channel that we are preparing + * + * \retval 0 on success + * \retval -1 on failure + * + * \details + * This function should always be called when the bridge_channel binds to an ast_channel at some point before the bridge_channel + * joins or is imparted onto a bridge. Failure to do so will result in an empty role list. While the list remains established, + * changes to roles on the ast_channel will not propogate to the bridge channel and roles can not be re-established on the bridge + * channel without first clearing the roles with ast_bridge_roles_bridge_channel_clear_roles. + */ +int ast_bridge_channel_establish_roles(struct ast_bridge_channel *bridge_channel); + +/*! + * \brief Clear all roles from a bridge_channel's role list + * + * \param bridge_channel the bridge channel that we are scrubbing + * + * \details + * If roles are already established on a bridge channel, ast_bridge_channel_establish_roles will fail unconditionally + * without changing any roles. In order to update a bridge channel's roles, they must first be cleared from the bridge channel using + * this function. + * + * \note + * ast_bridge_channel_clear_roles also serves as the destructor for the role list of a bridge channel. + */ +void ast_bridge_channel_clear_roles(struct ast_bridge_channel *bridge_channel); + +#if defined(__cplusplus) || defined(c_plusplus) +} +#endif + +#endif /* _ASTERISK_BRIDGING_ROLES_H */ |