bridge_roles.h File Reference

Channel Bridging Roles API. More...

#include "asterisk/linkedlists.h"

Include dependency graph for bridge_roles.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	AST_ROLE_LEN   32

Functions
void	ast_bridge_channel_clear_roles (struct ast_bridge_channel *bridge_channel)
	Clear all roles from a bridge_channel's role list. More...
int	ast_bridge_channel_establish_roles (struct ast_bridge_channel *bridge_channel)
	Clone the roles from a bridge_channel's attached ast_channel onto the bridge_channel's role list. More...
const char *	ast_bridge_channel_get_role_option (struct ast_bridge_channel *bridge_channel, const char *role_name, const char *option)
	Retrieve the value of a requested role option from a bridge channel. More...
int	ast_bridge_channel_has_role (struct ast_bridge_channel *bridge_channel, const char *role_name)
	Check to see if a bridge channel inherited a specific role from its channel. More...
int	ast_channel_add_bridge_role (struct ast_channel *chan, const char *role_name)
	Adds a bridge role to a channel. More...
void	ast_channel_clear_bridge_roles (struct ast_channel *chan)
	Removes all bridge roles currently on a channel. More...
const char *	ast_channel_get_role_option (struct ast_channel *channel, const char *role_name, const char *option)
	Retrieve the value of a requested role option from a channel. More...
int	ast_channel_has_role (struct ast_channel *channel, const char *role_name)
	Check if a role exists on a channel. More...
void	ast_channel_remove_bridge_role (struct ast_channel *chan, const char *role_name)
	Removes a bridge role from a channel. More...
int	ast_channel_set_bridge_role_option (struct ast_channel *channel, const char *role_name, const char *option, const char *value)
	Set a role option on a channel. More...

Detailed Description

Channel Bridging Roles API.

Author

Jonathan Rose jrose.nosp@m.@dig.nosp@m.ium.c.nosp@m.om

Definition in file bridge_roles.h.

Macro Definition Documentation

AST_ROLE_LEN

#define AST_ROLE_LEN   32

Definition at line 33 of file bridge_roles.h.

Function Documentation

ast_bridge_channel_clear_roles()

void ast_bridge_channel_clear_roles

(

struct ast_bridge_channel *

bridge_channel

)

Clear all roles from a bridge_channel's role list.

Parameters

bridge_channel

the bridge channel that we are scrubbing

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.

Definition at line 495 of file bridge_roles.c.

References bridge_role_datastore_destroy(), ast_bridge_channel::bridge_roles, and NULL.

Referenced by agent_alert(), ast_bridge_channel_establish_roles(), and bridge_channel_internal_pull().

{
   if (bridge_channel->bridge_roles) {
      bridge_role_datastore_destroy(bridge_channel->bridge_roles);
      bridge_channel->bridge_roles = NULL;
   }
}

ast_bridge_channel_establish_roles()

int ast_bridge_channel_establish_roles

(

struct ast_bridge_channel *

bridge_channel

)

Clone the roles from a bridge_channel's attached ast_channel onto the bridge_channel's role list.

Parameters

bridge_channel

The bridge channel that we are preparing

Return values

0	on success
-1	on failure

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.

Definition at line 447 of file bridge_roles.c.

References ast_bridge_channel_clear_roles(), ast_calloc, ast_debug, AST_LIST_LAST, AST_LIST_TRAVERSE, ast_bridge_channel::bridge_roles, ast_bridge_channel::chan, fetch_bridge_roles_datastore(), bridge_role_option::list, NULL, bridge_role_option::option, bridge_role::options, bridge_role::role, bridge_roles_datastore::role_list, setup_bridge_role(), setup_bridge_role_option(), and bridge_role_option::value.

Referenced by agent_alert(), and bridge_channel_internal_push_full().

{
   struct bridge_roles_datastore *roles_datastore;
   struct bridge_role *role = NULL;
   struct bridge_role_option *role_option;

   if (!bridge_channel->chan) {
      ast_debug(2, "Attempted to set roles on a bridge channel that has no associated channel. That's a bad idea.\n");
      return -1;
   }

   if (bridge_channel->bridge_roles) {
      ast_debug(2, "Attempted to reset roles while roles were already established. Purge existing roles first.\n");
      return -1;
   }

   roles_datastore = fetch_bridge_roles_datastore(bridge_channel->chan);
   if (!roles_datastore) {
      /* No roles to establish. */
      return 0;
   }

   if (!(bridge_channel->bridge_roles = ast_calloc(1, sizeof(*bridge_channel->bridge_roles)))) {
      return -1;
   }

   AST_LIST_TRAVERSE(&roles_datastore->role_list, role, list) {
      struct bridge_role *this_role_copy;

      if (setup_bridge_role(bridge_channel->bridge_roles, role->role)) {
         /* We need to abandon the copy because we couldn't setup a role */
         ast_bridge_channel_clear_roles(bridge_channel);
         return -1;
      }
      this_role_copy = AST_LIST_LAST(&bridge_channel->bridge_roles->role_list);

      AST_LIST_TRAVERSE(&role->options, role_option, list) {
         if (setup_bridge_role_option(this_role_copy, role_option->option, role_option->value)) {
            /* We need to abandon the copy because we couldn't setup a role option */
            ast_bridge_channel_clear_roles(bridge_channel);
            return -1;
         }
      }
   }

   return 0;
}

ast_bridge_channel_get_role_option()

const char* ast_bridge_channel_get_role_option	(	struct ast_bridge_channel *	bridge_channel,
		const char *	role_name,
		const char *	option
	)

Retrieve the value of a requested role option from a bridge channel.

Parameters

bridge_channel	The bridge channel we are retrieving the option from
role_name	Name of the role the option will be retrieved from
option	Name of the option we are retrieving the value of

Return values

NULL	If either the role does not exist on the bridge_channel or the role does exist but the option has not been set
The	value of the option

Note

See ast_channel_set_role_option note about the need to call ast_bridge_channel_establish_roles.

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.

Definition at line 427 of file bridge_roles.c.

References ast_bridge_channel::bridge_roles, get_role_from_datastore(), get_role_option(), NULL, bridge_role::role, and bridge_role_option::value.

Referenced by bridge_parking_push(), participant_entertainment_start(), and participant_idle_mode_setup().

{
   struct bridge_role *role;
   struct bridge_role_option *role_option = NULL;

   if (!bridge_channel->bridge_roles) {
      return NULL;
   }

   role = get_role_from_datastore(bridge_channel->bridge_roles, role_name);

   if (!role) {
      return NULL;
   }

   role_option = get_role_option(role, option);

   return role_option ? role_option->value : NULL;
}

ast_bridge_channel_has_role()

int ast_bridge_channel_has_role	(	struct ast_bridge_channel *	bridge_channel,
		const char *	role_name
	)

Check to see if a bridge channel inherited a specific role from its channel.

Parameters

bridge_channel	The bridge channel being checked
role_name	Name of the role being checked

Return values

0	The bridge channel does not have the requested role
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.

Definition at line 418 of file bridge_roles.c.

References ast_bridge_channel::bridge_roles, and get_role_from_datastore().

Referenced by bridge_parking_push(), and holding_bridge_join().

{
   if (!bridge_channel->bridge_roles) {
      return 0;
   }

   return get_role_from_datastore(bridge_channel->bridge_roles, role_name) ? 1 : 0;
}

ast_channel_add_bridge_role()

int ast_channel_add_bridge_role	(	struct ast_channel *	chan,
		const char *	role_name
	)

Adds a bridge role to a channel.

Parameters

chan	Acquirer of the requested role
role_name	Name of the role being attached

Return values

0	on success
-1	on failure

Definition at line 317 of file bridge_roles.c.

References ast_channel_name(), ast_debug, ast_log, fetch_or_create_bridge_roles_datastore(), get_role_from_datastore(), LOG_WARNING, and setup_bridge_role().

Referenced by add_transferer_role(), announce_request(), app_control_add_role(), bridge_agent_hold_push(), bridge_stasis_push(), media_request_helper(), parking_channel_set_roles(), process_options(), and rec_request().

{
   struct bridge_roles_datastore *roles_datastore = fetch_or_create_bridge_roles_datastore(chan);

   if (!roles_datastore) {
      ast_log(LOG_WARNING, "Unable to set up bridge role datastore on channel %s\n", ast_channel_name(chan));
      return -1;
   }

   /* Check to make sure we aren't adding a redundant role */
   if (get_role_from_datastore(roles_datastore, role_name)) {
      ast_debug(2, "Bridge role %s is already applied to the channel %s\n", role_name, ast_channel_name(chan));
      return 0;
   }

   /* It wasn't already there, so we can just finish setting it up now. */
   return setup_bridge_role(roles_datastore, role_name);
}

ast_channel_clear_bridge_roles()

void ast_channel_clear_bridge_roles

(

struct ast_channel *

chan

)

Removes all bridge roles currently on a channel.

Parameters

chan	Channel the roles are being removed from

Definition at line 360 of file bridge_roles.c.

References ast_channel_name(), ast_debug, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, bridge_role_destroy(), fetch_bridge_roles_datastore(), bridge_role_option::list, bridge_role::role, and bridge_roles_datastore::role_list.

Referenced by app_control_clear_roles(), and bridge_stasis_pull().

{
   struct bridge_roles_datastore *roles_datastore = fetch_bridge_roles_datastore(chan);
   struct bridge_role *role;

   if (!roles_datastore) {
      /* The roles datastore didn't already exist, so there is no need to remove any roles */
      ast_debug(2, "Roles did not exist on channel %s\n", ast_channel_name(chan));
      return;
   }

   AST_LIST_TRAVERSE_SAFE_BEGIN(&roles_datastore->role_list, role, list) {
      ast_debug(2, "Removing bridge role %s from channel %s\n", role->role, ast_channel_name(chan));
      AST_LIST_REMOVE_CURRENT(list);
      bridge_role_destroy(role);
   }
   AST_LIST_TRAVERSE_SAFE_END;
}

ast_channel_get_role_option()

const char* ast_channel_get_role_option	(	struct ast_channel *	channel,
		const char *	role_name,
		const char *	option
	)

Retrieve the value of a requested role option from a channel.

Parameters

channel	The channel to retrieve the requested option from
role_name	The role to which the option belongs
option	The name of the option to retrieve

Return values

NULL	The option does not exist
non-NULL	The value of the option

This is an alternative to 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.

Definition at line 403 of file bridge_roles.c.

References get_role_from_channel(), get_role_option(), NULL, bridge_role::role, and bridge_role_option::value.

Referenced by bridge_personality_atxfer_push().

{
   struct bridge_role *role;
   struct bridge_role_option *role_option;

   role = get_role_from_channel(channel, role_name);
   if (!role) {
      return NULL;
   }

   role_option = get_role_option(role, option);

   return role_option ? role_option->value : NULL;
}

ast_channel_has_role()

int ast_channel_has_role	(	struct ast_channel *	channel,
		const char *	role_name
	)

Check if a role exists on a channel.

Parameters

channel	The channel to check
role_name	The name of the role to search for

Return values

0	The requested role does not exist on the channel
1	The requested role exists on the channel

This is an alternative to 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.

Definition at line 398 of file bridge_roles.c.

References get_role_from_channel().

Referenced by bridge_personality_atxfer_push(), bridge_stasis_push(), and handle_hangup().

{
   return get_role_from_channel(channel, role_name) ? 1 : 0;
}

ast_channel_remove_bridge_role()

void ast_channel_remove_bridge_role	(	struct ast_channel *	chan,
		const char *	role_name
	)

Removes a bridge role from a channel.

Parameters

chan	Channel the role is being removed from
role_name	Name of the role being removed

Definition at line 336 of file bridge_roles.c.

References ast_channel_name(), ast_debug, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, bridge_role_destroy(), fetch_bridge_roles_datastore(), bridge_role_option::list, bridge_role::role, and bridge_roles_datastore::role_list.

Referenced by attended_transfer_properties_shutdown(), bridge_agent_hold_pull(), and bridge_agent_hold_push().

{
   struct bridge_roles_datastore *roles_datastore = fetch_bridge_roles_datastore(chan);
   struct bridge_role *role;

   if (!roles_datastore) {
      /* The roles datastore didn't already exist, so there is no need to remove a role */
      ast_debug(2, "Role %s did not exist on channel %s\n", role_name, ast_channel_name(chan));
      return;
   }

   AST_LIST_TRAVERSE_SAFE_BEGIN(&roles_datastore->role_list, role, list) {
      if (!strcmp(role->role, role_name)) {
         ast_debug(2, "Removing bridge role %s from channel %s\n", role_name, ast_channel_name(chan));
         AST_LIST_REMOVE_CURRENT(list);
         bridge_role_destroy(role);
         return;
      }
   }
   AST_LIST_TRAVERSE_SAFE_END;

   ast_debug(2, "Role %s did not exist on channel %s\n", role_name, ast_channel_name(chan));
}

ast_channel_set_bridge_role_option()

int ast_channel_set_bridge_role_option	(	struct ast_channel *	channel,
		const char *	role_name,
		const char *	option,
		const char *	value
	)

Set a role option on a channel.

Parameters

channel	Channel receiving the role option
role_name	Role the role option is applied to
option	Name of the option
value	Value of the option
0	on success

Return values

-1	on failure

Definition at line 379 of file bridge_roles.c.

References ast_string_field_set, get_role_from_channel(), get_role_option(), bridge_role::role, and setup_bridge_role_option().

Referenced by add_transferer_role(), agent_alert(), apply_option_entertainment(), apply_option_moh(), bridge_agent_hold_push(), bridge_stasis_push(), and parking_channel_set_roles().

{
   struct bridge_role *role = get_role_from_channel(channel, role_name);
   struct bridge_role_option *role_option;

   if (!role) {
      return -1;
   }

   role_option = get_role_option(role, option);

   if (role_option) {
      ast_string_field_set(role_option, value, value);
      return 0;
   }

   return setup_bridge_role_option(role, option, value);
}