bridge_internal.h File Reference

Private Bridging API. More...

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

Go to the source code of this file.

Functions
struct ast_bridge *	bridge_alloc (size_t size, const struct ast_bridge_methods *v_table)
struct ast_bridge *	bridge_base_init (struct ast_bridge *self, uint32_t capabilities, unsigned int flags, const char *creator, const char *name, const char *id)
	Initialize the base class of the bridge. More...
void	bridge_dissolve (struct ast_bridge *bridge, int cause)
void	bridge_do_merge (struct ast_bridge *dst_bridge, struct ast_bridge *src_bridge, struct ast_bridge_channel **kick_me, unsigned int num_kick, unsigned int optimized)
int	bridge_do_move (struct ast_bridge *dst_bridge, struct ast_bridge_channel *bridge_channel, int attempt_recovery, unsigned int optimized)
struct ast_bridge_channel *	bridge_find_channel (struct ast_bridge *bridge, struct ast_channel *chan)
void	bridge_merge_inhibit_nolock (struct ast_bridge *bridge, int request)
void	bridge_reconfigured (struct ast_bridge *bridge, unsigned int colp_update)
struct ast_bridge *	bridge_register (struct ast_bridge *bridge)
	Register the new bridge with the system. More...

Detailed Description

Private Bridging API.

Functions in this file are intended to be used by the Bridging API, bridge mixing technologies, and bridge sub-classes. Users of bridges that do not fit those three categories should not use the API defined in this file.

Author

Mark Michelson mmich.nosp@m.elso.nosp@m.n@dig.nosp@m.ium..nosp@m.com

See Also:

• CREDITS

Definition in file bridge_internal.h.

Function Documentation

bridge_alloc()

struct ast_bridge * bridge_alloc	(	size_t	size,
		const struct ast_bridge_methods *	v_table
	)

Definition at line 706 of file bridge.c.

{
    struct ast_bridge *bridge;
 
    /* Check v_table that all methods are present. */
    if (!v_table
        || !v_table->name
        || !v_table->destroy
        || !v_table->dissolving
        || !v_table->push
        || !v_table->pull
        || !v_table->notify_masquerade
        || !v_table->get_merge_priority) {
        ast_log(LOG_ERROR, "Virtual method table for bridge class %s not complete.\n",
            v_table && v_table->name ? v_table->name : "<unknown>");
        ast_assert(0);
        return NULL;
    }
 
    bridge = ao2_alloc(size, destroy_bridge);
    if (!bridge) {
        return NULL;
    }
 
    if (ast_string_field_init(bridge, 80)) {
        ao2_cleanup(bridge);
        return NULL;
    }
 
    bridge->v_table = v_table;
 
    AST_VECTOR_INIT(&bridge->media_types, AST_MEDIA_TYPE_END);
 
    return bridge;
}

References ao2_alloc, ao2_cleanup, ast_assert, ast_log, AST_MEDIA_TYPE_END, ast_string_field_init, AST_VECTOR_INIT, ast_bridge_methods::destroy, destroy_bridge(), ast_bridge_methods::dissolving, ast_bridge_methods::get_merge_priority, LOG_ERROR, ast_bridge::media_types, ast_bridge_methods::name, ast_bridge_methods::notify_masquerade, NULL, ast_bridge_methods::pull, ast_bridge_methods::push, and ast_bridge::v_table.

Referenced by ast_bridge_base_new(), ast_bridge_basic_new(), bridge_agent_hold_new(), bridge_parking_new(), and bridge_stasis_new().

bridge_base_init()

struct ast_bridge * bridge_base_init	(	struct ast_bridge *	self,
		uint32_t	capabilities,
		unsigned int	flags,
		const char *	creator,
		const char *	name,
		const char *	id
	)

Initialize the base class of the bridge.

Parameters

self	Bridge to operate upon. (Tolerates a NULL pointer)
capabilities	The capabilities that we require to be used on the bridge
flags	Flags that will alter the behavior of the bridge
creator	Entity that created the bridge (optional)
name	Name given to the bridge by its creator (optional, requires named creator)
id	Unique ID given to the bridge by its creator (optional)

Returns

self on success

Return values

NULL	on failure, self is already destroyed

Example usage:

struct ast_bridge *bridge;
bridge = bridge_alloc(sizeof(*bridge), &ast_bridge_base_v_table);
bridge = bridge_base_init(bridge, AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP, NULL, NULL, NULL);

This creates a no frills two party bridge that will be destroyed once one of the channels hangs up.

Definition at line 742 of file bridge.c.

{
    char uuid_hold[AST_UUID_STR_LEN];
 
    if (!self) {
        return NULL;
    }
 
    if (!ast_strlen_zero(id)) {
        ast_string_field_set(self, uniqueid, id);
    } else {
        ast_uuid_generate_str(uuid_hold, AST_UUID_STR_LEN);
        ast_string_field_set(self, uniqueid, uuid_hold);
    }
    ast_string_field_set(self, creator, creator);
    if (!ast_strlen_zero(creator)) {
        ast_string_field_set(self, name, name);
    }
 
    ast_set_flag(&self->feature_flags, flags);
    self->allowed_capabilities = capabilities;
 
    if (!(flags & AST_BRIDGE_FLAG_INVISIBLE)) {
        if (bridge_topics_init(self) != 0) {
            ast_log(LOG_WARNING, "Bridge %s: Could not initialize topics\n",
                self->uniqueid);
            ao2_ref(self, -1);
            return NULL;
        }
    }
 
    /* Use our helper function to find the "best" bridge technology. */
    self->technology = find_best_technology(capabilities, self);
    if (!self->technology) {
        ast_log(LOG_WARNING, "Bridge %s: Could not create class %s.  No technology to support it.\n",
            self->uniqueid, self->v_table->name);
        ao2_ref(self, -1);
        return NULL;
    }
 
    /* Pass off the bridge to the technology to manipulate if needed */
    ast_debug(1, "Bridge %s: calling %s technology constructor\n",
        self->uniqueid, self->technology->name);
    if (self->technology->create && self->technology->create(self)) {
        ast_log(LOG_WARNING, "Bridge %s: failed to setup bridge technology %s\n",
            self->uniqueid, self->technology->name);
        ao2_ref(self, -1);
        return NULL;
    }
    ast_debug(1, "Bridge %s: calling %s technology start\n",
        self->uniqueid, self->technology->name);
    if (self->technology->start && self->technology->start(self)) {
        ast_log(LOG_WARNING, "Bridge %s: failed to start bridge technology %s\n",
            self->uniqueid, self->technology->name);
        ao2_ref(self, -1);
        return NULL;
    }
 
    if (!(flags & AST_BRIDGE_FLAG_INVISIBLE)) {
        if (!ast_bridge_topic(self)) {
            ao2_ref(self, -1);
            return NULL;
        }
    }
 
    self->creationtime = ast_tvnow();
 
    return self;
}

References ast_bridge::allowed_capabilities, ao2_ref, AST_BRIDGE_FLAG_INVISIBLE, ast_bridge_topic(), ast_debug, ast_log, ast_set_flag, ast_string_field_set, ast_strlen_zero(), ast_tvnow(), ast_uuid_generate_str(), AST_UUID_STR_LEN, bridge_topics_init(), ast_bridge_technology::create, ast_bridge::creationtime, ast_bridge::creator, ast_bridge::feature_flags, find_best_technology(), LOG_WARNING, name, ast_bridge_methods::name, ast_bridge_technology::name, NULL, ast_bridge_technology::start, ast_bridge::technology, ast_bridge::uniqueid, and ast_bridge::v_table.

Referenced by ast_bridge_base_new(), ast_bridge_basic_new(), bridge_agent_hold_new(), bridge_parking_new(), and bridge_stasis_new().

bridge_dissolve()

void bridge_dissolve	(	struct ast_bridge *	bridge,
		int	cause
	)

Definition at line 315 of file bridge.c.

{
    struct ast_bridge_channel *bridge_channel;
    struct ast_frame action = {
        .frametype = AST_FRAME_BRIDGE_ACTION,
        .subclass.integer = BRIDGE_CHANNEL_ACTION_DEFERRED_DISSOLVING,
    };
 
    if (bridge->dissolved) {
        return;
    }
    bridge->dissolved = 1;
 
    if (cause <= 0) {
        cause = AST_CAUSE_NORMAL_CLEARING;
    }
    bridge->cause = cause;
 
    ast_debug(1, "Bridge %s: dissolving bridge with cause %d(%s)\n",
        bridge->uniqueid, cause, ast_cause2str(cause));
 
    AST_LIST_TRAVERSE(&bridge->channels, bridge_channel, entry) {
        ast_bridge_channel_leave_bridge(bridge_channel,
            BRIDGE_CHANNEL_STATE_END_NO_DISSOLVE, cause);
    }
 
    /* Must defer dissolving bridge because it is already locked. */
    ast_bridge_queue_action(bridge, &action);
}

References ast_bridge_channel_leave_bridge(), ast_bridge_queue_action(), ast_cause2str(), AST_CAUSE_NORMAL_CLEARING, ast_debug, AST_FRAME_BRIDGE_ACTION, AST_LIST_TRAVERSE, BRIDGE_CHANNEL_ACTION_DEFERRED_DISSOLVING, BRIDGE_CHANNEL_STATE_END_NO_DISSOLVE, ast_bridge::cause, ast_bridge::channels, ast_bridge::dissolved, ast_frame::frametype, and ast_bridge::uniqueid.

Referenced by ast_bridge_destroy(), bridge_channel_dissolve_check(), bridge_dissolve_check_stolen(), and bridge_reconfigured().

bridge_do_merge()

void bridge_do_merge	(	struct ast_bridge *	dst_bridge,
		struct ast_bridge *	src_bridge,
		struct ast_bridge_channel **	kick_me,
		unsigned int	num_kick,
		unsigned int	optimized
	)

Definition at line 2048 of file bridge.c.

{
    struct ast_bridge_channel *bridge_channel;
    unsigned int idx;
 
    ast_debug(1, "Merging bridge %s into bridge %s\n",
        src_bridge->uniqueid, dst_bridge->uniqueid);
 
    ast_bridge_publish_merge(dst_bridge, src_bridge);
 
    /*
     * Move channels from src_bridge over to dst_bridge.
     *
     * We must use AST_LIST_TRAVERSE_SAFE_BEGIN() because
     * bridge_channel_internal_pull() alters the list we are traversing.
     */
    AST_LIST_TRAVERSE_SAFE_BEGIN(&src_bridge->channels, bridge_channel, entry) {
        if (bridge_channel->state != BRIDGE_CHANNEL_STATE_WAIT) {
            /*
             * The channel is already leaving let it leave normally because
             * pulling it may delete hooks that should run for this channel.
             */
            continue;
        }
        if (ast_test_flag(&bridge_channel->features->feature_flags,
            AST_BRIDGE_CHANNEL_FLAG_IMMOVABLE)) {
            continue;
        }
 
        if (kick_me) {
            for (idx = 0; idx < num_kick; ++idx) {
                if (bridge_channel == kick_me[idx]) {
                    ast_bridge_channel_leave_bridge(bridge_channel,
                        BRIDGE_CHANNEL_STATE_END_NO_DISSOLVE, AST_CAUSE_NORMAL_CLEARING);
                    break;
                }
            }
        }
        bridge_channel_internal_pull(bridge_channel);
        if (bridge_channel->state != BRIDGE_CHANNEL_STATE_WAIT) {
            /*
             * The channel died as a result of being pulled or it was
             * kicked.  Leave it pointing to the original bridge.
             */
            continue;
        }
 
        bridge_channel_moving(bridge_channel, bridge_channel->bridge, dst_bridge);
 
        /* Point to new bridge.*/
        bridge_channel_change_bridge(bridge_channel, dst_bridge);
 
        if (bridge_channel_internal_push(bridge_channel)) {
            ast_bridge_features_remove(bridge_channel->features,
                AST_BRIDGE_HOOK_REMOVE_ON_PULL);
            ast_bridge_channel_leave_bridge(bridge_channel,
                BRIDGE_CHANNEL_STATE_END_NO_DISSOLVE, bridge_channel->bridge->cause);
        }
    }
    AST_LIST_TRAVERSE_SAFE_END;
 
    if (kick_me) {
        /*
         * Now we can kick any channels in the dst_bridge without
         * potentially dissolving the bridge.
         */
        for (idx = 0; idx < num_kick; ++idx) {
            bridge_channel = kick_me[idx];
            ast_bridge_channel_lock(bridge_channel);
            if (bridge_channel->state == BRIDGE_CHANNEL_STATE_WAIT) {
                ast_bridge_channel_leave_bridge_nolock(bridge_channel,
                    BRIDGE_CHANNEL_STATE_END_NO_DISSOLVE, AST_CAUSE_NORMAL_CLEARING);
                bridge_channel_internal_pull(bridge_channel);
            }
            ast_bridge_channel_unlock(bridge_channel);
        }
    }
 
    bridge_reconfigured(dst_bridge, !optimized);
    bridge_reconfigured(src_bridge, !optimized);
 
    ast_debug(1, "Merged bridge %s into bridge %s\n",
        src_bridge->uniqueid, dst_bridge->uniqueid);
}

References AST_BRIDGE_CHANNEL_FLAG_IMMOVABLE, ast_bridge_channel_leave_bridge(), ast_bridge_channel_leave_bridge_nolock(), ast_bridge_channel_lock, ast_bridge_channel_unlock, ast_bridge_features_remove(), AST_BRIDGE_HOOK_REMOVE_ON_PULL, ast_bridge_publish_merge(), AST_CAUSE_NORMAL_CLEARING, ast_debug, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, ast_test_flag, ast_bridge_channel::bridge, bridge_channel_change_bridge(), bridge_channel_internal_pull(), bridge_channel_internal_push(), bridge_channel_moving(), BRIDGE_CHANNEL_STATE_END_NO_DISSOLVE, BRIDGE_CHANNEL_STATE_WAIT, bridge_reconfigured(), ast_bridge::cause, ast_bridge::channels, ast_bridge_features::feature_flags, ast_bridge_channel::features, ast_bridge_channel::state, and ast_bridge::uniqueid.

Referenced by bridge_merge(), bridge_merge_locked(), try_merge_optimize_out(), and two_bridge_attended_transfer().

bridge_do_move()

int bridge_do_move	(	struct ast_bridge *	dst_bridge,
		struct ast_bridge_channel *	bridge_channel,
		int	attempt_recovery,
		unsigned int	optimized
	)

Definition at line 2314 of file bridge.c.

{
    struct ast_bridge *orig_bridge;
    int was_in_bridge;
    int res = 0;
 
    if (bridge_channel->swap) {
        ast_debug(1, "Moving %p(%s) into bridge %s swapping with %s\n",
            bridge_channel, ast_channel_name(bridge_channel->chan), dst_bridge->uniqueid,
            ast_channel_name(bridge_channel->swap));
    } else {
        ast_debug(1, "Moving %p(%s) into bridge %s\n",
            bridge_channel, ast_channel_name(bridge_channel->chan), dst_bridge->uniqueid);
    }
 
    orig_bridge = bridge_channel->bridge;
    was_in_bridge = bridge_channel->in_bridge;
 
    bridge_channel_internal_pull(bridge_channel);
    if (bridge_channel->state != BRIDGE_CHANNEL_STATE_WAIT) {
        /*
         * The channel died as a result of being pulled.  Leave it
         * pointing to the original bridge.
         *
         * Clear out the swap channel pointer.  A ref is not held
         * by bridge_channel->swap at this point.
         */
        bridge_channel->swap = NULL;
        bridge_reconfigured(orig_bridge, 0);
        return -1;
    }
 
    /* Point to new bridge.*/
    ao2_ref(orig_bridge, +1);/* Keep a ref in case the push fails. */
    bridge_channel_change_bridge(bridge_channel, dst_bridge);
 
    bridge_channel_moving(bridge_channel, orig_bridge, dst_bridge);
 
    if (bridge_channel_internal_push_full(bridge_channel, optimized)) {
        /* Try to put the channel back into the original bridge. */
        ast_bridge_features_remove(bridge_channel->features,
            AST_BRIDGE_HOOK_REMOVE_ON_PULL);
        if (attempt_recovery && was_in_bridge) {
            /* Point back to original bridge. */
            bridge_channel_change_bridge(bridge_channel, orig_bridge);
 
            if (bridge_channel_internal_push(bridge_channel)) {
                ast_bridge_features_remove(bridge_channel->features,
                    AST_BRIDGE_HOOK_REMOVE_ON_PULL);
                ast_bridge_channel_leave_bridge(bridge_channel,
                    BRIDGE_CHANNEL_STATE_END_NO_DISSOLVE, bridge_channel->bridge->cause);
            }
        } else {
            ast_bridge_channel_leave_bridge(bridge_channel,
                BRIDGE_CHANNEL_STATE_END_NO_DISSOLVE, bridge_channel->bridge->cause);
            bridge_channel_settle_owed_events(orig_bridge, bridge_channel);
        }
        res = -1;
    } else if (!optimized) {
        bridge_channel_settle_owed_events(orig_bridge, bridge_channel);
    }
 
    bridge_reconfigured(dst_bridge, !optimized);
    bridge_reconfigured(orig_bridge, !optimized);
    ao2_ref(orig_bridge, -1);
    return res;
}

References ao2_ref, ast_bridge_channel_leave_bridge(), ast_bridge_features_remove(), AST_BRIDGE_HOOK_REMOVE_ON_PULL, ast_channel_name(), ast_debug, ast_bridge_channel::bridge, bridge_channel_change_bridge(), bridge_channel_internal_pull(), bridge_channel_internal_push(), bridge_channel_internal_push_full(), bridge_channel_moving(), bridge_channel_settle_owed_events(), BRIDGE_CHANNEL_STATE_END_NO_DISSOLVE, BRIDGE_CHANNEL_STATE_WAIT, bridge_reconfigured(), ast_bridge::cause, ast_bridge_channel::chan, ast_bridge_channel::features, ast_bridge_channel::in_bridge, NULL, ast_bridge_channel::state, ast_bridge_channel::swap, and ast_bridge::uniqueid.

Referenced by bridge_move(), bridge_move_locked(), bridge_swap_attended_transfer(), and try_swap_optimize_out().

bridge_find_channel()

struct ast_bridge_channel * bridge_find_channel	(	struct ast_bridge *	bridge,
		struct ast_channel *	chan
	)

Definition at line 1429 of file bridge.c.

{
    struct ast_bridge_channel *bridge_channel;
 
    AST_LIST_TRAVERSE(&bridge->channels, bridge_channel, entry) {
        if (bridge_channel->chan == chan) {
            break;
        }
    }
 
    return bridge_channel;
}

References AST_LIST_TRAVERSE, ast_bridge_channel::bridge, ast_bridge_channel::chan, and ast_bridge::channels.

Referenced by ast_bridge_add_channel(), ast_bridge_join(), ast_bridge_kick(), ast_bridge_notify_masquerade(), ast_bridge_remove(), ast_bridge_suspend(), ast_bridge_unsuspend(), bridge_channel_internal_push_full(), bridge_impart_internal(), bridge_merge(), bridge_merge_locked(), bridge_move_locked(), and play_uri().

bridge_merge_inhibit_nolock()

void bridge_merge_inhibit_nolock	(	struct ast_bridge *	bridge,
		int	request
	)

Definition at line 2991 of file bridge.c.

{
    int new_request;
 
    new_request = bridge->inhibit_merge + request;
    ast_assert(0 <= new_request);
    bridge->inhibit_merge = new_request;
}

References ast_assert, ast_bridge::inhibit_merge, and request().

Referenced by ast_bridge_channel_merge_inhibit(), and ast_bridge_merge_inhibit().

bridge_reconfigured()

void bridge_reconfigured	(	struct ast_bridge *	bridge,
		unsigned int	colp_update
	)

Definition at line 1403 of file bridge.c.

{
    if (!bridge->reconfigured) {
        return;
    }
    bridge->reconfigured = 0;
    if (ast_test_flag(&bridge->feature_flags, AST_BRIDGE_FLAG_SMART)
        && smart_bridge_operation(bridge)) {
        /* Smart bridge failed. */
        bridge_dissolve(bridge, 0);
        return;
    }
    bridge_complete_join(bridge);
 
    if (bridge->dissolved) {
        return;
    }
    check_bridge_play_sounds(bridge);
    set_bridge_peer_vars(bridge);
    ast_bridge_publish_state(bridge);
 
    if (colp_update) {
        bridge_reconfigured_connected_line_update(bridge);
    }
}

References AST_BRIDGE_FLAG_SMART, ast_bridge_publish_state(), ast_test_flag, ast_bridge_channel::bridge, bridge_complete_join(), bridge_dissolve(), bridge_reconfigured_connected_line_update(), check_bridge_play_sounds(), ast_bridge::dissolved, ast_bridge::feature_flags, ast_bridge::reconfigured, set_bridge_peer_vars(), and smart_bridge_operation().

Referenced by ast_bridge_notify_masquerade(), bridge_channel_handle_control(), bridge_channel_internal_join(), bridge_channel_wait(), bridge_do_merge(), and bridge_do_move().

bridge_register()

struct ast_bridge * bridge_register

(

struct ast_bridge *

bridge

)

Register the new bridge with the system.

Since

12.0.0

Parameters

bridge

What to register. (Tolerates a NULL pointer)

struct ast_bridge *ast_bridge_basic_new(uint32_t capabilities, int flags, uint32 dtmf_features)
{
    void *bridge;
 
    bridge = bridge_alloc(sizeof(struct ast_bridge_basic), &ast_bridge_basic_v_table);
    bridge = bridge_base_init(bridge, capabilities, flags);
    bridge = ast_bridge_basic_init(bridge, dtmf_features);
    bridge = bridge_register(bridge);
    return bridge;
}

Note

This must be done after a bridge constructor has completed setting up the new bridge but before it returns.

After a bridge is registered, ast_bridge_destroy() must eventually be called to get rid of the bridge.

Returns

bridge on success.

Return values

NULL

on error.

Definition at line 691 of file bridge.c.

{
    if (bridge) {
        bridge->construction_completed = 1;
        ast_bridge_lock(bridge);
        ast_bridge_publish_state(bridge);
        ast_bridge_unlock(bridge);
        if (!ao2_link(bridges, bridge)) {
            ast_bridge_destroy(bridge, 0);
            bridge = NULL;
        }
    }
    return bridge;
}

References ao2_link, ast_bridge_destroy(), ast_bridge_lock, ast_bridge_publish_state(), ast_bridge_unlock, bridges, ast_bridge::construction_completed, and NULL.

Referenced by ast_bridge_base_new(), ast_bridge_basic_new(), bridge_agent_hold_new(), bridge_parking_new(), and bridge_stasis_new().