parking_controller.c File Reference

Parking Entry, Exit, and other assorted controls. More...

#include "asterisk.h"
#include "asterisk/logger.h"
#include "res_parking.h"
#include "asterisk/astobj2.h"
#include "asterisk/utils.h"
#include "asterisk/manager.h"
#include "asterisk/test.h"
#include "asterisk/features.h"
#include "asterisk/bridge_basic.h"

Include dependency graph for parking_controller.c:

Go to the source code of this file.

Data Structures
struct	parking_limits_pvt

Functions
int	comeback_goto (struct parked_user *pu, struct parking_lot *lot)
	Set a channel's position in the PBX after timeout using the parking lot settings.
void	flatten_dial_string (char *dialstring)
	Flattens a dial string so that it can be written to/found from PBX extensions.
void	parked_call_retrieve_enable_features (struct ast_channel *chan, struct parking_lot *lot, int recipient_mode)
	Apply features based on the parking lot feature options.
int	parking_channel_set_roles (struct ast_channel *chan, struct parking_lot *lot, int force_ringing)
	Set necessary bridge roles on a channel that is about to enter a parking lot.
struct ast_bridge *	parking_lot_get_bridge (struct parking_lot *lot)
	Get a reference to a parking lot's bridge. If it doesn't exist, create it and get a reference.
int	parking_lot_get_space (struct parking_lot *lot, int target_override)
	Get an available parking space within a parking lot.
struct parked_user *	parking_lot_inspect_parked_user (struct parking_lot *lot, int target)
	Determine if there is a parked user in a parking space and return it if there is.
struct parked_user *	parking_lot_retrieve_parked_user (struct parking_lot *lot, int target)
	Determine if there is a parked user in a parking space and pull it from the parking lot if there is.
static int	retrieve_parked_user_targeted (void *obj, void *arg, int flags)
int	unpark_parked_user (struct parked_user *pu)
	Pull a parked user out of its parking lot. Use this when you don't want to use the parked user afterwards.

Detailed Description

Parking Entry, Exit, and other assorted controls.

Author

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

Definition in file parking_controller.c.

Function Documentation

comeback_goto()

int comeback_goto	(	struct parked_user *	pu,
		struct parking_lot *	lot
	)

Set a channel's position in the PBX after timeout using the parking lot settings.

Since

12.0.0

Parameters

pu	Parked user who is entering/reentering the PBX
lot	Parking lot the user was removed from.

Return values

0	Position set successfully
-1	Failed to set the position

Definition at line 263 of file parking_controller.c.

{
    struct ast_channel *chan = pu->chan;
    char *peername_flat = ast_strdupa(pu->parker_dial_string);
 
    /* Flatten the peername so that it can be used for performing the timeout PBX operations */
    flatten_dial_string(peername_flat);
 
    if (lot->cfg->comebacktoorigin) {
        if (ast_exists_extension(chan, PARK_DIAL_CONTEXT, peername_flat, 1, NULL)) {
            ast_async_goto(chan, PARK_DIAL_CONTEXT, peername_flat, 1);
            return 0;
        } else {
            ast_log(LOG_ERROR, "Can not start %s at %s,%s,1 because extension does not exist. Terminating call.\n",
                ast_channel_name(chan), PARK_DIAL_CONTEXT, peername_flat);
            return -1;
        }
    }
 
    if (ast_exists_extension(chan, lot->cfg->comebackcontext, peername_flat, 1, NULL)) {
        ast_async_goto(chan, lot->cfg->comebackcontext, peername_flat, 1);
        return 0;
    }
 
    if (ast_exists_extension(chan, lot->cfg->comebackcontext, "s", 1, NULL)) {
        ast_verb(2, "Could not start %s at %s,%s,1. Using 's@%s' instead.\n", ast_channel_name(chan),
            lot->cfg->comebackcontext, peername_flat, lot->cfg->comebackcontext);
        ast_async_goto(chan, lot->cfg->comebackcontext, "s", 1);
        return 0;
    }
 
    ast_verb(2, "Can not start %s at %s,%s,1 and exten 's@%s' does not exist. Using 's@default'\n",
        ast_channel_name(chan),
        lot->cfg->comebackcontext, peername_flat, lot->cfg->comebackcontext);
    ast_async_goto(chan, "default", "s", 1);
 
    return 0;
}

References ast_async_goto(), ast_channel_name(), ast_exists_extension(), ast_log, ast_strdupa, ast_verb, parking_lot::cfg, parked_user::chan, parking_lot_cfg::comebackcontext, parking_lot_cfg::comebacktoorigin, flatten_dial_string(), LOG_ERROR, NULL, PARK_DIAL_CONTEXT, and parked_user::parker_dial_string.

Referenced by parking_duration_callback().

flatten_dial_string()

void flatten_dial_string

(

char *

dialstring

)

Flattens a dial string so that it can be written to/found from PBX extensions.

Since

12.0.0

Parameters

dialstring

unflattened dial string. This will be flattened in place.

Definition at line 251 of file parking_controller.c.

{
    int i;
 
    for (i = 0; dialstring[i]; i++) {
        if (dialstring[i] == '/') {
            /* The underscore is the flattest character of all. */
            dialstring[i] = '_';
        }
    }
}

Referenced by comeback_goto(), and parking_duration_callback().

parked_call_retrieve_enable_features()

void parked_call_retrieve_enable_features	(	struct ast_channel *	chan,
		struct parking_lot *	lot,
		int	recipient_mode
	)

Apply features based on the parking lot feature options.

Since

12.0.0

Parameters

chan	Which channel's feature set is being modified
lot	parking lot which establishes the features used
recipient_mode	AST_FEATURE_FLAG_BYCALLER if the user is the retriever AST_FEATURE_FLAG_BYCALLEE if the user is the parkee

Definition at line 217 of file parking_controller.c.

{
    /* Enabling features here should be additive to features that are already on the channel. */
    struct ast_flags feature_flags = { 0 };
    struct ast_flags *existing_features;
 
    ast_channel_lock(chan);
    existing_features = ast_bridge_features_ds_get(chan);
    if (existing_features) {
        feature_flags = *existing_features;
    }
 
    if (lot->cfg->parkedcalltransfers & recipient_mode) {
        ast_set_flag(&feature_flags, AST_FEATURE_REDIRECT);
    }
 
    if (lot->cfg->parkedcallreparking & recipient_mode) {
        ast_set_flag(&feature_flags, AST_FEATURE_PARKCALL);
    }
 
    if (lot->cfg->parkedcallhangup & recipient_mode) {
        ast_set_flag(&feature_flags, AST_FEATURE_DISCONNECT);
    }
 
    if (lot->cfg->parkedcallrecording & recipient_mode) {
        ast_set_flag(&feature_flags, AST_FEATURE_AUTOMIXMON);
    }
 
    ast_bridge_features_ds_set(chan, &feature_flags);
    ast_channel_unlock(chan);
 
    return;
}

References ast_bridge_features_ds_get(), ast_bridge_features_ds_set(), ast_channel_lock, ast_channel_unlock, AST_FEATURE_AUTOMIXMON, AST_FEATURE_DISCONNECT, AST_FEATURE_PARKCALL, AST_FEATURE_REDIRECT, ast_set_flag, parking_lot::cfg, parking_lot_cfg::parkedcallhangup, parking_lot_cfg::parkedcallrecording, parking_lot_cfg::parkedcallreparking, and parking_lot_cfg::parkedcalltransfers.

Referenced by bridge_parking_pull(), and parked_call_app_exec().

parking_channel_set_roles()

int parking_channel_set_roles	(	struct ast_channel *	chan,
		struct parking_lot *	lot,
		int	force_ringing
	)

Set necessary bridge roles on a channel that is about to enter a parking lot.

Since

12.0.0

Parameters

chan	Entering channel
lot	The parking lot the channel will be entering
force_ringing	Use ringing instead of music on hold

Return values

0	on success
non-zero	on failure

Definition at line 57 of file parking_controller.c.

{
    if (ast_channel_add_bridge_role(chan, "holding_participant")) {
        return -1;
    }
 
    if (force_ringing) {
        if (ast_channel_set_bridge_role_option(chan, "holding_participant", "idle_mode", "ringing")) {
            return -1;
        }
    } else {
        if (ast_channel_set_bridge_role_option(chan, "holding_participant", "idle_mode", "musiconhold")) {
            return -1;
        }
        if (!ast_strlen_zero(lot->cfg->mohclass)) {
            if (ast_channel_set_bridge_role_option(chan, "holding_participant", "moh_class", lot->cfg->mohclass)) {
                return -1;
            }
        }
    }
 
    return 0;
}

References ast_channel_add_bridge_role(), ast_channel_set_bridge_role_option(), ast_strlen_zero(), parking_lot::cfg, and parking_lot_cfg::mohclass.

Referenced by bridge_parking_push(), and park_common_setup2().

parking_lot_get_bridge()

struct ast_bridge * parking_lot_get_bridge

(

struct parking_lot *

lot

)

Get a reference to a parking lot's bridge. If it doesn't exist, create it and get a reference.

Since

12.0.0

Parameters

lot	Which parking lot we need the bridge from. This parking lot must be locked before calling this function.

Returns

A reference to the ast_bridge associated with the parking lot

Return values

NULL	if it didn't already have a bridge and one couldn't be created

Note

This bridge will need to be unreffed if it ever falls out of scope.

Definition at line 36 of file parking_controller.c.

{
    struct ast_bridge *lot_bridge;
 
    if (lot->parking_bridge) {
        ao2_ref(lot->parking_bridge, +1);
        return lot->parking_bridge;
    }
 
    lot_bridge = bridge_parking_new(lot);
    if (!lot_bridge) {
        return NULL;
    }
 
    /* The parking lot needs a reference to the bridge as well. */
    lot->parking_bridge = lot_bridge;
    ao2_ref(lot->parking_bridge, +1);
 
    return lot_bridge;
}

References ao2_ref, bridge_parking_new(), NULL, and parking_lot::parking_bridge.

Referenced by park_common_setup2().

parking_lot_get_space()

int parking_lot_get_space	(	struct parking_lot *	lot,
		int	target_override
	)

Get an available parking space within a parking lot.

Since

12.0.0

Parameters

lot	Which parking lot we are getting a space from
target_override	If there is a specific slot we want, provide it here and we'll start from that position

Return values

-1	if No slot can be found

Returns

integer value of parking space selected

Note

lot should be locked before this is called and unlocked only after a parked_user with the space returned has been added to the parking lot.

Definition at line 96 of file parking_controller.c.

{
    int original_target;
    int current_target;
    struct ao2_iterator i;
    struct parked_user *user;
    int wrap;
 
    if (lot->cfg->parkfindnext) {
        /* Use next_space if the lot already has next_space set; otherwise use lot start. */
        original_target = lot->next_space ? lot->next_space : lot->cfg->parking_start;
    } else {
        original_target = lot->cfg->parking_start;
    }
 
    if (target_override >= lot->cfg->parking_start && target_override <= lot->cfg->parking_stop) {
        original_target = target_override;
    } else if (target_override > -1) {
        ast_log(LOG_WARNING, "Preferred parking spot %d is out of bounds (%d-%d)\n", target_override, lot->cfg->parking_start, lot->cfg->parking_stop);
    }
 
    current_target = original_target;
 
    wrap = lot->cfg->parking_start;
 
    i = ao2_iterator_init(lot->parked_users, 0);
    while ((user = ao2_iterator_next(&i))) {
        /* Increment the wrap on each pass until we find an empty space */
        if (wrap == user->parking_space) {
            wrap += 1;
        }
 
        if (user->parking_space < current_target) {
            /* It's lower than the anticipated target, so we haven't reached the target yet. */
            ao2_ref(user, -1);
            continue;
        }
 
        if (user->parking_space > current_target) {
            /* The current target is usable because all items below have been read and the next target is higher than the one we want. */
            ao2_ref(user, -1);
            break;
        }
 
        /* We found one already parked here. */
        current_target += 1;
        ao2_ref(user, -1);
    }
    ao2_iterator_destroy(&i);
 
    if (current_target <= lot->cfg->parking_stop) {
        return current_target;
    }
 
    if (wrap <= lot->cfg->parking_stop) {
        return wrap;
    }
 
    return -1;
}

References ao2_iterator_destroy(), ao2_iterator_init(), ao2_iterator_next, ao2_ref, ast_log, parking_lot::cfg, LOG_WARNING, parked_user::lot, parking_lot::next_space, parking_lot::parked_users, parking_lot_cfg::parkfindnext, parking_lot_cfg::parking_start, parking_lot_cfg::parking_stop, and parked_user::start.

Referenced by generate_parked_user().

parking_lot_inspect_parked_user()

struct parked_user * parking_lot_inspect_parked_user	(	struct parking_lot *	lot,
		int	target
	)

Determine if there is a parked user in a parking space and return it if there is.

Parameters

lot	Parking lot being pulled from
target	If < 0 search for the first occupied space in the parking lot If >= 0 Only pull from the indicated target

Return values

NULL	if no parked user could be pulled from the requested parking lot at the requested parking space

Returns

reference to the requested parked user

Definition at line 168 of file parking_controller.c.

{
    struct parked_user *user;
 
    if (target < 0) {
        user = ao2_callback(lot->parked_users, 0, NULL, NULL);
    } else {
        user = ao2_callback(lot->parked_users, 0, retrieve_parked_user_targeted, &target);
    }
 
    if (!user) {
        return NULL;
    }
 
    return user;
}

References ao2_callback, parked_user::lot, NULL, parking_lot::parked_users, and retrieve_parked_user_targeted().

Referenced by func_get_parkingslot_channel().

parking_lot_retrieve_parked_user()

struct parked_user * parking_lot_retrieve_parked_user	(	struct parking_lot *	lot,
		int	target
	)

Determine if there is a parked user in a parking space and pull it from the parking lot if there is.

Since

12.0.0

Parameters

lot	Parking lot being pulled from
target	If < 0 search for the first occupied space in the parking lot If >= 0 Only pull from the indicated target

Return values

NULL	if no parked user could be pulled from the requested parking lot at the requested parking space

Returns

reference to the requested parked user

Note

The parked user will be removed from parking lot as part of this process

Remove this reference with ao2_cleanup once it falls out of scope.

Definition at line 185 of file parking_controller.c.

{
    RAII_VAR(struct parked_user *, user, NULL, ao2_cleanup);
 
    if (target < 0) {
        user = ao2_callback(lot->parked_users, 0, NULL, NULL);
    } else {
        user = ao2_callback(lot->parked_users, 0, retrieve_parked_user_targeted, &target);
    }
 
    if (!user) {
        return NULL;
    }
 
    ao2_lock(user);
    if (user->resolution != PARK_UNSET) {
        /* Abandon. Something else has resolved the parked user before we got to it. */
        ao2_unlock(user);
        return NULL;
    }
 
    ao2_unlink(lot->parked_users, user);
    user->resolution = PARK_ANSWERED;
    ao2_unlock(user);
 
    parking_lot_remove_if_unused(user->lot);
 
    /* Bump the ref count by 1 since the RAII_VAR will eat the reference otherwise */
    ao2_ref(user, +1);
    return user;
}

References ao2_callback, ao2_cleanup, ao2_lock, ao2_ref, ao2_unlink, ao2_unlock, parked_user::lot, NULL, PARK_ANSWERED, PARK_UNSET, parking_lot::parked_users, parking_lot_remove_if_unused(), RAII_VAR, and retrieve_parked_user_targeted().

Referenced by parked_call_app_exec().

retrieve_parked_user_targeted()

static int retrieve_parked_user_targeted ( void *  obj, void *  arg, int  flags  )

static

Definition at line 157 of file parking_controller.c.

{
    int *target = arg;
    struct parked_user *user = obj;
    if (user->parking_space == *target) {
        return CMP_MATCH;
    }
 
    return 0;
}

References CMP_MATCH.

Referenced by parking_lot_inspect_parked_user(), and parking_lot_retrieve_parked_user().

unpark_parked_user()

int unpark_parked_user

(

struct parked_user *

user

)

Pull a parked user out of its parking lot. Use this when you don't want to use the parked user afterwards.

Since

12.0.0

Parameters

user	The parked user being pulled.

Return values

0	on success
-1	if the user didn't have its parking lot set

Definition at line 85 of file parking_controller.c.

{
    if (pu->lot) {
        ao2_unlink(pu->lot->parked_users, pu);
        parking_lot_remove_if_unused(pu->lot);
        return 0;
    }
 
    return -1;
}

References ao2_unlink, parking_lot_remove_if_unused(), and parked_user::start.

Referenced by bridge_parking_pull().