ccss.h File Reference

Call Completion Supplementary Services API. More...

#include "asterisk.h"
#include "asterisk/linkedlists.h"
#include "asterisk/devicestate.h"

Include dependency graph for ccss.h:

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

Go to the source code of this file.

Data Structures
struct	ast_cc_agent
struct	ast_cc_agent_callbacks
struct	ast_cc_interface
	Structure with information about an outbound interface. More...
struct	ast_cc_monitor
struct	ast_cc_monitor_callbacks
	Callbacks defined by CC monitors. More...

Macros
#define	ast_cc_config_params_init()   __ast_cc_config_params_init(__FILE__, __LINE__, __PRETTY_FUNCTION__)
	Allocate and initialize an ast_cc_config_params structure.
#define	AST_CC_GENERIC_MONITOR_TYPE   "generic"

Typedefs
typedef void(*	ast_cc_callback_fn) (struct ast_channel *chan, struct ast_cc_config_params *cc_params, const char *monitor_type, const char *const device_name, const char *const dialstring, void *private_data)
	Callback made from ast_cc_callback for certain channel types.

Enumerations
enum	ast_cc_agent_flags { AST_CC_AGENT_SKIP_OFFER = (1 << 0) }
	agent flags that can alter core behavior More...
enum	ast_cc_agent_policies { AST_CC_AGENT_NEVER , AST_CC_AGENT_NATIVE , AST_CC_AGENT_GENERIC }
	The various possibilities for cc_agent_policy values. More...
enum	ast_cc_agent_response_reason { AST_CC_AGENT_RESPONSE_SUCCESS , AST_CC_AGENT_RESPONSE_FAILURE_INVALID , AST_CC_AGENT_RESPONSE_FAILURE_TOO_MANY }
enum	ast_cc_monitor_class { AST_CC_DEVICE_MONITOR , AST_CC_EXTENSION_MONITOR }
enum	ast_cc_monitor_policies { AST_CC_MONITOR_NEVER , AST_CC_MONITOR_NATIVE , AST_CC_MONITOR_GENERIC , AST_CC_MONITOR_ALWAYS }
	The various possibilities for cc_monitor_policy values. More...
enum	ast_cc_service_type { AST_CC_NONE , AST_CC_CCBS , AST_CC_CCNR , AST_CC_CCNL }

Functions
struct ast_cc_config_params *	__ast_cc_config_params_init (const char *file, int line, const char *function)
	Allocate and initialize an ast_cc_config_params structure.
int	ast_cc_agent_accept_request (int core_id, const char *const debug,...)
	Accept inbound CC request.
struct ast_cc_agent *	ast_cc_agent_callback (int flags, ao2_callback_fn *function, void *arg, const char *const type)
	Call a callback on all agents of a specific type.
int	ast_cc_agent_caller_available (int core_id, const char *const debug,...)
	Indicate that a previously unavailable caller has become available.
int	ast_cc_agent_caller_busy (int core_id, const char *const debug,...)
	Indicate that the caller is busy.
int	ast_cc_agent_recalling (int core_id, const char *const debug,...)
	Tell the CC core that a caller is currently recalling.
int	ast_cc_agent_register (const struct ast_cc_agent_callbacks *callbacks)
	Register a set of agent callbacks with the core.
int	ast_cc_agent_set_interfaces_chanvar (struct ast_channel *chan)
	Set the first level CC_INTERFACES channel variable for a channel.
int	ast_cc_agent_status_response (int core_id, enum ast_device_state devstate)
	Response with a caller's current status.
void	ast_cc_agent_unregister (const struct ast_cc_agent_callbacks *callbacks)
	Unregister a set of agent callbacks with the core.
int	ast_cc_available_timer_expire (const void *data)
	Scheduler callback for available timer expiration.
int	ast_cc_build_frame (struct ast_channel *chan, struct ast_cc_config_params *cc_params, const char *monitor_type, const char *const device_name, const char *const dialstring, enum ast_cc_service_type service, void *private_data, struct ast_frame *frame)
	Create a CC Control frame.
void	ast_cc_busy_interface (struct ast_channel *inbound, struct ast_cc_config_params *cc_params, const char *monitor_type, const char *const device_name, const char *const dialstring, void *private_data)
	Callback made from ast_cc_callback for certain channel types.
void	ast_cc_call_failed (struct ast_channel *incoming, struct ast_channel *outgoing, const char *const dialstring)
	Make CCBS available in the case that ast_call fails.
int	ast_cc_call_init (struct ast_channel *chan, int *ignore_cc)
	Start the CC process on a call.
int	ast_cc_callback (struct ast_channel *inbound, const char *const tech, const char *const dest, ast_cc_callback_fn callback)
	Run a callback for potential matching destinations.
int	ast_cc_completed (struct ast_channel *chan, const char *const debug,...)
	Indicate recall has been acknowledged.
void	ast_cc_config_params_destroy (struct ast_cc_config_params *params)
	Free memory from CCSS configuration params.
void	ast_cc_copy_config_params (struct ast_cc_config_params *dest, const struct ast_cc_config_params *src)
	copy CCSS configuration parameters from one structure to another
void	ast_cc_default_config_params (struct ast_cc_config_params *params)
	Set the specified CC config params to default values.
void	ast_cc_extension_monitor_add_dialstring (struct ast_channel *incoming, const char *const dialstring, const char *const device_name)
	Add a child dialstring to an extension monitor.
int	ast_cc_failed (int core_id, const char *const debug,...)
	Indicate failure has occurred.
int	ast_cc_get_current_core_id (struct ast_channel *chan)
	Get the core id for the current call.
struct ast_cc_monitor *	ast_cc_get_monitor_by_recall_core_id (const int core_id, const char *const device_name)
	Get the associated monitor given the device name and core_id.
int	ast_cc_get_param (struct ast_cc_config_params *params, const char *const name, char *buf, size_t buf_len)
	get a CCSS configuration parameter, given its name
int	ast_cc_is_config_param (const char *const name)
	Is this a CCSS configuration parameter?
int	ast_cc_is_enabled (void)
	Determine if CCSS is enabled.
int	ast_cc_is_recall (struct ast_channel *chan, int *core_id, const char *const monitor_type)
	Decide if a call to a particular channel is a CC recall.
int	ast_cc_monitor_callee_available (const int core_id, const char *const debug,...)
	Alert the core that a device being monitored has become available.
int	ast_cc_monitor_count (const char *const name, const char *const type)
	Return the number of outstanding CC requests to a specific device.
int	ast_cc_monitor_failed (int core_id, const char *const monitor_name, const char *const debug,...)
	Indicate that a failure has occurred on a specific monitor.
int	ast_cc_monitor_party_b_free (int core_id)
	Alert a caller that though the callee has become free, the caller himself is not and may not call back.
int	ast_cc_monitor_register (const struct ast_cc_monitor_callbacks *callbacks)
	Register a set of monitor callbacks with the core.
int	ast_cc_monitor_request_acked (int core_id, const char *const debug,...)
	Indicate that an outbound entity has accepted our CC request.
int	ast_cc_monitor_status_request (int core_id)
	Request the status of a caller or callers.
int	ast_cc_monitor_stop_ringing (int core_id)
	Alert a caller to stop ringing.
void	ast_cc_monitor_unregister (const struct ast_cc_monitor_callbacks *callbacks)
	Unregister a set of monitor callbacks with the core.
int	ast_cc_offer (struct ast_channel *caller_chan)
	Offer CC to a caller.
int	ast_cc_request_is_within_limits (void)
	Check if the incoming CC request is within the bounds set by the cc_max_requests configuration option.
int	ast_cc_set_param (struct ast_cc_config_params *params, const char *const name, const char *value)
	set a CCSS configuration parameter, given its name
const char *	ast_get_cc_agent_dialstring (struct ast_cc_config_params *config)
	Get the cc_agent_dialstring.
enum ast_cc_agent_policies	ast_get_cc_agent_policy (struct ast_cc_config_params *config)
	Get the cc_agent_policy.
const char *	ast_get_cc_callback_sub (struct ast_cc_config_params *config)
	Get the name of the callback subroutine.
unsigned int	ast_get_cc_max_agents (struct ast_cc_config_params *config)
	Get the cc_max_agents.
unsigned int	ast_get_cc_max_monitors (struct ast_cc_config_params *config)
	Get the cc_max_monitors.
enum ast_cc_monitor_policies	ast_get_cc_monitor_policy (struct ast_cc_config_params *config)
	Get the cc_monitor_policy.
unsigned int	ast_get_cc_offer_timer (struct ast_cc_config_params *config)
	Get the cc_offer_timer.
unsigned int	ast_get_cc_recall_timer (struct ast_cc_config_params *config)
	Get the cc_recall_timer.
unsigned int	ast_get_ccbs_available_timer (struct ast_cc_config_params *config)
	Get the ccbs_available_timer.
unsigned int	ast_get_ccnr_available_timer (struct ast_cc_config_params *config)
	Get the ccnr_available_timer.
void	ast_handle_cc_control_frame (struct ast_channel *inbound, struct ast_channel *outbound, void *frame_data)
	Properly react to a CC control frame.
void	ast_ignore_cc (struct ast_channel *chan)
	Mark the channel to ignore further CC activity.
int	ast_queue_cc_frame (struct ast_channel *chan, const char *const monitor_type, const char *const dialstring, enum ast_cc_service_type service, void *private_data)
	Queue an AST_CONTROL_CC frame.
void	ast_set_cc_agent_dialstring (struct ast_cc_config_params *config, const char *const value)
	Set the cc_agent_dialstring.
int	ast_set_cc_agent_policy (struct ast_cc_config_params *config, enum ast_cc_agent_policies value)
	Set the cc_agent_policy.
void	ast_set_cc_callback_sub (struct ast_cc_config_params *config, const char *const value)
	Set the callback subroutine name.
int	ast_set_cc_interfaces_chanvar (struct ast_channel *chan, const char *const extension)
	Set the CC_INTERFACES channel variable for a channel using an.
void	ast_set_cc_max_agents (struct ast_cc_config_params *config, unsigned int value)
	Set the cc_max_agents.
void	ast_set_cc_max_monitors (struct ast_cc_config_params *config, unsigned int value)
	Set the cc_max_monitors.
int	ast_set_cc_monitor_policy (struct ast_cc_config_params *config, enum ast_cc_monitor_policies value)
	Set the cc_monitor_policy.
void	ast_set_cc_offer_timer (struct ast_cc_config_params *config, unsigned int value)
	Set the cc_offer_timer.
void	ast_set_cc_recall_timer (struct ast_cc_config_params *config, unsigned int value)
	Set the cc_recall_timer.
void	ast_set_ccbs_available_timer (struct ast_cc_config_params *config, unsigned int value)
	Set the ccbs_available_timer.
void	ast_set_ccnr_available_timer (struct ast_cc_config_params *config, unsigned int value)
	Set the ccnr_available_timer.
int	ast_setup_cc_recall_datastore (struct ast_channel *chan, const int core_id)
	Set up a CC recall datastore on a channel.

Detailed Description

Call Completion Supplementary Services API.

Author

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

Definition in file ccss.h.

Macro Definition Documentation

ast_cc_config_params_init

#define ast_cc_config_params_init

(

)

__ast_cc_config_params_init(__FILE__, __LINE__, __PRETTY_FUNCTION__)

Allocate and initialize an ast_cc_config_params structure.

Note

Reasonable default values are chosen for the parameters upon allocation.

Return values

NULL	Unable to allocate the structure
non-NULL	A pointer to the newly allocated and initialized structure

Definition at line 135 of file ccss.h.

AST_CC_GENERIC_MONITOR_TYPE

#define AST_CC_GENERIC_MONITOR_TYPE   "generic"

It is recommended that monitors use a pointer to an ast_cc_monitor_callbacks::type when creating an AST_CONTROL_CC frame. Since the generic monitor callbacks are opaque and channel drivers will wish to use that, this string is made globally available for all to use

Definition at line 455 of file ccss.h.

Typedef Documentation

ast_cc_callback_fn

typedef void(* ast_cc_callback_fn) (struct ast_channel *chan, struct ast_cc_config_params *cc_params, const char *monitor_type, const char *const device_name, const char *const dialstring, void *private_data)

Callback made from ast_cc_callback for certain channel types.

Since

1.8

Parameters

chan	A channel involved in the call. What we want is on a datastore on both incoming and outgoing so either may be provided
cc_params	The CC configuration parameters for the outbound target
monitor_type	The type of monitor to use when CC is requested
device_name	The name of the outbound target device.
dialstring	The dial string used when calling this specific interface
private_data	If a native monitor is being used, and some channel-driver-specific private data has been allocated, then this parameter should contain a pointer to that data. If using a generic monitor, this parameter should remain NULL. Note that if this function should fail at some point, it is the responsibility of the caller to free the private data upon return.

For channel types that fail ast_request when the device is busy, we call into the channel driver with ast_cc_callback. This is the callback that is called in that case for each device found which could have been returned by ast_request.

Definition at line 1562 of file ccss.h.

Enumeration Type Documentation

ast_cc_agent_flags

enum ast_cc_agent_flags

agent flags that can alter core behavior

Enumerator
AST_CC_AGENT_SKIP_OFFER

Definition at line 59 of file ccss.h.

                        {
    /* Some agent types allow for a caller to
     * request CC without reaching the CC_CALLER_OFFERED
     * state. In other words, the caller can request
     * CC while he is still on the phone from the failed
     * call. The generic agent is an agent which allows
     * for this behavior.
     */
    AST_CC_AGENT_SKIP_OFFER = (1 << 0),
};

ast_cc_agent_policies

enum ast_cc_agent_policies

The various possibilities for cc_agent_policy values.

Since

1.8

Enumerator
AST_CC_AGENT_NEVER	Never offer CCSS to the caller
AST_CC_AGENT_NATIVE	Offer CCSS using native signaling
AST_CC_AGENT_GENERIC	Use generic agent for caller

Definition at line 47 of file ccss.h.

                           {
    /*! Never offer CCSS to the caller */
    AST_CC_AGENT_NEVER,
    /*! Offer CCSS using native signaling */
    AST_CC_AGENT_NATIVE,
    /*! Use generic agent for caller */
    AST_CC_AGENT_GENERIC,
};

ast_cc_agent_response_reason

enum ast_cc_agent_response_reason

Enumerator
AST_CC_AGENT_RESPONSE_SUCCESS	CC request accepted
AST_CC_AGENT_RESPONSE_FAILURE_INVALID	CC request not allowed at this time. Invalid state transition.
AST_CC_AGENT_RESPONSE_FAILURE_TOO_MANY	Too many CC requests in the system.

Definition at line 841 of file ccss.h.

                                  {
    /*! CC request accepted */
    AST_CC_AGENT_RESPONSE_SUCCESS,
    /*! CC request not allowed at this time. Invalid state transition. */
    AST_CC_AGENT_RESPONSE_FAILURE_INVALID,
    /*! Too many CC requests in the system. */
    AST_CC_AGENT_RESPONSE_FAILURE_TOO_MANY,
};

ast_cc_monitor_class

enum ast_cc_monitor_class

Used to determine which type of monitor an ast_cc_device_monitor is.

Enumerator
AST_CC_DEVICE_MONITOR
AST_CC_EXTENSION_MONITOR

Definition at line 462 of file ccss.h.

                          {
    AST_CC_DEVICE_MONITOR,
    AST_CC_EXTENSION_MONITOR,
};

ast_cc_monitor_policies

enum ast_cc_monitor_policies

The various possibilities for cc_monitor_policy values.

Since

1.8

Enumerator
AST_CC_MONITOR_NEVER	Never accept CCSS offers from callee
AST_CC_MONITOR_NATIVE
AST_CC_MONITOR_GENERIC	Always use CCSS generic monitor for callee Note that if callee offers CCSS natively, we still will use a generic CCSS monitor if this is set
AST_CC_MONITOR_ALWAYS	Accept native CCSS offers, but if no offer is present, use a generic CCSS monitor

Definition at line 74 of file ccss.h.

                             {
    /*! Never accept CCSS offers from callee */
    AST_CC_MONITOR_NEVER,
    /* CCSS only available if callee offers it through signaling */
    AST_CC_MONITOR_NATIVE,
    /*! Always use CCSS generic monitor for callee
     * Note that if callee offers CCSS natively, we still
     * will use a generic CCSS monitor if this is set
     */
    AST_CC_MONITOR_GENERIC,
    /*! Accept native CCSS offers, but if no offer is present,
     * use a generic CCSS monitor
     */
    AST_CC_MONITOR_ALWAYS,
};

ast_cc_service_type

enum ast_cc_service_type

Enumerator
AST_CC_NONE
AST_CC_CCBS
AST_CC_CCNR
AST_CC_CCNL

Definition at line 32 of file ccss.h.

                         {
    /* No Service available/requested */
    AST_CC_NONE,
    /* Call Completion Busy Subscriber */
    AST_CC_CCBS,
    /* Call Completion No Response */
    AST_CC_CCNR,
    /* Call Completion Not Logged In (currently SIP only) */
    AST_CC_CCNL,
};

Function Documentation

__ast_cc_config_params_init()

struct ast_cc_config_params * __ast_cc_config_params_init	(	const char *	file,
		int	line,
		const char *	function
	)

Allocate and initialize an ast_cc_config_params structure.

Note

Reasonable default values are chosen for the parameters upon allocation.

Return values

NULL	Unable to allocate the structure
non-NULL	A pointer to the newly allocated and initialized structure

Definition at line 699 of file ccss.c.

{
    struct ast_cc_config_params *params;
 
    RETURN_IF_NOT_ENABLED(NULL);
 
    params = __ast_malloc(sizeof(*params), file, line, function);
    if (!params) {
        return NULL;
    }
 
    ast_cc_default_config_params(params);
    return params;
}

References __ast_malloc(), ast_cc_default_config_params(), NULL, and RETURN_IF_NOT_ENABLED.

ast_cc_agent_accept_request()

int ast_cc_agent_accept_request	(	int	core_id,
		const char *const	debug,
			...
	)

Accept inbound CC request.

Since

1.8

When a caller requests CC, this function should be called to let the core know that the request has been accepted.

Parameters

core_id	core_id of the CC transaction
debug	optional string to print for debugging purposes

Return values

0	Success
-1	Failure

Definition at line 3807 of file ccss.c.

{
    va_list ap;
    int res;
 
    RETURN_IF_NOT_ENABLED(0);
 
    va_start(ap, debug);
    res = cc_request_state_change(CC_CALLER_REQUESTED, core_id, debug, ap);
    va_end(ap);
    return res;
}

References CC_CALLER_REQUESTED, cc_request_state_change(), dialed_cc_interfaces::core_id, debug, and RETURN_IF_NOT_ENABLED.

Referenced by ccreq_exec().

ast_cc_agent_callback()

struct ast_cc_agent * ast_cc_agent_callback	(	int	flags,
		ao2_callback_fn *	function,
		void *	arg,
		const char *const	type
	)

Call a callback on all agents of a specific type.

Since the container of CC core instances is private, and so are the items which the container contains, we have to provide an ao2_callback-like method so that a specific agent may be found or so that an operation can be made on all agents of a particular type. The first three arguments should be familiar to anyone who has used ao2_callback. The final argument is the type of agent you wish to have the callback called on.

Note

Since agents are refcounted, and this function returns a reference to the agent, it is imperative that you decrement the refcount of the agent once you have finished using it.

Parameters

flags	astobj2 search flags
function	an ao2 callback function to call
arg	the argument to the callback function
type	The type of agents to call the callback on

Definition at line 472 of file ccss.c.

{
    struct cc_callback_helper helper = {.function = function, .args = args, .type = type};
    struct cc_core_instance *core_instance;
 
    RETURN_IF_NOT_ENABLED(NULL);
 
    if ((core_instance = ao2_t_callback(cc_core_instances, flags, cc_agent_callback_helper, &helper,
                    "Calling provided agent callback function"))) {
        struct ast_cc_agent *agent = cc_ref(core_instance->agent, "An outside entity needs the agent");
        cc_unref(core_instance, "agent callback done with the core_instance");
        return agent;
    }
    return NULL;
}

References cc_core_instance::agent, ao2_t_callback, args, cc_agent_callback_helper(), cc_core_instances, cc_ref(), cc_unref(), cc_callback_helper::function, NULL, RETURN_IF_NOT_ENABLED, and type.

ast_cc_agent_caller_available()

int ast_cc_agent_caller_available	(	int	core_id,
		const char *const	debug,
			...
	)

Indicate that a previously unavailable caller has become available.

Since

1.8

If a monitor is suspended due to a caller becoming unavailable, then this function should be called to indicate that the caller has become available.

Parameters

core_id	core_id of the CC transaction
debug	optional string to print for debugging purposes

Return values

0	Success
-1	Failure

Definition at line 3859 of file ccss.c.

{
    va_list ap;
    int res;
 
    RETURN_IF_NOT_ENABLED(0);
 
    va_start(ap, debug);
    res = cc_request_state_change(CC_ACTIVE, core_id, debug, ap);
    va_end(ap);
    return res;
}

References CC_ACTIVE, cc_request_state_change(), dialed_cc_interfaces::core_id, debug, and RETURN_IF_NOT_ENABLED.

Referenced by generic_agent_devstate_cb().

ast_cc_agent_caller_busy()

int ast_cc_agent_caller_busy	(	int	core_id,
		const char *const	debug,
			...
	)

Indicate that the caller is busy.

Since

1.8

When the callee makes it known that he is available, the core will let the caller's channel driver know that it may attempt to let the caller know to attempt a recall. If the channel driver can detect, though, that the caller is busy, then the channel driver should call this function to let the CC core know.

Parameters

core_id	core_id of the CC transaction
debug	optional string to print for debugging purposes

Return values

0	Success
-1	Failure

Definition at line 3846 of file ccss.c.

{
    va_list ap;
    int res;
 
    RETURN_IF_NOT_ENABLED(0);
 
    va_start(ap, debug);
    res = cc_request_state_change(CC_CALLER_BUSY, core_id, debug, ap);
    va_end(ap);
    return res;
}

References CC_CALLER_BUSY, cc_request_state_change(), dialed_cc_interfaces::core_id, debug, and RETURN_IF_NOT_ENABLED.

Referenced by cc_generic_agent_recall().

ast_cc_agent_recalling()

int ast_cc_agent_recalling	(	int	core_id,
		const char *const	debug,
			...
	)

Tell the CC core that a caller is currently recalling.

Since

1.8

The main purpose of this is so that the core can alert the monitor to stop its available timer since the caller has begun its recall phase.

Parameters

core_id	core_id of the CC transaction
debug	optional string to print for debugging purposes

Return values

0	Success
-1	Failure

Definition at line 3872 of file ccss.c.

{
    va_list ap;
    int res;
 
    RETURN_IF_NOT_ENABLED(0);
 
    va_start(ap, debug);
    res = cc_request_state_change(CC_RECALLING, core_id, debug, ap);
    va_end(ap);
    return res;
}

References CC_RECALLING, cc_request_state_change(), dialed_cc_interfaces::core_id, debug, and RETURN_IF_NOT_ENABLED.

Referenced by generic_recall().

ast_cc_agent_register()

int ast_cc_agent_register

(

const struct ast_cc_agent_callbacks *

callbacks

)

Register a set of agent callbacks with the core.

Since

1.8

This is made so that at agent creation time, the proper callbacks may be installed and the proper .init callback may be called for the monitor to establish private data.

Parameters

callbacks

The callbacks used by the agent implementation

Return values

0	Successfully registered
-1	Failure to register

Definition at line 1247 of file ccss.c.

{
    struct cc_agent_backend *backend;
 
    RETURN_IF_NOT_ENABLED(0);
 
    backend = ast_calloc(1, sizeof(*backend));
    if (!backend) {
        return -1;
    }
 
    backend->callbacks = callbacks;
    AST_RWLIST_WRLOCK(&cc_agent_backends);
    AST_RWLIST_INSERT_TAIL(&cc_agent_backends, backend, next);
    AST_RWLIST_UNLOCK(&cc_agent_backends);
    return 0;
}

References ast_calloc, AST_RWLIST_INSERT_TAIL, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, cc_agent_backend::callbacks, callbacks, cc_agent_backend::next, and RETURN_IF_NOT_ENABLED.

Referenced by load_module(), and load_module().

ast_cc_agent_set_interfaces_chanvar()

int ast_cc_agent_set_interfaces_chanvar

(

struct ast_channel *

chan

)

Set the first level CC_INTERFACES channel variable for a channel.

Since

1.8

Note

Implementers of protocol-specific CC agents should call this function after calling ast_setup_cc_recall_datastore.

This function will lock the channel as well as the list of monitors stored on the channel's CC recall datastore, though neither are held at the same time. Callers of this function should be aware of potential lock ordering problems that may arise.

The CC_INTERFACES channel variable will have the interfaces that should be called back for a specific PBX instance.

Parameters

chan	The channel to set the CC_INTERFACES variable on

Definition at line 3654 of file ccss.c.

{
    struct ast_datastore *recall_datastore;
    struct cc_monitor_tree *interface_tree;
    struct ast_cc_monitor *monitor;
    struct cc_recall_ds_data *recall_data;
    struct ast_str *str = ast_str_create(64);
    int core_id;
 
    RETURN_IF_NOT_ENABLED(0);
 
    if (!str) {
        return -1;
    }
 
    ast_channel_lock(chan);
    if (!(recall_datastore = ast_channel_datastore_find(chan, &recall_ds_info, NULL))) {
        ast_channel_unlock(chan);
        ast_free(str);
        return -1;
    }
    recall_data = recall_datastore->data;
    interface_tree = recall_data->interface_tree;
    core_id = recall_data->core_id;
    ast_channel_unlock(chan);
 
    AST_LIST_LOCK(interface_tree);
    monitor = AST_LIST_FIRST(interface_tree);
    build_cc_interfaces_chanvar(monitor, &str);
    AST_LIST_UNLOCK(interface_tree);
 
    pbx_builtin_setvar_helper(chan, "CC_INTERFACES", ast_str_buffer(str));
    ast_log_dynamic_level(cc_logger_level, "Core %d: CC_INTERFACES set to %s\n",
            core_id, ast_str_buffer(str));
 
    ast_free(str);
    return 0;
}

References ast_channel_datastore_find(), ast_channel_lock, ast_channel_unlock, ast_free, AST_LIST_FIRST, AST_LIST_LOCK, AST_LIST_UNLOCK, ast_log_dynamic_level, ast_str_buffer(), ast_str_create, build_cc_interfaces_chanvar(), cc_logger_level, cc_recall_ds_data::core_id, ast_datastore::data, cc_recall_ds_data::interface_tree, NULL, pbx_builtin_setvar_helper(), recall_ds_info, RETURN_IF_NOT_ENABLED, and str.

Referenced by generic_recall().

ast_cc_agent_status_response()

int ast_cc_agent_status_response	(	int	core_id,
		enum ast_device_state	devstate
	)

Response with a caller's current status.

When an ISDN PTMP monitor requests the caller's status, the agent must respond to the request using this function. For simplicity it is recommended that the devstate parameter be one of AST_DEVICE_INUSE or AST_DEVICE_NOT_INUSE.

Parameters

core_id	The core ID of the CC transaction
devstate	The current state of the caller to which the agent pertains

Return values

0	Successfully responded with our status
-1	Failed to respond with our status

Definition at line 4148 of file ccss.c.

{
    struct cc_status_response_args *args;
    struct cc_core_instance *core_instance;
    int res;
 
    RETURN_IF_NOT_ENABLED(0);
 
    args = ast_calloc(1, sizeof(*args));
    if (!args) {
        return -1;
    }
 
    core_instance = find_cc_core_instance(core_id);
    if (!core_instance) {
        ast_free(args);
        return -1;
    }
 
    args->core_instance = core_instance;
    args->devstate = devstate;
 
    res = ast_taskprocessor_push(cc_core_taskprocessor, cc_status_response, args);
    if (res) {
        cc_unref(core_instance, "Unref core instance. ast_taskprocessor_push failed");
        ast_free(args);
    }
    return res;
}

References args, ast_calloc, ast_free, ast_taskprocessor_push(), cc_core_taskprocessor, cc_status_response(), cc_unref(), cc_core_instance::core_id, find_cc_core_instance(), and RETURN_IF_NOT_ENABLED.

Referenced by cc_generic_agent_status_request().

ast_cc_agent_unregister()

void ast_cc_agent_unregister

(

const struct ast_cc_agent_callbacks *

callbacks

)

Unregister a set of agent callbacks with the core.

Since

1.8

If a module which makes use of a CC agent is unloaded, then it may unregister its agent callbacks with the core.

Parameters

callbacks

The callbacks used by the agent implementation

Definition at line 1265 of file ccss.c.

{
    struct cc_agent_backend *backend;
 
    RETURN_IF_NOT_ENABLED();
 
    AST_RWLIST_WRLOCK(&cc_agent_backends);
    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&cc_agent_backends, backend, next) {
        if (backend->callbacks == callbacks) {
            AST_RWLIST_REMOVE_CURRENT(next);
            ast_free(backend);
            break;
        }
    }
    AST_RWLIST_TRAVERSE_SAFE_END;
    AST_RWLIST_UNLOCK(&cc_agent_backends);
}

References ast_free, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, cc_agent_backend::callbacks, callbacks, cc_agent_backend::next, and RETURN_IF_NOT_ENABLED.

Referenced by __unload_module(), and unload_module().

ast_cc_available_timer_expire()

int ast_cc_available_timer_expire

(

const void *

data

)

Scheduler callback for available timer expiration.

Since

1.8

Note

When arming the available timer from within a device monitor, you MUST use this function as the callback for the scheduler.

Parameters

data	A reference to the CC monitor on which the timer was running.

Definition at line 1523 of file ccss.c.

{
    struct ast_cc_monitor *monitor = (struct ast_cc_monitor *) data;
    int res;
 
    RETURN_IF_NOT_ENABLED(0);
 
    monitor->available_timer_id = -1;
    res = ast_cc_monitor_failed(monitor->core_id, monitor->interface->device_name, "Available timer expired for monitor");
    cc_unref(monitor, "Unref reference from scheduler\n");
    return res;
}

References ast_cc_monitor_failed(), ast_cc_monitor::available_timer_id, cc_unref(), ast_cc_monitor::core_id, ast_cc_interface::device_name, ast_cc_monitor::interface, and RETURN_IF_NOT_ENABLED.

Referenced by cc_generic_monitor_request_cc().

ast_cc_build_frame()

int ast_cc_build_frame	(	struct ast_channel *	chan,
		struct ast_cc_config_params *	cc_params,
		const char *	monitor_type,
		const char *const	device_name,
		const char *const	dialstring,
		enum ast_cc_service_type	service,
		void *	private_data,
		struct ast_frame *	frame
	)

Create a CC Control frame.

Since

1.8

chan_dahdi is weird. It doesn't seem to actually queue frames when it needs to tell an application something. Instead it wakes up, tells the application that it has data ready, and then based on set flags, creates the proper frame type. For chan_dahdi, we provide this function. It provides us the data we need, and we'll make its frame for it.

Parameters

	chan	A channel involved in the call. What we want is on a datastore on both incoming and outgoing so either may be provided
	cc_params	The CC configuration parameters for the outbound target
	monitor_type	The type of monitor to use when CC is requested
	device_name	The name of the outbound target device.
	dialstring	The dial string used when calling this specific interface
	service	What kind of CC service is being offered. (CCBS/CCNR/etc...)
	private_data	If a native monitor is being used, and some channel-driver-specific private data has been allocated, then this parameter should contain a pointer to that data. If using a generic monitor, this parameter should remain NULL. Note that if this function should fail at some point, it is the responsibility of the caller to free the private data upon return.
[out]	frame	The frame we will be returning to the caller. It is vital that ast_frame_free be called on this frame since the payload will be allocated on the heap.

Return values

-1	Failure. At some point there was a failure. Do not attempt to use the frame in this case.
0	Success

Definition at line 4235 of file ccss.c.

{
    struct cc_control_payload *payload;
 
    RETURN_IF_NOT_ENABLED(0);
 
    payload = ast_calloc(1, sizeof(*payload));
    if (!payload) {
        return -1;
    }
    if (cc_build_payload(chan, cc_params, monitor_type, device_name, dialstring, service, private_data, payload)) {
        /* Something screwed up, we can't make a frame with this */
        ast_free(payload);
        return -1;
    }
    frame->frametype = AST_FRAME_CONTROL;
    frame->subclass.integer = AST_CONTROL_CC;
    frame->data.ptr = payload;
    frame->datalen = sizeof(*payload);
    frame->mallocd = AST_MALLOCD_DATA;
    return 0;
}

References ast_calloc, AST_CONTROL_CC, AST_FRAME_CONTROL, ast_free, AST_MALLOCD_DATA, cc_build_payload(), ast_frame::data, ast_frame::datalen, cc_control_payload::device_name, cc_control_payload::dialstring, ast_frame::frametype, ast_frame_subclass::integer, ast_frame::mallocd, cc_control_payload::monitor_type, cc_control_payload::private_data, ast_frame::ptr, RETURN_IF_NOT_ENABLED, service, and ast_frame::subclass.

Referenced by ast_queue_cc_frame().

ast_cc_busy_interface()

void ast_cc_busy_interface	(	struct ast_channel *	inbound,
		struct ast_cc_config_params *	cc_params,
		const char *	monitor_type,
		const char *const	device_name,
		const char *const	dialstring,
		void *	private_data
	)

Callback made from ast_cc_callback for certain channel types.

Since

1.8

Parameters

inbound	Incoming asterisk channel.
cc_params	The CC configuration parameters for the outbound target
monitor_type	The type of monitor to use when CC is requested
device_name	The name of the outbound target device.
dialstring	The dial string used when calling this specific interface
private_data	If a native monitor is being used, and some channel-driver-specific private data has been allocated, then this parameter should contain a pointer to that data. If using a generic monitor, this parameter should remain NULL. Note that if this function should fail at some point, it is the responsibility of the caller to free the private data upon return.

For channel types that fail ast_request when the device is busy, we call into the channel driver with ast_cc_callback. This is the callback that is called in that case for each device found which could have been returned by ast_request.

This function creates a CC control frame payload, simulating the act of reading it from the nonexistent outgoing channel's frame queue. We then handle this simulated frame just as we would a normal CC frame which had actually been queued by the channel driver.

Definition at line 4296 of file ccss.c.

{
    struct cc_control_payload payload;
 
    RETURN_IF_NOT_ENABLED();
 
    if (cc_build_payload(inbound, cc_params, monitor_type, device_name, dialstring, AST_CC_CCBS, private_data, &payload)) {
        /* Something screwed up. Don't try to handle this payload */
        call_destructor_with_no_monitor(monitor_type, private_data);
        return;
    }
    ast_handle_cc_control_frame(inbound, NULL, &payload);
}

References AST_CC_CCBS, ast_handle_cc_control_frame(), call_destructor_with_no_monitor(), cc_build_payload(), cc_control_payload::device_name, cc_control_payload::dialstring, cc_control_payload::monitor_type, NULL, cc_control_payload::private_data, and RETURN_IF_NOT_ENABLED.

Referenced by dial_exec_full().

ast_cc_call_failed()

void ast_cc_call_failed	(	struct ast_channel *	incoming,
		struct ast_channel *	outgoing,
		const char *const	dialstring
	)

Make CCBS available in the case that ast_call fails.

Since

1.8

In some situations, notably if a call-limit is reached in SIP, ast_call will fail due to Asterisk's knowing that the desired device is currently busy. In such a situation, CCBS should be made available to the caller.

One caveat is that this may only be used if generic monitoring is being used. The reason is that since Asterisk determined that the device was busy without actually placing a call to it, the far end will have no idea what call we are requesting call completion for if we were to send a call completion request.

Definition at line 4261 of file ccss.c.

{
    char device_name[AST_CHANNEL_NAME];
    struct cc_control_payload payload;
    struct ast_cc_config_params *cc_params;
 
    RETURN_IF_NOT_ENABLED();
 
    if (ast_channel_hangupcause(outgoing) != AST_CAUSE_BUSY && ast_channel_hangupcause(outgoing) != AST_CAUSE_CONGESTION) {
        /* It doesn't make sense to try to offer CCBS to the caller if the reason for ast_call
         * failing is something other than busy or congestion
         */
        return;
    }
 
    cc_params = ast_channel_get_cc_config_params(outgoing);
    if (!cc_params) {
        return;
    }
    if (ast_get_cc_monitor_policy(cc_params) != AST_CC_MONITOR_GENERIC) {
        /* This sort of CCBS only works if using generic CC. For native, we would end up sending
         * a CC request for a non-existent call. The far end will reject this every time
         */
        return;
    }
 
    ast_channel_get_device_name(outgoing, device_name, sizeof(device_name));
    if (cc_build_payload(outgoing, cc_params, AST_CC_GENERIC_MONITOR_TYPE, device_name,
        dialstring, AST_CC_CCBS, NULL, &payload)) {
        /* Something screwed up, we can't make a frame with this */
        return;
    }
    ast_handle_cc_control_frame(incoming, outgoing, &payload);
}

References AST_CAUSE_BUSY, AST_CAUSE_CONGESTION, AST_CC_CCBS, AST_CC_GENERIC_MONITOR_TYPE, AST_CC_MONITOR_GENERIC, ast_channel_get_cc_config_params(), ast_channel_get_device_name(), ast_channel_hangupcause(), AST_CHANNEL_NAME, ast_get_cc_monitor_policy(), ast_handle_cc_control_frame(), cc_build_payload(), cc_control_payload::device_name, NULL, and RETURN_IF_NOT_ENABLED.

Referenced by dial_exec_full().

ast_cc_call_init()

int ast_cc_call_init	(	struct ast_channel *	chan,
		int *	ignore_cc
	)

Start the CC process on a call.

Since

1.8

Whenever a CC-capable application, such as Dial, wishes to engage in CC activity, it initiates the process by calling this function. If the CC core should discover that a previous application has called ast_ignore_cc on this channel or a "parent" channel, then the value of the ignore_cc integer passed in will be set nonzero.

The ignore_cc parameter is a convenience parameter. It can save an application the trouble of trying to call CC APIs when it knows that it should just ignore further attempts at CC actions.

Parameters

	chan	The inbound channel calling the CC-capable application.
[out]	ignore_cc	Will be set non-zero if no further CC actions need to be taken

Return values

0	Success
-1	Failure

Definition at line 2429 of file ccss.c.

{
    /* There are three situations to deal with here:
     *
     * 1. The channel does not have a dialed_cc_interfaces datastore on
     * it. This means that this is the first time that Dial has
     * been called. We need to create/initialize the datastore.
     *
     * 2. The channel does have a cc_interface datastore on it and
     * the "ignore" indicator is 0. This means that a Local channel
     * was called by a "parent" dial. We can check the datastore's
     * parent field to see who the root of this particular dial tree
     * is.
     *
     * 3. The channel does have a cc_interface datastore on it and
     * the "ignore" indicator is 1. This means that a second Dial call
     * is being made from an extension. In this case, we do not
     * want to make any additions/modifications to the datastore. We
     * will instead set a flag to indicate that CCSS is completely
     * disabled for this Dial attempt.
     */
 
    struct ast_datastore *cc_interfaces_datastore;
    struct dialed_cc_interfaces *interfaces;
    struct ast_cc_monitor *monitor;
    struct ast_cc_config_params *cc_params;
 
    if (!global_enabled) {
        ast_debug(3, "CCSS disabled globally\n");
        *ignore_cc = 1;
        return 0;
    }
 
    ast_channel_lock(chan);
 
    cc_params = ast_channel_get_cc_config_params(chan);
    if (!cc_params) {
        ast_channel_unlock(chan);
        return -1;
    }
    if (ast_get_cc_agent_policy(cc_params) == AST_CC_AGENT_NEVER) {
        /* We can't offer CC to this caller anyway, so don't bother with CC on this call
         */
        *ignore_cc = 1;
        ast_channel_unlock(chan);
        ast_log_dynamic_level(cc_logger_level, "Agent policy for %s is 'never'. CC not possible\n", ast_channel_name(chan));
        return 0;
    }
 
    if (!(cc_interfaces_datastore = ast_channel_datastore_find(chan, &dialed_cc_interfaces_info, NULL))) {
        /* Situation 1 has occurred */
        ast_channel_unlock(chan);
        return cc_interfaces_datastore_init(chan);
    }
    interfaces = cc_interfaces_datastore->data;
    ast_channel_unlock(chan);
 
    if (interfaces->ignore) {
        /* Situation 3 has occurred */
        *ignore_cc = 1;
        ast_log_dynamic_level(cc_logger_level, "Datastore is present with ignore flag set. Ignoring CC offers on this call\n");
        return 0;
    }
 
    /* Situation 2 has occurred */
    if (!(monitor = cc_extension_monitor_init(ast_channel_exten(chan),
                                            ast_channel_context(chan),
                                            interfaces->dial_parent_id))) {
        return -1;
    }
    monitor->core_id = interfaces->core_id;
    AST_LIST_LOCK(interfaces->interface_tree);
    cc_ref(monitor, "monitor tree's reference to the monitor");
    AST_LIST_INSERT_TAIL(interfaces->interface_tree, monitor, next);
    AST_LIST_UNLOCK(interfaces->interface_tree);
    interfaces->dial_parent_id = monitor->id;
    cc_unref(monitor, "Unref monitor's allocation reference");
    return 0;
}

References AST_CC_AGENT_NEVER, ast_channel_context(), ast_channel_datastore_find(), ast_channel_exten(), ast_channel_get_cc_config_params(), ast_channel_lock, ast_channel_name(), ast_channel_unlock, ast_debug, ast_get_cc_agent_policy(), AST_LIST_INSERT_TAIL, AST_LIST_LOCK, AST_LIST_UNLOCK, ast_log_dynamic_level, cc_extension_monitor_init(), cc_interfaces_datastore_init(), cc_logger_level, cc_ref(), cc_unref(), ast_cc_monitor::core_id, ast_datastore::data, dialed_cc_interfaces_info, global_enabled, ast_cc_monitor::id, interfaces, and NULL.

Referenced by dial_exec_full().

ast_cc_callback()

int ast_cc_callback	(	struct ast_channel *	inbound,
		const char *const	tech,
		const char *const	dest,
		ast_cc_callback_fn	callback
	)

Run a callback for potential matching destinations.

Since

1.8

Note

See the explanation in ast_channel_tech::cc_callback for more details.

Parameters

inbound
tech	Channel technology to use
dest	Channel/group/peer or whatever the specific technology uses
callback	Function to call when a target is reached

Return values

0	Always, I guess.

Definition at line 4311 of file ccss.c.

{
    const struct ast_channel_tech *chantech;
 
    RETURN_IF_NOT_ENABLED(0);
 
    chantech = ast_get_channel_tech(tech);
    if (chantech && chantech->cc_callback) {
        chantech->cc_callback(inbound, dest, callback);
    }
 
    return 0;
}

References ast_get_channel_tech(), callback(), ast_channel_tech::cc_callback, and RETURN_IF_NOT_ENABLED.

Referenced by dial_exec_full().

ast_cc_completed()

int ast_cc_completed	(	struct ast_channel *	chan,
		const char *const	debug,
			...
	)

Indicate recall has been acknowledged.

Since

1.8

When we receive confirmation that an endpoint has responded to our CC recall, we call this function.

Parameters

chan	The inbound channel making the CC recall
debug	optional string to print for debugging purposes

Return values

0	Success
-1	Failure

Definition at line 3885 of file ccss.c.

{
    struct ast_datastore *recall_datastore;
    struct cc_recall_ds_data *recall_data;
    int core_id;
    va_list ap;
    int res;
 
    RETURN_IF_NOT_ENABLED(0);
 
    ast_channel_lock(chan);
    if (!(recall_datastore = ast_channel_datastore_find(chan, &recall_ds_info, NULL))) {
        /* Silly! Why did you call this function if there's no recall DS? */
        ast_channel_unlock(chan);
        return -1;
    }
    recall_data = recall_datastore->data;
    if (recall_data->nested || recall_data->ignore) {
        /* If this is being called from a nested Dial, it is too
         * early to determine if the recall has actually completed.
         * The outermost dial is the only one with the authority to
         * declare the recall to be complete.
         *
         * Similarly, if this function has been called when the
         * recall has progressed beyond the first dial, this is not
         * a legitimate time to declare the recall to be done. In fact,
         * that should have been done already.
         */
        ast_channel_unlock(chan);
        return -1;
    }
    core_id = recall_data->core_id;
    ast_channel_unlock(chan);
    va_start(ap, debug);
    res = cc_request_state_change(CC_COMPLETE, core_id, debug, ap);
    va_end(ap);
    return res;
}

References ast_channel_datastore_find(), ast_channel_lock, ast_channel_unlock, CC_COMPLETE, cc_request_state_change(), cc_recall_ds_data::core_id, ast_datastore::data, debug, cc_recall_ds_data::ignore, cc_recall_ds_data::nested, NULL, recall_ds_info, and RETURN_IF_NOT_ENABLED.

Referenced by wait_for_answer().

ast_cc_config_params_destroy()

void ast_cc_config_params_destroy

(

struct ast_cc_config_params *

params

)

Free memory from CCSS configuration params.

Note

Just a call to ast_free for now...

Parameters

params

Pointer to structure whose memory we need to free

Definition at line 714 of file ccss.c.

{
    ast_free(params);
}

References ast_free.

Referenced by agent_destroy(), ast_channel_cc_params_init(), cc_interface_destroy(), channel_cc_params_destroy(), dahdi_create_channel_range(), destroy_dahdi_pvt(), process_dahdi(), and setup_dahdi().

ast_cc_copy_config_params()

void ast_cc_copy_config_params	(	struct ast_cc_config_params *	dest,
		const struct ast_cc_config_params *	src
	)

copy CCSS configuration parameters from one structure to another

Since

1.8

For now, this is a simple memcpy, but this function is necessary since the size of an ast_cc_config_params structure is unknown outside of main/ccss.c. Also, this allows for easier expansion of the function in case it becomes more complex than just a memcpy.

Parameters

src	The structure from which data is copied
dest	The structure to which data is copied

Definition at line 876 of file ccss.c.

{
    if (dest && src) {
        *dest = *src;
    }
}

Referenced by ast_channel_cc_params_init(), cc_agent_init(), cc_build_payload(), cc_device_monitor_init(), channel_cc_params_copy(), dahdi_new(), deep_copy_dahdi_chan_conf(), duplicate_pseudo(), and mkintf().

ast_cc_default_config_params()

void ast_cc_default_config_params

(

struct ast_cc_config_params *

params

)

Set the specified CC config params to default values.

Since

1.8

This is just like ast_cc_copy_config_params() and could be used in place of it if you need to set the config params to defaults instead. You are simply "copying" defaults into the destination.

Parameters

params

CC config params to set to default values.

Definition at line 694 of file ccss.c.

{
    *params = cc_default_params;
}

References cc_default_params.

Referenced by __ast_cc_config_params_init().

ast_cc_extension_monitor_add_dialstring()

void ast_cc_extension_monitor_add_dialstring	(	struct ast_channel *	incoming,
		const char *const	dialstring,
		const char *const	device_name
	)

Add a child dialstring to an extension monitor.

Since

1.8

Whenever we request a channel, the parent extension monitor needs to store the dialstring of the device requested. The reason is so that we can call the device back during the recall even if we are not monitoring the device.

Parameters

incoming	The caller's channel
dialstring	The dialstring used when requesting the outbound channel
device_name	The device name associated with the requested outbound channel

Definition at line 2022 of file ccss.c.

{
    struct ast_datastore *cc_datastore;
    struct dialed_cc_interfaces *cc_interfaces;
    struct ast_cc_monitor *monitor;
    struct extension_monitor_pvt *extension_pvt;
    struct extension_child_dialstring *child_dialstring;
    struct cc_monitor_tree *interface_tree;
    int id;
 
    RETURN_IF_NOT_ENABLED();
 
    ast_channel_lock(incoming);
    if (!(cc_datastore = ast_channel_datastore_find(incoming, &dialed_cc_interfaces_info, NULL))) {
        ast_channel_unlock(incoming);
        return;
    }
 
    cc_interfaces = cc_datastore->data;
    interface_tree = cc_interfaces->interface_tree;
    id = cc_interfaces->dial_parent_id;
    ast_channel_unlock(incoming);
 
    AST_LIST_LOCK(interface_tree);
    AST_LIST_TRAVERSE(interface_tree, monitor, next) {
        if (monitor->id == id) {
            break;
        }
    }
 
    if (!monitor) {
        AST_LIST_UNLOCK(interface_tree);
        return;
    }
 
    extension_pvt = monitor->private_data;
    if (!(child_dialstring = ast_calloc(1, sizeof(*child_dialstring)))) {
        AST_LIST_UNLOCK(interface_tree);
        return;
    }
    ast_copy_string(child_dialstring->original_dialstring, dialstring, sizeof(child_dialstring->original_dialstring));
    ast_copy_string(child_dialstring->device_name, device_name, sizeof(child_dialstring->device_name));
    child_dialstring->is_valid = 1;
    AST_LIST_INSERT_TAIL(&extension_pvt->child_dialstrings, child_dialstring, next);
    AST_LIST_UNLOCK(interface_tree);
}

References ast_calloc, ast_channel_datastore_find(), ast_channel_lock, ast_channel_unlock, ast_copy_string(), AST_LIST_INSERT_TAIL, AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, extension_monitor_pvt::child_dialstrings, ast_datastore::data, extension_child_dialstring::device_name, dialed_cc_interfaces::dial_parent_id, dialed_cc_interfaces_info, id, ast_cc_monitor::id, dialed_cc_interfaces::interface_tree, extension_child_dialstring::is_valid, NULL, extension_child_dialstring::original_dialstring, ast_cc_monitor::private_data, and RETURN_IF_NOT_ENABLED.

Referenced by dial_exec_full().

ast_cc_failed()

int ast_cc_failed	(	int	core_id,
		const char *const	debug,
			...
	)

Indicate failure has occurred.

Since

1.8

If at any point a failure occurs, this is the function to call so that the core can initiate cleanup procedures.

Parameters

core_id	core_id of the CC transaction
debug	optional string to print for debugging purposes

Return values

0	Success
-1	Failure

Definition at line 3924 of file ccss.c.

{
    va_list ap;
    int res;
 
    RETURN_IF_NOT_ENABLED(0);
 
    va_start(ap, debug);
    res = cc_request_state_change(CC_FAILED, core_id, debug, ap);
    va_end(ap);
    return res;
}

References CC_FAILED, cc_request_state_change(), cc_recall_ds_data::core_id, debug, and RETURN_IF_NOT_ENABLED.

Referenced by cancel_available_timer(), cc_caller_offered(), cc_caller_requested(), cc_monitor_failed(), cccancel_exec(), ccreq_exec(), generic_recall(), kill_cores(), offer_timer_expire(), request_cc(), suspend(), unsuspend(), and wait_for_answer().

ast_cc_get_current_core_id()

int ast_cc_get_current_core_id

(

struct ast_channel *

chan

)

Get the core id for the current call.

Since

1.8

The main use of this function is for channel drivers who queue an AST_CONTROL_CC frame. A channel driver may call this function in order to get the core_id for what may become a CC request. This way, when monitor functions are called which use a core_id as a means of identification, the channel driver will have saved this information.

The channel given to this function may be an inbound or outbound channel. Both will have the necessary info on it.

Parameters

chan	The channel from which to get the core_id.

Return values

core_id	on success
-1	Failure

Definition at line 2514 of file ccss.c.

{
    struct ast_datastore *datastore;
    struct dialed_cc_interfaces *cc_interfaces;
    int core_id_return;
 
    RETURN_IF_NOT_ENABLED(-1);
 
    ast_channel_lock(chan);
    if (!(datastore = ast_channel_datastore_find(chan, &dialed_cc_interfaces_info, NULL))) {
        ast_channel_unlock(chan);
        return -1;
    }
 
    cc_interfaces = datastore->data;
    core_id_return = cc_interfaces->ignore ? -1 : cc_interfaces->core_id;
    ast_channel_unlock(chan);
    return core_id_return;
 
}

References ast_channel_datastore_find(), ast_channel_lock, ast_channel_unlock, dialed_cc_interfaces::core_id, ast_datastore::data, dialed_cc_interfaces_info, dialed_cc_interfaces::ignore, NULL, and RETURN_IF_NOT_ENABLED.

ast_cc_get_monitor_by_recall_core_id()

struct ast_cc_monitor * ast_cc_get_monitor_by_recall_core_id	(	const int	core_id,
		const char *const	device_name
	)

Get the associated monitor given the device name and core_id.

Since

1.8

The function ast_cc_is_recall is helpful for determining if a call to a specific channel is a recall. However, once you have determined that this is a recall, you will most likely need access to the private data within the associated monitor. This function is what one uses to get that monitor.

Note

This function locks the list of monitors that correspond to the core_id passed in. Be sure that you have no potential lock order issues when calling this function.

Parameters

core_id	The core ID to which this recall corresponds. This likely will have been obtained using the ast_cc_is_recall function
device_name	Which device to find the monitor for.

Return values

NULL	Appropriate monitor does not exist
non-NULL	The monitor to use for this recall

Definition at line 3542 of file ccss.c.

{
    struct cc_core_instance *core_instance = find_cc_core_instance(core_id);
    struct ast_cc_monitor *monitor_iter;
 
    RETURN_IF_NOT_ENABLED(NULL);
 
    if (!core_instance) {
        return NULL;
    }
 
    AST_LIST_LOCK(core_instance->monitors);
    AST_LIST_TRAVERSE(core_instance->monitors, monitor_iter, next) {
        if (!strcmp(monitor_iter->interface->device_name, device_name)) {
            /* Found a monitor. */
            cc_ref(monitor_iter, "Hand the requester of the monitor a reference");
            break;
        }
    }
    AST_LIST_UNLOCK(core_instance->monitors);
    cc_unref(core_instance, "Done with core instance ref in ast_cc_get_monitor_by_recall_core_id");
    return monitor_iter;
}

References AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, cc_ref(), cc_unref(), cc_core_instance::core_id, ast_cc_interface::device_name, find_cc_core_instance(), ast_cc_monitor::interface, cc_core_instance::monitors, ast_cc_monitor::next, NULL, and RETURN_IF_NOT_ENABLED.

ast_cc_get_param()

int ast_cc_get_param	(	struct ast_cc_config_params *	params,
		const char *const	name,
		char *	buf,
		size_t	buf_len
	)

get a CCSS configuration parameter, given its name

Note

Useful when reading input as a string, like from dialplan or manager.

Parameters

params	The CCSS configuration from which to get the value
name	The name of the CCSS parameter we want
buf	A preallocated buffer to hold the value
buf_len	The size of buf

Return values

0	Success
-1	Failure

Definition at line 780 of file ccss.c.

{
    const char *value = NULL;
 
    if (!strcasecmp(name, "cc_callback_sub")) {
        value = ast_get_cc_callback_sub(params);
    } else if (!strcasecmp(name, "cc_agent_policy")) {
        value = agent_policy_to_str(ast_get_cc_agent_policy(params));
    } else if (!strcasecmp(name, "cc_monitor_policy")) {
        value = monitor_policy_to_str(ast_get_cc_monitor_policy(params));
    } else if (!strcasecmp(name, "cc_agent_dialstring")) {
        value = ast_get_cc_agent_dialstring(params);
    }
    if (value) {
        ast_copy_string(buf, value, buf_len);
        return 0;
    }
 
    /* The rest of these are all ints of some sort and require some
     * snprintf-itude
     */
 
    if (!strcasecmp(name, "cc_offer_timer")) {
        snprintf(buf, buf_len, "%u", ast_get_cc_offer_timer(params));
    } else if (!strcasecmp(name, "ccnr_available_timer")) {
        snprintf(buf, buf_len, "%u", ast_get_ccnr_available_timer(params));
    } else if (!strcasecmp(name, "ccbs_available_timer")) {
        snprintf(buf, buf_len, "%u", ast_get_ccbs_available_timer(params));
    } else if (!strcasecmp(name, "cc_max_agents")) {
        snprintf(buf, buf_len, "%u", ast_get_cc_max_agents(params));
    } else if (!strcasecmp(name, "cc_max_monitors")) {
        snprintf(buf, buf_len, "%u", ast_get_cc_max_monitors(params));
    } else if (!strcasecmp(name, "cc_recall_timer")) {
        snprintf(buf, buf_len, "%u", ast_get_cc_recall_timer(params));
    } else {
        ast_log(LOG_WARNING, "%s is not a valid CC parameter. Ignoring.\n", name);
        return -1;
    }
 
    return 0;
}

References agent_policy_to_str(), ast_copy_string(), ast_get_cc_agent_dialstring(), ast_get_cc_agent_policy(), ast_get_cc_callback_sub(), ast_get_cc_max_agents(), ast_get_cc_max_monitors(), ast_get_cc_monitor_policy(), ast_get_cc_offer_timer(), ast_get_cc_recall_timer(), ast_get_ccbs_available_timer(), ast_get_ccnr_available_timer(), ast_log, buf, LOG_WARNING, monitor_policy_to_str(), name, NULL, and value.

Referenced by acf_cc_read().

ast_cc_is_config_param()

int ast_cc_is_config_param

(

const char *const

name

)

Is this a CCSS configuration parameter?

Since

1.8

Parameters

name	Name of configuration option being parsed.

Return values

1	Yes, this is a CCSS configuration parameter.
0	No, this is not a CCSS configuration parameter.

Definition at line 862 of file ccss.c.

{
    return (!strcasecmp(name, "cc_agent_policy") ||
                !strcasecmp(name, "cc_monitor_policy") ||
                !strcasecmp(name, "cc_offer_timer") ||
                !strcasecmp(name, "ccnr_available_timer") ||
                !strcasecmp(name, "ccbs_available_timer") ||
                !strcasecmp(name, "cc_max_agents") ||
                !strcasecmp(name, "cc_max_monitors") ||
                !strcasecmp(name, "cc_callback_sub") ||
                !strcasecmp(name, "cc_agent_dialstring") ||
                !strcasecmp(name, "cc_recall_timer"));
}

References name.

Referenced by process_dahdi().

ast_cc_is_enabled()

int ast_cc_is_enabled

(

void

)

Determine if CCSS is enabled.

Since

23.2.0

22.8.0

20.18.0

Return values

0	Not enabled.
1	Enabled

Definition at line 4540 of file ccss.c.

{
    return global_enabled;
}

References global_enabled.

Referenced by ast_channel_get_cc_config_params(), ast_unreal_call_setup(), ast_unreal_new_channels(), and local_call().

ast_cc_is_recall()

int ast_cc_is_recall	(	struct ast_channel *	chan,
		int *	core_id,
		const char *const	monitor_type
	)

Decide if a call to a particular channel is a CC recall.

Since

1.8

When a CC recall happens, it is important on the called side to know that the call is a CC recall and not a normal call. This function will determine first if the call in question is a CC recall. Then it will determine based on the chan parameter if the channel is being called is being recalled.

As a quick example, let's say a call is placed to SIP/1000 and SIP/1000 is currently on the phone. The caller requests CCBS. SIP/1000 finishes his call, and so the caller attempts to recall. Now, the dialplan administrator has set up this second call so that not only is SIP/1000 called, but also SIP/2000 is called. If SIP/1000's channel were passed to this function, the return value would be non-zero, but if SIP/2000's channel were passed into this function, then the return would be 0 since SIP/2000 was not one of the original devices dialed.

Note

This function may be called on a calling channel as well to determine if it is part of a CC recall.

This function will lock the channel as well as the list of monitors on the channel datastore, though the locks are not held at the same time. Be sure that you have no potential lock order issues here.

Parameters

	chan	The channel to check
[out]	core_id	If this is a valid CC recall, the core_id of the failed call will be placed in this output parameter
	monitor_type	Clarify which type of monitor type we are looking for if this is happening on a called channel. For incoming channels, this parameter is not used.

Return values

0	Either this is not a recall or it is but this channel is not part of the recall
non-zero	This is a recall and the channel in question is directly involved.

Definition at line 3459 of file ccss.c.

{
    struct ast_datastore *recall_datastore;
    struct cc_recall_ds_data *recall_data;
    struct cc_monitor_tree *interface_tree;
    char device_name[AST_CHANNEL_NAME];
    struct ast_cc_monitor *device_monitor;
    int core_id_candidate;
 
    RETURN_IF_NOT_ENABLED(0);
 
    ast_assert(core_id != NULL);
 
    *core_id = -1;
 
    ast_channel_lock(chan);
    if (!(recall_datastore = ast_channel_datastore_find(chan, &recall_ds_info, NULL))) {
        /* Obviously not a recall if the datastore isn't present */
        ast_channel_unlock(chan);
        return 0;
    }
 
    recall_data = recall_datastore->data;
 
    if (recall_data->ignore) {
        /* Though this is a recall, the call to this particular interface is not part of the
         * recall either because this is a call forward or because this is not the first
         * invocation of Dial during this call
         */
        ast_channel_unlock(chan);
        return 0;
    }
 
    if (!recall_data->nested) {
        /* If the nested flag is not set, then this means that
         * the channel passed to this function is the caller making
         * the recall. This means that we shouldn't look through
         * the monitor tree for the channel because it shouldn't be
         * there. However, this is a recall though, so return true.
         */
        *core_id = recall_data->core_id;
        ast_channel_unlock(chan);
        return 1;
    }
 
    if (ast_strlen_zero(monitor_type)) {
        /* If someone passed a NULL or empty monitor type, then it is clear
         * the channel they passed in was an incoming channel, and so searching
         * the list of dialed interfaces is not going to be helpful. Just return
         * false immediately.
         */
        ast_channel_unlock(chan);
        return 0;
    }
 
    interface_tree = recall_data->interface_tree;
    ast_channel_get_device_name(chan, device_name, sizeof(device_name));
    /* We grab the value of the recall_data->core_id so that we
     * can unlock the channel before we start looking through the
     * interface list. That way we don't have to worry about a possible
     * clash between the channel lock and the monitor tree lock.
     */
    core_id_candidate = recall_data->core_id;
    ast_channel_unlock(chan);
 
    /*
     * Now we need to find out if the channel device name
     * is in the list of interfaces in the called tree.
     */
    AST_LIST_LOCK(interface_tree);
    AST_LIST_TRAVERSE(interface_tree, device_monitor, next) {
        if (!strcmp(device_monitor->interface->device_name, device_name) &&
                !strcmp(device_monitor->interface->monitor_type, monitor_type)) {
            /* BOOM! Device is in the tree! We have a winner! */
            *core_id = core_id_candidate;
            AST_LIST_UNLOCK(interface_tree);
            return 1;
        }
    }
    AST_LIST_UNLOCK(interface_tree);
    return 0;
}

References ast_assert, ast_channel_datastore_find(), ast_channel_get_device_name(), ast_channel_lock, AST_CHANNEL_NAME, ast_channel_unlock, AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_strlen_zero(), ast_cc_monitor::core_id, cc_recall_ds_data::core_id, ast_datastore::data, ast_cc_interface::device_name, cc_recall_ds_data::ignore, ast_cc_monitor::interface, cc_recall_ds_data::interface_tree, ast_cc_interface::monitor_type, cc_recall_ds_data::nested, ast_cc_monitor::next, NULL, recall_ds_info, and RETURN_IF_NOT_ENABLED.

Referenced by cc_core_init_instance(), and wait_for_answer().

ast_cc_monitor_callee_available()

int ast_cc_monitor_callee_available	(	const int	core_id,
		const char *const	debug,
			...
	)

Alert the core that a device being monitored has become available.

Since

1.8

Note

The code in the core will take care of making sure that the information gets passed up the ladder correctly.

core_id The core ID of the corresponding CC transaction

debug

Return values

0	Request successfully queued
-1	Request could not be queued

Definition at line 3833 of file ccss.c.

{
    va_list ap;
    int res;
 
    RETURN_IF_NOT_ENABLED(0);
 
    va_start(ap, debug);
    res = cc_request_state_change(CC_CALLEE_READY, core_id, debug, ap);
    va_end(ap);
    return res;
}

References CC_CALLEE_READY, cc_request_state_change(), dialed_cc_interfaces::core_id, debug, and RETURN_IF_NOT_ENABLED.

Referenced by cc_generic_monitor_destructor(), cc_generic_monitor_suspend(), cc_generic_monitor_unsuspend(), and generic_monitor_devstate_tp_cb().

ast_cc_monitor_count()

int ast_cc_monitor_count	(	const char *const	name,
		const char *const	type
	)

Return the number of outstanding CC requests to a specific device.

Since

1.8

Note

This function will lock the list of monitors stored on every instance of the CC core. Callers of this function should be aware of this and avoid any potential lock ordering problems.

Parameters

name	The name of the monitored device
type	The type of the monitored device (e.g. "generic")

Returns

The number of CC requests for the monitor

Definition at line 4438 of file ccss.c.

{
    struct count_monitors_cb_data data = {.device_name = name, .monitor_type = type,};
 
    RETURN_IF_NOT_ENABLED(0);
 
    ao2_t_callback(cc_core_instances, OBJ_NODATA, count_monitors_cb, &data, "Counting agents");
    ast_log_dynamic_level(cc_logger_level, "Counted %d monitors\n", data.count);
    return data.count;
}

References ao2_t_callback, ast_log_dynamic_level, cc_core_instances, cc_logger_level, count_monitors_cb_data::count, count_monitors_cb(), count_monitors_cb_data::device_name, name, OBJ_NODATA, RETURN_IF_NOT_ENABLED, and type.

Referenced by ast_queue_cc_frame().

ast_cc_monitor_failed()

int ast_cc_monitor_failed	(	int	core_id,
		const char *const	monitor_name,
		const char *const	debug,
			...
	)

Indicate that a failure has occurred on a specific monitor.

Since

1.8

If a monitor should detect that a failure has occurred when communicating with its endpoint, then ast_cc_monitor_failed should be called. The big difference between ast_cc_monitor_failed and ast_cc_failed is that ast_cc_failed indicates a global failure for a CC transaction, where as ast_cc_monitor_failed is localized to a particular monitor. When ast_cc_failed is called, the entire CC transaction is torn down. When ast_cc_monitor_failed is called, only the monitor on which the failure occurred is pruned from the tree of monitors.

If there are no more devices left to monitor when this function is called, then the core will fail the CC transaction globally.

Parameters

core_id	The core ID for the CC transaction
monitor_name	The name of the monitor on which the failure occurred
debug	A debug message to print to the CC log

Definition at line 3988 of file ccss.c.

{
    struct ast_cc_monitor_failure_data *failure_data;
    int res;
    va_list ap;
 
    RETURN_IF_NOT_ENABLED(0);
 
    if (!(failure_data = ast_calloc(1, sizeof(*failure_data)))) {
        return -1;
    }
 
    if (!(failure_data->device_name = ast_strdup(monitor_name))) {
        ast_free(failure_data);
        return -1;
    }
 
    va_start(ap, debug);
    if (ast_vasprintf(&failure_data->debug, debug, ap) == -1) {
        va_end(ap);
        ast_free((char *)failure_data->device_name);
        ast_free(failure_data);
        return -1;
    }
    va_end(ap);
 
    failure_data->core_id = core_id;
 
    res = ast_taskprocessor_push(cc_core_taskprocessor, cc_monitor_failed, failure_data);
    if (res) {
        ast_free((char *)failure_data->device_name);
        ast_free((char *)failure_data->debug);
        ast_free(failure_data);
    }
    return res;
}

References ast_calloc, ast_free, ast_strdup, ast_taskprocessor_push(), ast_vasprintf, cc_core_taskprocessor, cc_monitor_failed(), ast_cc_monitor_failure_data::core_id, ast_cc_monitor_failure_data::debug, debug, ast_cc_monitor_failure_data::device_name, and RETURN_IF_NOT_ENABLED.

Referenced by ast_cc_available_timer_expire().

ast_cc_monitor_party_b_free()

int ast_cc_monitor_party_b_free

(

int

core_id

)

Alert a caller that though the callee has become free, the caller himself is not and may not call back.

When an ISDN PTMP monitor senses that his monitored party has become available, he will request the status of the called party. If he determines that the caller is currently not available, then he will call this function so that an appropriate message is sent to the caller.

Yes, you just read that correctly. The callee asks the caller what his current status is, and if the caller is currently unavailable, the monitor must send him a message anyway. WTF?

This function results in the agent's party_b_free callback being called. It is most likely that you will not need to actually implement the party_b_free callback in an agent because it is not likely that you will need to or even want to send a caller a message indicating the callee's status if the caller himself is not also free.

Parameters

core_id

The core ID of the CC transaction

Return values

0	Successfully alerted the core that party B is free
-1	Could not alert the core that party B is free

Definition at line 4104 of file ccss.c.

{
    int res;
    struct cc_core_instance *core_instance = find_cc_core_instance(core_id);
 
    RETURN_IF_NOT_ENABLED(0);
 
    if (!core_instance) {
        return -1;
    }
 
    res = ast_taskprocessor_push(cc_core_taskprocessor, cc_party_b_free, core_instance);
    if (res) {
        cc_unref(core_instance, "Unref core instance. ast_taskprocessor_push failed");
    }
    return res;
}

References ast_taskprocessor_push(), cc_core_taskprocessor, cc_party_b_free(), cc_unref(), cc_core_instance::core_id, find_cc_core_instance(), and RETURN_IF_NOT_ENABLED.

ast_cc_monitor_register()

int ast_cc_monitor_register

(

const struct ast_cc_monitor_callbacks *

callbacks

)

Register a set of monitor callbacks with the core.

Since

1.8

This is made so that at monitor creation time, the proper callbacks may be installed and the proper .init callback may be called for the monitor to establish private data.

Parameters

callbacks

The callbacks used by the monitor implementation

Return values

0	Successfully registered
-1	Failure to register

Definition at line 1186 of file ccss.c.

{
    struct cc_monitor_backend *backend;
 
    RETURN_IF_NOT_ENABLED(0);
 
    backend = ast_calloc(1, sizeof(*backend));
    if (!backend) {
        return -1;
    }
 
    backend->callbacks = callbacks;
 
    AST_RWLIST_WRLOCK(&cc_monitor_backends);
    AST_RWLIST_INSERT_TAIL(&cc_monitor_backends, backend, next);
    AST_RWLIST_UNLOCK(&cc_monitor_backends);
    return 0;
}

References ast_calloc, AST_RWLIST_INSERT_TAIL, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, cc_monitor_backend::callbacks, callbacks, cc_monitor_backend::next, and RETURN_IF_NOT_ENABLED.

Referenced by load_module(), and load_module().

ast_cc_monitor_request_acked()

int ast_cc_monitor_request_acked	(	int	core_id,
		const char *const	debug,
			...
	)

Indicate that an outbound entity has accepted our CC request.

Since

1.8

When we receive confirmation that an outbound device has accepted the CC request we sent it, this function must be called.

Parameters

core_id	core_id of the CC transaction
debug	optional string to print for debugging purposes

Return values

0	Success
-1	Failure

Definition at line 3820 of file ccss.c.

{
    va_list ap;
    int res;
 
    RETURN_IF_NOT_ENABLED(0);
 
    va_start(ap, debug);
    res = cc_request_state_change(CC_ACTIVE, core_id, debug, ap);
    va_end(ap);
    return res;
}

References CC_ACTIVE, cc_request_state_change(), dialed_cc_interfaces::core_id, debug, and RETURN_IF_NOT_ENABLED.

Referenced by cc_generic_monitor_request_cc(), and cc_stop_ringing().

ast_cc_monitor_status_request()

int ast_cc_monitor_status_request

(

int

core_id

)

Request the status of a caller or callers.

The following are all functions which are required due to the unique case where Asterisk is acting as the NT side of an ISDN PTMP connection to the caller and as the TE side of an ISDN PTMP connection to the callee. In such a case, there are several times where the PTMP monitor needs information from the agent in order to formulate the appropriate messages to send.

When an ISDN PTMP monitor senses that the callee has become available, it needs to know the current status of the caller in order to determine the appropriate response to send to the caller. In order to do this, the monitor calls this function. Responses will arrive asynchronously.

Note

Zero or more responses may come as a result.

Parameters

core_id

The core ID of the CC transaction

Return values

0	Successfully requested status
-1	Failed to request status

Definition at line 4035 of file ccss.c.

{
    int res;
    struct cc_core_instance *core_instance = find_cc_core_instance(core_id);
 
    RETURN_IF_NOT_ENABLED(0);
 
    if (!core_instance) {
        return -1;
    }
 
    res = ast_taskprocessor_push(cc_core_taskprocessor, cc_status_request, core_instance);
    if (res) {
        cc_unref(core_instance, "Unref core instance. ast_taskprocessor_push failed");
    }
    return res;
}

References ast_taskprocessor_push(), cc_core_taskprocessor, cc_status_request(), cc_unref(), cc_core_instance::core_id, find_cc_core_instance(), and RETURN_IF_NOT_ENABLED.

ast_cc_monitor_stop_ringing()

int ast_cc_monitor_stop_ringing

(

int

core_id

)

Alert a caller to stop ringing.

When an ISDN PTMP monitor becomes available, it is assumed that the agent will then cause the caller's phone to ring. In some cases, this is literally what happens. In other cases, it may be that the caller gets a visible indication on his phone that he may attempt to recall the callee. If multiple callers are recalled (since it may be possible to have a group of callers configured as a single party A), and one of those callers picks up his phone, then the ISDN PTMP monitor will alert the other callers to stop ringing. The agent's stop_ringing callback will be called, and it is up to the agent's driver to send an appropriate message to make his caller stop ringing.

Parameters

core_id

The core ID of the CC transaction

Return values

0	Successfully requested for the phone to stop ringing
-1	Could not request for the phone to stop ringing

Definition at line 4074 of file ccss.c.

{
    int res;
    struct cc_core_instance *core_instance = find_cc_core_instance(core_id);
 
    RETURN_IF_NOT_ENABLED(0);
 
    if (!core_instance) {
        return -1;
    }
 
    res = ast_taskprocessor_push(cc_core_taskprocessor, cc_stop_ringing, core_instance);
    if (res) {
        cc_unref(core_instance, "Unref core instance. ast_taskprocessor_push failed");
    }
    return res;
}

References ast_taskprocessor_push(), cc_core_taskprocessor, cc_stop_ringing(), cc_unref(), cc_core_instance::core_id, find_cc_core_instance(), and RETURN_IF_NOT_ENABLED.

ast_cc_monitor_unregister()

void ast_cc_monitor_unregister

(

const struct ast_cc_monitor_callbacks *

callbacks

)

Unregister a set of monitor callbacks with the core.

Since

1.8

If a module which makes use of a CC monitor is unloaded, then it may unregister its monitor callbacks with the core.

Parameters

callbacks

The callbacks used by the monitor implementation

Definition at line 1222 of file ccss.c.

{
    struct cc_monitor_backend *backend;
 
    RETURN_IF_NOT_ENABLED();
 
    AST_RWLIST_WRLOCK(&cc_monitor_backends);
    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&cc_monitor_backends, backend, next) {
        if (backend->callbacks == callbacks) {
            AST_RWLIST_REMOVE_CURRENT(next);
            ast_free(backend);
            break;
        }
    }
    AST_RWLIST_TRAVERSE_SAFE_END;
    AST_RWLIST_UNLOCK(&cc_monitor_backends);
}

References ast_free, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, cc_monitor_backend::callbacks, callbacks, cc_monitor_backend::next, and RETURN_IF_NOT_ENABLED.

Referenced by __unload_module(), and unload_module().

ast_cc_offer()

int ast_cc_offer

(

struct ast_channel *

caller_chan

)

Offer CC to a caller.

Since

1.8

This function is called from ast_hangup if the caller is eligible to be offered call completion service.

Parameters

caller_chan

The calling channel

Return values

-1	Error
0	Success

Definition at line 3780 of file ccss.c.

{
    int core_id;
    int res = -1;
    struct ast_datastore *datastore;
    struct dialed_cc_interfaces *cc_interfaces;
    char cc_is_offerable;
 
    RETURN_IF_NOT_ENABLED(0);
 
    ast_channel_lock(caller_chan);
    if (!(datastore = ast_channel_datastore_find(caller_chan, &dialed_cc_interfaces_info, NULL))) {
        ast_channel_unlock(caller_chan);
        return res;
    }
 
    cc_interfaces = datastore->data;
    cc_is_offerable = cc_interfaces->is_original_caller;
    core_id = cc_interfaces->core_id;
    ast_channel_unlock(caller_chan);
 
    if (cc_is_offerable) {
        res = cc_offer(core_id, "CC offered to caller %s", ast_channel_name(caller_chan));
    }
    return res;
}

References ast_channel_datastore_find(), ast_channel_lock, ast_channel_name(), ast_channel_unlock, cc_offer(), dialed_cc_interfaces::core_id, cc_recall_ds_data::core_id, ast_datastore::data, dialed_cc_interfaces_info, dialed_cc_interfaces::is_original_caller, NULL, and RETURN_IF_NOT_ENABLED.

Referenced by ast_hangup().

ast_cc_request_is_within_limits()

int ast_cc_request_is_within_limits

(

void

)

Check if the incoming CC request is within the bounds set by the cc_max_requests configuration option.

Since

1.8

It is recommended that an entity which receives an incoming CC request calls this function before calling ast_cc_agent_accept_request. This way, immediate feedback can be given to the caller about why his request was rejected.

If this is not called and a state change to CC_CALLER_REQUESTED is made, then the core will still not allow for the request to succeed. However, if done this way, it may not be obvious to the requestor why the request failed.

Return values

0	Not within the limits. Fail.
non-zero	Within the limits. Success.

Definition at line 2509 of file ccss.c.

{
    return cc_request_count < global_cc_max_requests;
}

References cc_request_count, and global_cc_max_requests.

Referenced by cc_caller_requested(), cc_interfaces_datastore_init(), and ccreq_exec().

ast_cc_set_param()

int ast_cc_set_param	(	struct ast_cc_config_params *	params,
		const char *const	name,
		const char *	value
	)

set a CCSS configuration parameter, given its name

Note

Useful when parsing config files when used in conjunction with ast_ccss_is_cc_config_param.

Parameters

params	The parameter structure to set the value on
name	The name of the cc parameter
value	The value of the parameter

Return values

0	Success
-1	Failure

Definition at line 823 of file ccss.c.

{
    unsigned int value_as_uint;
    if (!strcasecmp(name, "cc_agent_policy")) {
        return ast_set_cc_agent_policy(params, str_to_agent_policy(value));
    } else if (!strcasecmp(name, "cc_monitor_policy")) {
        return ast_set_cc_monitor_policy(params, str_to_monitor_policy(value));
    } else if (!strcasecmp(name, "cc_agent_dialstring")) {
        ast_set_cc_agent_dialstring(params, value);
    } else if (!strcasecmp(name, "cc_callback_sub")) {
        ast_set_cc_callback_sub(params, value);
        return 0;
    }
 
    if (sscanf(value, "%30u", &value_as_uint) != 1) {
        return -1;
    }
 
    if (!strcasecmp(name, "cc_offer_timer")) {
        ast_set_cc_offer_timer(params, value_as_uint);
    } else if (!strcasecmp(name, "ccnr_available_timer")) {
        ast_set_ccnr_available_timer(params, value_as_uint);
    } else if (!strcasecmp(name, "ccbs_available_timer")) {
        ast_set_ccbs_available_timer(params, value_as_uint);
    } else if (!strcasecmp(name, "cc_max_agents")) {
        ast_set_cc_max_agents(params, value_as_uint);
    } else if (!strcasecmp(name, "cc_max_monitors")) {
        ast_set_cc_max_monitors(params, value_as_uint);
    } else if (!strcasecmp(name, "cc_recall_timer")) {
        ast_set_cc_recall_timer(params, value_as_uint);
    } else {
        ast_log(LOG_WARNING, "%s is not a valid CC parameter. Ignoring.\n", name);
        return -1;
    }
 
    return 0;
}

References ast_log, ast_set_cc_agent_dialstring(), ast_set_cc_agent_policy(), ast_set_cc_callback_sub(), ast_set_cc_max_agents(), ast_set_cc_max_monitors(), ast_set_cc_monitor_policy(), ast_set_cc_offer_timer(), ast_set_cc_recall_timer(), ast_set_ccbs_available_timer(), ast_set_ccnr_available_timer(), LOG_WARNING, name, str_to_agent_policy(), str_to_monitor_policy(), and value.

Referenced by acf_cc_write(), and process_dahdi().

ast_get_cc_agent_dialstring()

const char * ast_get_cc_agent_dialstring

(

struct ast_cc_config_params *

config

)

Get the cc_agent_dialstring.

Since

1.8

Parameters

config

The configuration to retrieve the cc_agent_dialstring from

Returns

The cc_agent_dialstring from this configuration

Definition at line 977 of file ccss.c.

{
    return config->cc_agent_dialstring;
}

References config.

Referenced by ast_cc_get_param(), and generic_recall().

ast_get_cc_agent_policy()

enum ast_cc_agent_policies ast_get_cc_agent_policy

(

struct ast_cc_config_params *

config

)

Get the cc_agent_policy.

Since

1.8

Parameters

config

The configuration to retrieve the policy from

Returns

The current cc_agent_policy for this configuration

Definition at line 883 of file ccss.c.

{
    return config->cc_agent_policy;
}

References ast_cc_config_params::cc_agent_policy, and config.

Referenced by ast_cc_call_init(), ast_cc_get_param(), cc_core_init_instance(), and find_agent_callbacks().

ast_get_cc_callback_sub()

const char * ast_get_cc_callback_sub

(

struct ast_cc_config_params *

config

)

Get the name of the callback subroutine.

Since

11

Parameters

config

The configuration to retrieve the callback_sub from

Returns

The callback_sub name

Definition at line 1011 of file ccss.c.

{
    return config->cc_callback_sub;
}

References config.

Referenced by ast_cc_get_param(), and generic_recall().

ast_get_cc_max_agents()

unsigned int ast_get_cc_max_agents

(

struct ast_cc_config_params *

config

)

Get the cc_max_agents.

Since

1.8

Parameters

config

The configuration to retrieve the cc_max_agents from

Returns

The cc_max_agents from this configuration

Definition at line 991 of file ccss.c.

{
    return config->cc_max_agents;
}

References config.

Referenced by ast_cc_get_param(), and cc_core_init_instance().

ast_get_cc_max_monitors()

unsigned int ast_get_cc_max_monitors

(

struct ast_cc_config_params *

config

)

Get the cc_max_monitors.

Since

1.8

Parameters

config

The configuration to retrieve the cc_max_monitors from

Returns

The cc_max_monitors from this configuration

Definition at line 1001 of file ccss.c.

{
    return config->cc_max_monitors;
}

References config.

Referenced by ast_cc_get_param(), and ast_queue_cc_frame().

ast_get_cc_monitor_policy()

enum ast_cc_monitor_policies ast_get_cc_monitor_policy

(

struct ast_cc_config_params *

config

)

Get the cc_monitor_policy.

Since

1.8

Parameters

config

The configuration to retrieve the cc_monitor_policy from

Returns

The cc_monitor_policy retrieved from the configuration

Definition at line 900 of file ccss.c.

{
    return config->cc_monitor_policy;
}

References config.

Referenced by analog_call(), ast_cc_call_failed(), ast_cc_get_param(), and dahdi_cc_callback().

ast_get_cc_offer_timer()

unsigned int ast_get_cc_offer_timer

(

struct ast_cc_config_params *

config

)

Get the cc_offer_timer.

Since

1.8

Parameters

config

The configuration to retrieve the cc_offer_timer from

Returns

The cc_offer_timer from this configuration

Definition at line 917 of file ccss.c.

{
    return config->cc_offer_timer;
}

References config.

Referenced by ast_cc_get_param(), and cc_generic_agent_start_offer_timer().

ast_get_cc_recall_timer()

unsigned int ast_get_cc_recall_timer

(

struct ast_cc_config_params *

config

)

Get the cc_recall_timer.

Since

1.8

Parameters

config

The configuration to retrieve the cc_recall_timer from

Returns

The cc_recall_timer from this configuration

Definition at line 947 of file ccss.c.

{
    return config->cc_recall_timer;
}

References config.

Referenced by ast_cc_get_param(), and generic_recall().

ast_get_ccbs_available_timer()

unsigned int ast_get_ccbs_available_timer

(

struct ast_cc_config_params *

config

)

Get the ccbs_available_timer.

Since

1.8

Parameters

config

The configuration to retrieve the ccbs_available_timer from

Returns

The ccbs_available_timer from this configuration

Definition at line 962 of file ccss.c.

{
    return config->ccbs_available_timer;
}

References config.

Referenced by ast_cc_get_param(), and cc_generic_monitor_request_cc().

ast_get_ccnr_available_timer()

unsigned int ast_get_ccnr_available_timer

(

struct ast_cc_config_params *

config

)

Get the ccnr_available_timer.

Since

1.8

Parameters

config

The configuration to retrieve the ccnr_available_timer from

Returns

The ccnr_available_timer from this configuration

Definition at line 932 of file ccss.c.

{
    return config->ccnr_available_timer;
}

References config.

Referenced by ast_cc_get_param(), and cc_generic_monitor_request_cc().

ast_handle_cc_control_frame()

void ast_handle_cc_control_frame	(	struct ast_channel *	inbound,
		struct ast_channel *	outbound,
		void *	frame_data
	)

Properly react to a CC control frame.

Since

1.8

When a CC-capable application, such as Dial, receives a frame of type AST_CONTROL_CC, then it may call this function in order to have the device which sent the frame added to the tree of interfaces which is kept on the inbound channel.

Parameters

inbound	The inbound channel
outbound	The outbound channel (The one from which the CC frame was read)
frame_data	The ast_frame's data.ptr field.

Unless we are ignoring CC for some reason, we will always call this function when we read an AST_CONTROL_CC frame from an outbound channel.

This function will call cc_device_monitor_init to create the new cc_monitor for the device from which we read the frame. In addition, the new device will be added to the monitor tree on the dialed_cc_interfaces datastore on the inbound channel.

If this is the first AST_CONTROL_CC frame that we have handled for this call, then we will also initialize the CC core for this call.

Definition at line 2334 of file ccss.c.

{
    char *device_name;
    char *dialstring;
    struct ast_cc_monitor *monitor;
    struct ast_datastore *cc_datastore;
    struct dialed_cc_interfaces *cc_interfaces;
    struct cc_control_payload *cc_data = frame_data;
    struct cc_core_instance *core_instance;
 
    RETURN_IF_NOT_ENABLED();
 
    device_name = cc_data->device_name;
    dialstring = cc_data->dialstring;
 
    ast_channel_lock(inbound);
    if (!(cc_datastore = ast_channel_datastore_find(inbound, &dialed_cc_interfaces_info, NULL))) {
        ast_log(LOG_WARNING, "Unable to retrieve CC datastore while processing CC frame from '%s'. CC services will be unavailable.\n", device_name);
        ast_channel_unlock(inbound);
        call_destructor_with_no_monitor(cc_data->monitor_type, cc_data->private_data);
        return;
    }
 
    cc_interfaces = cc_datastore->data;
 
    if (cc_interfaces->ignore) {
        ast_channel_unlock(inbound);
        call_destructor_with_no_monitor(cc_data->monitor_type, cc_data->private_data);
        return;
    }
 
    if (!cc_interfaces->is_original_caller) {
        /* If the is_original_caller is not set on the *inbound* channel, then
         * it must be a local channel. As such, we do not want to create a core instance
         * or an agent for the local channel. Instead, we want to pass this along to the
         * other side of the local channel so that the original caller can benefit.
         */
        ast_channel_unlock(inbound);
        ast_indicate_data(inbound, AST_CONTROL_CC, cc_data, sizeof(*cc_data));
        return;
    }
 
    core_instance = find_cc_core_instance(cc_interfaces->core_id);
    if (!core_instance) {
        core_instance = cc_core_init_instance(inbound, cc_interfaces->interface_tree,
            cc_interfaces->core_id, cc_data);
        if (!core_instance) {
            cc_interfaces->ignore = 1;
            ast_channel_unlock(inbound);
            call_destructor_with_no_monitor(cc_data->monitor_type, cc_data->private_data);
            return;
        }
    }
 
    ast_channel_unlock(inbound);
 
    /* Yeah this kind of sucks, but luckily most people
     * aren't dialing thousands of interfaces on every call
     *
     * This traversal helps us to not create duplicate monitors in
     * case a device queues multiple CC control frames.
     */
    AST_LIST_LOCK(cc_interfaces->interface_tree);
    AST_LIST_TRAVERSE(cc_interfaces->interface_tree, monitor, next) {
        if (!strcmp(monitor->interface->device_name, device_name)) {
            ast_log_dynamic_level(cc_logger_level, "Core %d: Device %s sent us multiple CC control frames. Ignoring those beyond the first.\n",
                    core_instance->core_id, device_name);
            AST_LIST_UNLOCK(cc_interfaces->interface_tree);
            cc_unref(core_instance, "Returning early from ast_handle_cc_control_frame. Unref core_instance");
            call_destructor_with_no_monitor(cc_data->monitor_type, cc_data->private_data);
            return;
        }
    }
    AST_LIST_UNLOCK(cc_interfaces->interface_tree);
 
    if (!(monitor = cc_device_monitor_init(device_name, dialstring, cc_data, core_instance->core_id))) {
        ast_log(LOG_WARNING, "Unable to create CC device interface for '%s'. CC services will be unavailable on this interface.\n", device_name);
        cc_unref(core_instance, "Returning early from ast_handle_cc_control_frame. Unref core_instance");
        call_destructor_with_no_monitor(cc_data->monitor_type, cc_data->private_data);
        return;
    }
 
    AST_LIST_LOCK(cc_interfaces->interface_tree);
    cc_ref(monitor, "monitor tree's reference to the monitor");
    AST_LIST_INSERT_TAIL(cc_interfaces->interface_tree, monitor, next);
    AST_LIST_UNLOCK(cc_interfaces->interface_tree);
 
    cc_extension_monitor_change_is_valid(core_instance, monitor->parent_id, monitor->interface->device_name, 0);
 
    cc_publish_available(cc_interfaces->core_id, device_name, cc_service_to_string(cc_data->service));
 
    cc_unref(core_instance, "Done with core_instance after handling CC control frame");
    cc_unref(monitor, "Unref reference from allocating monitor");
}

References ast_channel_datastore_find(), ast_channel_lock, ast_channel_unlock, AST_CONTROL_CC, ast_indicate_data(), AST_LIST_INSERT_TAIL, AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_log, ast_log_dynamic_level, call_destructor_with_no_monitor(), cc_core_init_instance(), cc_device_monitor_init(), cc_extension_monitor_change_is_valid(), cc_logger_level, cc_publish_available(), cc_ref(), cc_service_to_string(), cc_unref(), cc_core_instance::core_id, dialed_cc_interfaces::core_id, ast_datastore::data, ast_cc_interface::device_name, cc_control_payload::device_name, dialed_cc_interfaces_info, ast_cc_monitor::dialstring, cc_control_payload::dialstring, find_cc_core_instance(), dialed_cc_interfaces::ignore, ast_cc_monitor::interface, dialed_cc_interfaces::interface_tree, dialed_cc_interfaces::is_original_caller, LOG_WARNING, cc_control_payload::monitor_type, NULL, ast_cc_monitor::parent_id, cc_control_payload::private_data, RETURN_IF_NOT_ENABLED, and cc_control_payload::service.

Referenced by ast_cc_busy_interface(), ast_cc_call_failed(), and wait_for_answer().

ast_ignore_cc()

void ast_ignore_cc

(

struct ast_channel *

chan

)

Mark the channel to ignore further CC activity.

Since

1.8

When a CC-capable application, such as Dial, has finished with all CC processing for a channel and knows that any further CC processing should be ignored, this function should be called.

Parameters

chan	The channel for which further CC processing should be ignored.

Definition at line 3747 of file ccss.c.

{
    struct ast_datastore *cc_datastore;
    struct ast_datastore *cc_recall_datastore;
    struct dialed_cc_interfaces *cc_interfaces;
    struct cc_recall_ds_data *recall_cc_data;
 
    RETURN_IF_NOT_ENABLED();
 
    ast_channel_lock(chan);
    if ((cc_datastore = ast_channel_datastore_find(chan, &dialed_cc_interfaces_info, NULL))) {
        cc_interfaces = cc_datastore->data;
        cc_interfaces->ignore = 1;
    }
 
    if ((cc_recall_datastore = ast_channel_datastore_find(chan, &recall_ds_info, NULL))) {
        recall_cc_data = cc_recall_datastore->data;
        recall_cc_data->ignore = 1;
    }
    ast_channel_unlock(chan);
}

References ast_channel_datastore_find(), ast_channel_lock, ast_channel_unlock, ast_datastore::data, dialed_cc_interfaces_info, dialed_cc_interfaces::ignore, cc_recall_ds_data::ignore, NULL, recall_ds_info, and RETURN_IF_NOT_ENABLED.

Referenced by dial_exec_full(), and do_forward().

ast_queue_cc_frame()

int ast_queue_cc_frame	(	struct ast_channel *	chan,
		const char *const	monitor_type,
		const char *const	dialstring,
		enum ast_cc_service_type	service,
		void *	private_data
	)

Queue an AST_CONTROL_CC frame.

Since

1.8

Note

Since this function calls ast_queue_frame, the channel will be locked during the course of this function.

Parameters

chan	The channel onto which to queue the frame
monitor_type	The type of monitor to use when CC is requested
dialstring	The dial string used to call the device
service	The type of CC service the device is willing to offer
private_data	If a native monitor is being used, and some channel-driver-specific private data has been allocated, then this parameter should contain a pointer to that data. If using a generic monitor, this parameter should remain NULL. Note that if this function should fail at some point, it is the responsibility of the caller to free the private data upon return.

Return values

0	Success
-1	Error

Definition at line 4206 of file ccss.c.

{
    struct ast_frame frame = {0,};
    char device_name[AST_CHANNEL_NAME];
    int retval;
    struct ast_cc_config_params *cc_params;
 
    RETURN_IF_NOT_ENABLED(0);
 
    cc_params = ast_channel_get_cc_config_params(chan);
    if (!cc_params) {
        return -1;
    }
    ast_channel_get_device_name(chan, device_name, sizeof(device_name));
    if (ast_cc_monitor_count(device_name, monitor_type) >= ast_get_cc_max_monitors(cc_params)) {
        ast_log(LOG_NOTICE, "Not queuing a CC frame for device %s since it already has its maximum monitors allocated\n", device_name);
        return -1;
    }
 
    if (ast_cc_build_frame(chan, cc_params, monitor_type, device_name, dialstring, service, private_data, &frame)) {
        /* Frame building failed. We can't use this. */
        return -1;
    }
    retval = ast_queue_frame(chan, &frame);
    ast_frfree(&frame);
    return retval;
}

References ast_cc_build_frame(), ast_cc_monitor_count(), ast_channel_get_cc_config_params(), ast_channel_get_device_name(), AST_CHANNEL_NAME, ast_frfree, ast_get_cc_max_monitors(), ast_log, ast_queue_frame(), LOG_NOTICE, RETURN_IF_NOT_ENABLED, and service.

Referenced by analog_call().

ast_set_cc_agent_dialstring()

void ast_set_cc_agent_dialstring	(	struct ast_cc_config_params *	config,
		const char *const	value
	)

Set the cc_agent_dialstring.

Since

1.8

Parameters

config	The configuration to set the cc_agent_dialstring on
value	The new cc_agent_dialstring we want to change to

Definition at line 982 of file ccss.c.

{
    if (ast_strlen_zero(value)) {
        config->cc_agent_dialstring[0] = '\0';
    } else {
        ast_copy_string(config->cc_agent_dialstring, value, sizeof(config->cc_agent_dialstring));
    }
}

References ast_copy_string(), ast_strlen_zero(), config, and value.

Referenced by ast_cc_set_param().

ast_set_cc_agent_policy()

int ast_set_cc_agent_policy	(	struct ast_cc_config_params *	config,
		enum ast_cc_agent_policies	value
	)

Set the cc_agent_policy.

Since

1.8

Parameters

config	The configuration to set the cc_agent_policy on
value	The new cc_agent_policy we want to change to

Return values

0	Success
-1	Failure (likely due to bad input)

Definition at line 888 of file ccss.c.

{
    /* Screw C and its weak type checking for making me have to do this
     * validation at runtime.
     */
    if (value < AST_CC_AGENT_NEVER || value > AST_CC_AGENT_GENERIC) {
        return -1;
    }
    config->cc_agent_policy = value;
    return 0;
}

References AST_CC_AGENT_GENERIC, config, and value.

Referenced by ast_cc_set_param().

ast_set_cc_callback_sub()

void ast_set_cc_callback_sub	(	struct ast_cc_config_params *	config,
		const char *const	value
	)

Set the callback subroutine name.

Since

11

Parameters

config	The configuration to set the callback_sub on
value	The new callback subroutine we want to change to

Definition at line 1016 of file ccss.c.

{
    if (ast_strlen_zero(value)) {
        config->cc_callback_sub[0] = '\0';
    } else {
        ast_copy_string(config->cc_callback_sub, value, sizeof(config->cc_callback_sub));
    }
}

References ast_copy_string(), ast_strlen_zero(), config, and value.

Referenced by ast_cc_set_param().

ast_set_cc_interfaces_chanvar()

int ast_set_cc_interfaces_chanvar	(	struct ast_channel *	chan,
		const char *const	extension
	)

Set the CC_INTERFACES channel variable for a channel using an.

Since

1.8

extension@context 

as a starting point

The CC_INTERFACES channel variable will have the interfaces that should be called back for a specific PBX instance. This version of the function is used mainly by local channels, wherein we need to set CC_INTERFACES based on an extension and context that appear in the middle of the tree of dialed interfaces.

Note

This function will lock the channel as well as the list of monitors stored on the channel's CC recall datastore, though neither are held at the same time. Callers of this function should be aware of potential lock ordering problems that may arise.

Parameters

chan	The channel to set the CC_INTERFACES variable on
extension	The name of the extension for which we're setting the variable. This should be in the form of exten@context

Definition at line 3693 of file ccss.c.

{
    struct ast_datastore *recall_datastore;
    struct cc_monitor_tree *interface_tree;
    struct ast_cc_monitor *monitor_iter;
    struct cc_recall_ds_data *recall_data;
    struct ast_str *str = ast_str_create(64);
    int core_id;
 
    RETURN_IF_NOT_ENABLED(0);
 
    if (!str) {
        return -1;
    }
 
    ast_channel_lock(chan);
    if (!(recall_datastore = ast_channel_datastore_find(chan, &recall_ds_info, NULL))) {
        ast_channel_unlock(chan);
        ast_free(str);
        return -1;
    }
    recall_data = recall_datastore->data;
    interface_tree = recall_data->interface_tree;
    core_id = recall_data->core_id;
    ast_channel_unlock(chan);
 
    AST_LIST_LOCK(interface_tree);
    AST_LIST_TRAVERSE(interface_tree, monitor_iter, next) {
        if (!strcmp(monitor_iter->interface->device_name, extension)) {
            break;
        }
    }
 
    if (!monitor_iter) {
        /* We couldn't find this extension. This may be because
         * we have been directed into an unexpected extension because
         * the admin has changed a CC_INTERFACES variable at some point.
         */
        AST_LIST_UNLOCK(interface_tree);
        ast_free(str);
        return -1;
    }
 
    build_cc_interfaces_chanvar(monitor_iter, &str);
    AST_LIST_UNLOCK(interface_tree);
 
    pbx_builtin_setvar_helper(chan, "CC_INTERFACES", ast_str_buffer(str));
    ast_log_dynamic_level(cc_logger_level, "Core %d: CC_INTERFACES set to %s\n",
            core_id, ast_str_buffer(str));
 
    ast_free(str);
    return 0;
}

References ast_channel_datastore_find(), ast_channel_lock, ast_channel_unlock, ast_free, AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_log_dynamic_level, ast_str_buffer(), ast_str_create, build_cc_interfaces_chanvar(), cc_logger_level, cc_recall_ds_data::core_id, ast_datastore::data, ast_cc_interface::device_name, ast_cc_monitor::interface, cc_recall_ds_data::interface_tree, NULL, pbx_builtin_setvar_helper(), recall_ds_info, RETURN_IF_NOT_ENABLED, and str.

Referenced by local_call().

ast_set_cc_max_agents()

void ast_set_cc_max_agents	(	struct ast_cc_config_params *	config,
		unsigned int	value
	)

Set the cc_max_agents.

Since

1.8

Parameters

config	The configuration to set the cc_max_agents on
value	The new cc_max_agents we want to change to

Definition at line 996 of file ccss.c.

{
    config->cc_max_agents = value;
}

References config, and value.

Referenced by ast_cc_set_param().

ast_set_cc_max_monitors()

void ast_set_cc_max_monitors	(	struct ast_cc_config_params *	config,
		unsigned int	value
	)

Set the cc_max_monitors.

Since

1.8

Parameters

config	The configuration to set the cc_max_monitors on
value	The new cc_max_monitors we want to change to

Definition at line 1006 of file ccss.c.

{
    config->cc_max_monitors = value;
}

References config, and value.

Referenced by ast_cc_set_param().

ast_set_cc_monitor_policy()

int ast_set_cc_monitor_policy	(	struct ast_cc_config_params *	config,
		enum ast_cc_monitor_policies	value
	)

Set the cc_monitor_policy.

Since

1.8

Parameters

config	The configuration to set the cc_monitor_policy on
value	The new cc_monitor_policy we want to change to

Return values

0	Success
-1	Failure (likely due to bad input)

Definition at line 905 of file ccss.c.

{
    /* Screw C and its weak type checking for making me have to do this
     * validation at runtime.
     */
    if (value < AST_CC_MONITOR_NEVER || value > AST_CC_MONITOR_ALWAYS) {
        return -1;
    }
    config->cc_monitor_policy = value;
    return 0;
}

References AST_CC_MONITOR_ALWAYS, config, and value.

Referenced by ast_cc_set_param().

ast_set_cc_offer_timer()

void ast_set_cc_offer_timer	(	struct ast_cc_config_params *	config,
		unsigned int	value
	)

Set the cc_offer_timer.

Since

1.8

Parameters

config	The configuration to set the cc_offer_timer on
value	The new cc_offer_timer we want to change to

Definition at line 922 of file ccss.c.

{
    /* 0 is an unreasonable value for any timer. Stick with the default */
    if (value == 0) {
        ast_log(LOG_WARNING, "0 is an invalid value for cc_offer_timer. Retaining value as %u\n", config->cc_offer_timer);
        return;
    }
    config->cc_offer_timer = value;
}

References ast_log, config, LOG_WARNING, and value.

Referenced by ast_cc_set_param().

ast_set_cc_recall_timer()

void ast_set_cc_recall_timer	(	struct ast_cc_config_params *	config,
		unsigned int	value
	)

Set the cc_recall_timer.

Since

1.8

Parameters

config	The configuration to set the cc_recall_timer on
value	The new cc_recall_timer we want to change to

Definition at line 952 of file ccss.c.

{
    /* 0 is an unreasonable value for any timer. Stick with the default */
    if (value == 0) {
        ast_log(LOG_WARNING, "0 is an invalid value for ccnr_available_timer. Retaining value as %u\n", config->cc_recall_timer);
        return;
    }
    config->cc_recall_timer = value;
}

References ast_log, config, LOG_WARNING, and value.

Referenced by ast_cc_set_param().

ast_set_ccbs_available_timer()

void ast_set_ccbs_available_timer	(	struct ast_cc_config_params *	config,
		unsigned int	value
	)

Set the ccbs_available_timer.

Since

1.8

Parameters

config	The configuration to set the ccbs_available_timer on
value	The new ccbs_available_timer we want to change to

Definition at line 967 of file ccss.c.

{
    /* 0 is an unreasonable value for any timer. Stick with the default */
    if (value == 0) {
        ast_log(LOG_WARNING, "0 is an invalid value for ccbs_available_timer. Retaining value as %u\n", config->ccbs_available_timer);
        return;
    }
    config->ccbs_available_timer = value;
}

References ast_log, config, LOG_WARNING, and value.

Referenced by ast_cc_set_param().

ast_set_ccnr_available_timer()

void ast_set_ccnr_available_timer	(	struct ast_cc_config_params *	config,
		unsigned int	value
	)

Set the ccnr_available_timer.

Since

1.8

Parameters

config	The configuration to set the ccnr_available_timer on
value	The new ccnr_available_timer we want to change to

Definition at line 937 of file ccss.c.

{
    /* 0 is an unreasonable value for any timer. Stick with the default */
    if (value == 0) {
        ast_log(LOG_WARNING, "0 is an invalid value for ccnr_available_timer. Retaining value as %u\n", config->ccnr_available_timer);
        return;
    }
    config->ccnr_available_timer = value;
}

References ast_log, config, LOG_WARNING, and value.

Referenced by ast_cc_set_param().

ast_setup_cc_recall_datastore()

int ast_setup_cc_recall_datastore	(	struct ast_channel *	chan,
		const int	core_id
	)

Set up a CC recall datastore on a channel.

Since

1.8

Implementers of protocol-specific CC agents will need to call this function in order for the channel to have the necessary interfaces to recall.

This function must be called by the implementer once it has been detected that an inbound call is a cc_recall. After allocating the channel, call this function, followed by ast_cc_set_cc_interfaces_chanvar. While it would be nice to be able to have the core do this automatically, it just cannot be done given the current architecture.

Definition at line 3423 of file ccss.c.

{
    struct ast_datastore *recall_datastore;
    struct cc_recall_ds_data *recall_data;
    struct cc_core_instance *core_instance;
 
    RETURN_IF_NOT_ENABLED(0);
 
    recall_datastore = ast_datastore_alloc(&recall_ds_info, NULL);
    if (!recall_datastore) {
        return -1;
    }
 
    if (!(recall_data = ast_calloc(1, sizeof(*recall_data)))) {
        ast_datastore_free(recall_datastore);
        return -1;
    }
 
    if (!(core_instance = find_cc_core_instance(core_id))) {
        ast_free(recall_data);
        ast_datastore_free(recall_datastore);
        return -1;
    }
 
    recall_data->interface_tree = cc_ref(core_instance->monitors,
            "Bump refcount for monitor tree for recall datastore");
    recall_data->core_id = core_id;
    recall_datastore->data = recall_data;
    recall_datastore->inheritance = DATASTORE_INHERIT_FOREVER;
    ast_channel_lock(chan);
    ast_channel_datastore_add(chan, recall_datastore);
    ast_channel_unlock(chan);
    cc_unref(core_instance, "Recall datastore set up. No need for core_instance ref");
    return 0;
}

References ast_calloc, ast_channel_datastore_add(), ast_channel_lock, ast_channel_unlock, ast_datastore_alloc, ast_datastore_free(), ast_free, cc_ref(), cc_unref(), cc_core_instance::core_id, cc_recall_ds_data::core_id, ast_datastore::data, DATASTORE_INHERIT_FOREVER, find_cc_core_instance(), ast_datastore::inheritance, cc_recall_ds_data::interface_tree, cc_core_instance::monitors, NULL, recall_ds_info, and RETURN_IF_NOT_ENABLED.

Referenced by generic_recall().