Mon Mar 19 11:30:37 2012

Asterisk developer's documentation


ccss.h File Reference

Call Completion Supplementary Services API. More...

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

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...

Defines

#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

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.
ast_cc_agentast_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.
ast_cc_monitorast_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_init (void)
 Initialize CCSS.
int ast_cc_is_config_param (const char *const name)
 Is this a CCSS configuration parameter?
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_macro (struct ast_cc_config_params *config)
 Get the name of the callback_macro.
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_macro (struct ast_cc_config_params *config, const char *const value)
 Set the callback_macro 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 extension as a starting point.
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 <mmichelson@digium.com>

Definition in file ccss.h.


Define Documentation

 
#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.

Referenced by ast_channel_cc_params_init(), build_peer(), cc_agent_init(), cc_device_monitor_init(), channel_cc_params_copy(), dahdi_chan_conf_default(), duplicate_pseudo(), sip_alloc(), and temp_peer().

#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 472 of file ccss.h.

Referenced by analog_call(), ast_cc_call_failed(), dahdi_cc_callback(), sig_pri_cc_available(), sig_pri_cc_generic_check(), and sip_handle_cc().


Typedef Documentation

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.

Returns:
Nothing

Definition at line 1583 of file ccss.h.


Enumeration Type Documentation

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.

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

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.

00047                            {
00048    /*! Never offer CCSS to the caller */
00049    AST_CC_AGENT_NEVER,
00050    /*! Offer CCSS using native signaling */
00051    AST_CC_AGENT_NATIVE,
00052    /*! Use generic agent for caller */
00053    AST_CC_AGENT_GENERIC,
00054 };

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 861 of file ccss.h.

00861                                   {
00862    /*! CC request accepted */
00863    AST_CC_AGENT_RESPONSE_SUCCESS,
00864    /*! CC request not allowed at this time. Invalid state transition. */
00865    AST_CC_AGENT_RESPONSE_FAILURE_INVALID,
00866    /*! Too many CC requests in the system. */
00867    AST_CC_AGENT_RESPONSE_FAILURE_TOO_MANY,
00868 };

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 479 of file ccss.h.

00479                           {
00480    AST_CC_DEVICE_MONITOR,
00481    AST_CC_EXTENSION_MONITOR,
00482 };

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.

00074                              {
00075    /*! Never accept CCSS offers from callee */
00076    AST_CC_MONITOR_NEVER,
00077    /* CCSS only available if callee offers it through signaling */
00078    AST_CC_MONITOR_NATIVE,
00079    /*! Always use CCSS generic monitor for callee
00080     * Note that if callee offers CCSS natively, we still
00081     * will use a generic CCSS monitor if this is set
00082     */
00083    AST_CC_MONITOR_GENERIC,
00084    /*! Accept native CCSS offers, but if no offer is present,
00085     * use a generic CCSS monitor
00086     */
00087    AST_CC_MONITOR_ALWAYS,
00088 };

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.

00032                          {
00033    /* No Service available/requested */
00034    AST_CC_NONE,
00035    /* Call Completion Busy Subscriber */
00036    AST_CC_CCBS,
00037    /* Call Completion No Response */
00038    AST_CC_CCNR,
00039    /* Call Completion Not Logged In (currently SIP only) */
00040    AST_CC_CCNL,
00041 };


Function Documentation

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 559 of file ccss.c.

References __ast_malloc(), ast_cc_default_config_params(), and ast_malloc.

00560 {
00561 #if defined(__AST_DEBUG_MALLOC)
00562    struct ast_cc_config_params *params = __ast_malloc(sizeof(*params), file, line, function);
00563 #else
00564    struct ast_cc_config_params *params = ast_malloc(sizeof(*params));
00565 #endif
00566 
00567    if (!params) {
00568       return NULL;
00569    }
00570 
00571    ast_cc_default_config_params(params);
00572    return params;
00573 }

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 3495 of file ccss.c.

References CC_CALLER_REQUESTED, and cc_request_state_change().

Referenced by ccreq_exec(), handle_cc_subscribe(), and sig_pri_handle_cis_subcmds().

03496 {
03497    va_list ap;
03498    int res;
03499 
03500    va_start(ap, debug);
03501    res = cc_request_state_change(CC_CALLER_REQUESTED, core_id, debug, ap);
03502    va_end(ap);
03503    return res;
03504 }

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 442 of file ccss.c.

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

Referenced by find_sip_cc_agent_by_notify_uri(), find_sip_cc_agent_by_original_callid(), find_sip_cc_agent_by_subscribe_uri(), and sig_pri_find_cc_agent_by_cc_id().

00443 {
00444    struct cc_callback_helper helper = {.function = function, .args = args, .type = type};
00445    struct cc_core_instance *core_instance;
00446    if ((core_instance = ao2_t_callback(cc_core_instances, flags, cc_agent_callback_helper, &helper,
00447                "Calling provided agent callback function"))) {
00448       struct ast_cc_agent *agent = cc_ref(core_instance->agent, "An outside entity needs the agent");
00449       cc_unref(core_instance, "agent callback done with the core_instance");
00450       return agent;
00451    }
00452    return NULL;
00453 }

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 3539 of file ccss.c.

References CC_ACTIVE, and cc_request_state_change().

Referenced by cc_esc_publish_handler(), generic_agent_devstate_cb(), and sig_pri_handle_cis_subcmds().

03540 {
03541    va_list ap;
03542    int res;
03543 
03544    va_start(ap, debug);
03545    res = cc_request_state_change(CC_ACTIVE, core_id, debug, ap);
03546    va_end(ap);
03547    return res;
03548 }

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 3528 of file ccss.c.

References CC_CALLER_BUSY, and cc_request_state_change().

Referenced by cc_esc_publish_handler(), cc_generic_agent_recall(), sig_pri_handle_cis_subcmds(), and sip_cc_agent_recall().

03529 {
03530    va_list ap;
03531    int res;
03532 
03533    va_start(ap, debug);
03534    res = cc_request_state_change(CC_CALLER_BUSY, core_id, debug, ap);
03535    va_end(ap);
03536    return res;
03537 }

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 3550 of file ccss.c.

References CC_RECALLING, and cc_request_state_change().

Referenced by generic_recall(), get_destination(), and sig_pri_handle_subcmds().

03551 {
03552    va_list ap;
03553    int res;
03554 
03555    va_start(ap, debug);
03556    res = cc_request_state_change(CC_RECALLING, core_id, debug, ap);
03557    va_end(ap);
03558    return res;
03559 }

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 946 of file ccss.c.

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

Referenced by ast_cc_init(), and load_module().

00947 {
00948    struct cc_agent_backend *backend = ast_calloc(1, sizeof(*backend));
00949 
00950    if (!backend) {
00951       return -1;
00952    }
00953 
00954    backend->callbacks = callbacks;
00955    AST_RWLIST_WRLOCK(&cc_agent_backends);
00956    AST_RWLIST_INSERT_TAIL(&cc_agent_backends, backend, next);
00957    AST_RWLIST_UNLOCK(&cc_agent_backends);
00958    return 0;
00959 }

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 3350 of file ccss.c.

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_recall_ds_data::core_id, ast_datastore::data, cc_recall_ds_data::interface_tree, monitor, pbx_builtin_setvar_helper(), recall_ds_info, and str.

Referenced by generic_recall(), handle_request_invite(), and sig_pri_handle_subcmds().

03351 {
03352    struct ast_datastore *recall_datastore;
03353    struct cc_monitor_tree *interface_tree;
03354    struct ast_cc_monitor *monitor;
03355    struct cc_recall_ds_data *recall_data;
03356    struct ast_str *str = ast_str_create(64);
03357    int core_id;
03358 
03359    if (!str) {
03360       return -1;
03361    }
03362 
03363    ast_channel_lock(chan);
03364    if (!(recall_datastore = ast_channel_datastore_find(chan, &recall_ds_info, NULL))) {
03365       ast_channel_unlock(chan);
03366       ast_free(str);
03367       return -1;
03368    }
03369    recall_data = recall_datastore->data;
03370    interface_tree = recall_data->interface_tree;
03371    core_id = recall_data->core_id;
03372    ast_channel_unlock(chan);
03373 
03374    AST_LIST_LOCK(interface_tree);
03375    monitor = AST_LIST_FIRST(interface_tree);
03376    build_cc_interfaces_chanvar(monitor, str);
03377    AST_LIST_UNLOCK(interface_tree);
03378 
03379    pbx_builtin_setvar_helper(chan, "CC_INTERFACES", ast_str_buffer(str));
03380    ast_log_dynamic_level(cc_logger_level, "Core %d: CC_INTERFACES set to %s\n",
03381          core_id, ast_str_buffer(str));
03382 
03383    ast_free(str);
03384    return 0;
03385 }

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 3815 of file ccss.c.

References args, ast_calloc, ast_free, ast_taskprocessor_push(), cc_core_taskprocessor, cc_status_response(), cc_unref(), and find_cc_core_instance().

Referenced by cc_generic_agent_status_request(), sig_pri_handle_cis_subcmds(), and sip_cc_agent_status_request().

03816 {
03817    struct cc_status_response_args *args;
03818    struct cc_core_instance *core_instance;
03819    int res;
03820 
03821    args = ast_calloc(1, sizeof(*args));
03822    if (!args) {
03823       return -1;
03824    }
03825 
03826    core_instance = find_cc_core_instance(core_id);
03827    if (!core_instance) {
03828       ast_free(args);
03829       return -1;
03830    }
03831 
03832    args->core_instance = core_instance;
03833    args->devstate = devstate;
03834 
03835    res = ast_taskprocessor_push(cc_core_taskprocessor, cc_status_response, args);
03836    if (res) {
03837       cc_unref(core_instance, "Unref core instance. ast_taskprocessor_push failed");
03838       ast_free(args);
03839    }
03840    return res;
03841 }

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
Return values:
0 Successfully unregistered
-1 Failure to unregister

Definition at line 961 of file ccss.c.

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, cc_monitor_backend::callbacks, and cc_monitor_backend::next.

Referenced by __unload_module().

00962 {
00963    struct cc_agent_backend *backend;
00964    AST_RWLIST_WRLOCK(&cc_agent_backends);
00965    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&cc_agent_backends, backend, next) {
00966       if (backend->callbacks == callbacks) {
00967          AST_RWLIST_REMOVE_CURRENT(next);
00968          ast_free(backend);
00969          break;
00970       }
00971    }
00972    AST_RWLIST_TRAVERSE_SAFE_END;
00973    AST_RWLIST_UNLOCK(&cc_agent_backends);
00974 }

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 1229 of file ccss.c.

References ast_cc_monitor_failed(), cc_unref(), and monitor.

Referenced by cc_generic_monitor_request_cc(), and sip_cc_monitor_request_cc().

01230 {
01231    struct ast_cc_monitor *monitor = (struct ast_cc_monitor *) data;
01232    int res;
01233    monitor->available_timer_id = -1;
01234    res = ast_cc_monitor_failed(monitor->core_id, monitor->interface->device_name, "Available timer expired for monitor");
01235    cc_unref(monitor, "Unref reference from scheduler\n");
01236    return res;
01237 }

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 3898 of file ccss.c.

References ast_calloc, AST_CONTROL_CC, AST_FRAME_CONTROL, ast_free, AST_MALLOCD_DATA, cc_build_payload(), ast_frame::data, ast_frame::datalen, ast_frame::frametype, ast_frame_subclass::integer, ast_frame::mallocd, ast_frame::ptr, and ast_frame::subclass.

Referenced by ast_queue_cc_frame().

03902 {
03903    struct cc_control_payload *payload = ast_calloc(1, sizeof(*payload));
03904 
03905    if (!payload) {
03906       return -1;
03907    }
03908    if (cc_build_payload(chan, cc_params, monitor_type, device_name, dialstring, service, private_data, payload)) {
03909       /* Something screwed up, we can't make a frame with this */
03910       ast_free(payload);
03911       return -1;
03912    }
03913    frame->frametype = AST_FRAME_CONTROL;
03914    frame->subclass.integer = AST_CONTROL_CC;
03915    frame->data.ptr = payload;
03916    frame->datalen = sizeof(*payload);
03917    frame->mallocd = AST_MALLOCD_DATA;
03918    return 0;
03919 }

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 3954 of file ccss.c.

References AST_CC_CCBS, ast_handle_cc_control_frame(), call_destructor_with_no_monitor(), and cc_build_payload().

Referenced by dial_exec_full().

03956 {
03957    struct cc_control_payload payload;
03958    if (cc_build_payload(inbound, cc_params, monitor_type, device_name, dialstring, AST_CC_CCBS, private_data, &payload)) {
03959       /* Something screwed up. Don't try to handle this payload */
03960       call_destructor_with_no_monitor(monitor_type, private_data);
03961       return;
03962    }
03963    ast_handle_cc_control_frame(inbound, NULL, &payload);
03964 }

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 3921 of file ccss.c.

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_NAME, ast_get_cc_monitor_policy(), ast_handle_cc_control_frame(), cc_build_payload(), and ast_channel::hangupcause.

Referenced by dial_exec_full().

03922 {
03923    char device_name[AST_CHANNEL_NAME];
03924    struct cc_control_payload payload;
03925    struct ast_cc_config_params *cc_params;
03926 
03927    if (outgoing->hangupcause != AST_CAUSE_BUSY && outgoing->hangupcause != AST_CAUSE_CONGESTION) {
03928       /* It doesn't make sense to try to offer CCBS to the caller if the reason for ast_call
03929        * failing is something other than busy or congestion
03930        */
03931       return;
03932    }
03933 
03934    cc_params = ast_channel_get_cc_config_params(outgoing);
03935    if (!cc_params) {
03936       return;
03937    }
03938    if (ast_get_cc_monitor_policy(cc_params) != AST_CC_MONITOR_GENERIC) {
03939       /* This sort of CCBS only works if using generic CC. For native, we would end up sending
03940        * a CC request for a non-existent call. The far end will reject this every time
03941        */
03942       return;
03943    }
03944 
03945    ast_channel_get_device_name(outgoing, device_name, sizeof(device_name));
03946    if (cc_build_payload(outgoing, cc_params, AST_CC_GENERIC_MONITOR_TYPE, device_name,
03947       dialstring, AST_CC_CCBS, NULL, &payload)) {
03948       /* Something screwed up, we can't make a frame with this */
03949       return;
03950    }
03951    ast_handle_cc_control_frame(incoming, outgoing, &payload);
03952 }

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 2136 of file ccss.c.

References AST_CC_AGENT_NEVER, ast_channel_datastore_find(), ast_channel_get_cc_config_params(), ast_channel_lock, ast_channel_unlock, 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_ref(), cc_unref(), ast_channel::context, dialed_cc_interfaces::core_id, ast_datastore::data, dialed_cc_interfaces::dial_parent_id, dialed_cc_interfaces_info, ast_channel::exten, dialed_cc_interfaces::ignore, dialed_cc_interfaces::interface_tree, ast_channel::macrocontext, ast_channel::macroexten, monitor, ast_channel::name, cc_monitor_backend::next, and S_OR.

Referenced by dial_exec_full().

02137 {
02138    /* There are three situations to deal with here:
02139     *
02140     * 1. The channel does not have a dialed_cc_interfaces datastore on
02141     * it. This means that this is the first time that Dial has
02142     * been called. We need to create/initialize the datastore.
02143     *
02144     * 2. The channel does have a cc_interface datastore on it and
02145     * the "ignore" indicator is 0. This means that a Local channel
02146     * was called by a "parent" dial. We can check the datastore's
02147     * parent field to see who the root of this particular dial tree
02148     * is.
02149     *
02150     * 3. The channel does have a cc_interface datastore on it and
02151     * the "ignore" indicator is 1. This means that a second Dial call
02152     * is being made from an extension. In this case, we do not
02153     * want to make any additions/modifications to the datastore. We
02154     * will instead set a flag to indicate that CCSS is completely
02155     * disabled for this Dial attempt.
02156     */
02157 
02158    struct ast_datastore *cc_interfaces_datastore;
02159    struct dialed_cc_interfaces *interfaces;
02160    struct ast_cc_monitor *monitor;
02161    struct ast_cc_config_params *cc_params;
02162 
02163    ast_channel_lock(chan);
02164 
02165    cc_params = ast_channel_get_cc_config_params(chan);
02166    if (!cc_params) {
02167       ast_channel_unlock(chan);
02168       return -1;
02169    }
02170    if (ast_get_cc_agent_policy(cc_params) == AST_CC_AGENT_NEVER) {
02171       /* We can't offer CC to this caller anyway, so don't bother with CC on this call
02172        */
02173       *ignore_cc = 1;
02174       ast_channel_unlock(chan);
02175       ast_log_dynamic_level(cc_logger_level, "Agent policy for %s is 'never'. CC not possible\n", chan->name);
02176       return 0;
02177    }
02178 
02179    if (!(cc_interfaces_datastore = ast_channel_datastore_find(chan, &dialed_cc_interfaces_info, NULL))) {
02180       /* Situation 1 has occurred */
02181       ast_channel_unlock(chan);
02182       return cc_interfaces_datastore_init(chan);
02183    }
02184    interfaces = cc_interfaces_datastore->data;
02185    ast_channel_unlock(chan);
02186 
02187    if (interfaces->ignore) {
02188       /* Situation 3 has occurred */
02189       *ignore_cc = 1;
02190       ast_log_dynamic_level(cc_logger_level, "Datastore is present with ignore flag set. Ignoring CC offers on this call\n");
02191       return 0;
02192    }
02193 
02194    /* Situation 2 has occurred */
02195    if (!(monitor = cc_extension_monitor_init(S_OR(chan->macroexten, chan->exten),
02196          S_OR(chan->macrocontext, chan->context), interfaces->dial_parent_id))) {
02197       return -1;
02198    }
02199    monitor->core_id = interfaces->core_id;
02200    AST_LIST_LOCK(interfaces->interface_tree);
02201    cc_ref(monitor, "monitor tree's reference to the monitor");
02202    AST_LIST_INSERT_TAIL(interfaces->interface_tree, monitor, next);
02203    AST_LIST_UNLOCK(interfaces->interface_tree);
02204    interfaces->dial_parent_id = monitor->id;
02205    cc_unref(monitor, "Unref monitor's allocation reference");
02206    return 0;
02207 }

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:
Always 0, I guess.

Definition at line 3966 of file ccss.c.

References ast_get_channel_tech(), and ast_channel_tech::cc_callback.

Referenced by dial_exec_full().

03967 {
03968    const struct ast_channel_tech *chantech = ast_get_channel_tech(tech);
03969 
03970    if (chantech && chantech->cc_callback) {
03971       chantech->cc_callback(inbound, dest, callback);
03972    }
03973 
03974    return 0;
03975 }

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 3561 of file ccss.c.

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, cc_recall_ds_data::ignore, cc_recall_ds_data::nested, and recall_ds_info.

03562 {
03563    struct ast_datastore *recall_datastore;
03564    struct cc_recall_ds_data *recall_data;
03565    int core_id;
03566    va_list ap;
03567    int res;
03568 
03569    ast_channel_lock(chan);
03570    if (!(recall_datastore = ast_channel_datastore_find(chan, &recall_ds_info, NULL))) {
03571       /* Silly! Why did you call this function if there's no recall DS? */
03572       ast_channel_unlock(chan);
03573       return -1;
03574    }
03575    recall_data = recall_datastore->data;
03576    if (recall_data->nested || recall_data->ignore) {
03577       /* If this is being called from a nested Dial, it is too
03578        * early to determine if the recall has actually completed.
03579        * The outermost dial is the only one with the authority to
03580        * declare the recall to be complete.
03581        *
03582        * Similarly, if this function has been called when the
03583        * recall has progressed beyond the first dial, this is not
03584        * a legitimate time to declare the recall to be done. In fact,
03585        * that should have been done already.
03586        */
03587       ast_channel_unlock(chan);
03588       return -1;
03589    }
03590    core_id = recall_data->core_id;
03591    ast_channel_unlock(chan);
03592    va_start(ap, debug);
03593    res = cc_request_state_change(CC_COMPLETE, core_id, debug, ap);
03594    va_end(ap);
03595    return res;
03596 }

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
Return values:
void 

Definition at line 575 of file ccss.c.

References ast_free.

Referenced by __sip_destroy(), agent_destroy(), ast_channel_cc_params_init(), cc_interface_destroy(), channel_cc_params_destroy(), destroy_dahdi_pvt(), setup_dahdi(), and sip_destroy_peer().

00576 {
00577    ast_free(params);
00578 }

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
Returns:
Nothing

Definition at line 737 of file ccss.c.

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

00738 {
00739    *dest = *src;
00740 }

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.
Returns:
Nothing

Definition at line 554 of file ccss.c.

References cc_default_params.

Referenced by __ast_cc_config_params_init().

00555 {
00556    *params = cc_default_params;
00557 }

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
Return values:
void 

Definition at line 1725 of file ccss.c.

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, dialed_cc_interfaces::dial_parent_id, dialed_cc_interfaces_info, id, dialed_cc_interfaces::interface_tree, monitor, and cc_monitor_backend::next.

Referenced by dial_exec_full().

01726 {
01727    struct ast_datastore *cc_datastore;
01728    struct dialed_cc_interfaces *cc_interfaces;
01729    struct ast_cc_monitor *monitor;
01730    struct extension_monitor_pvt *extension_pvt;
01731    struct extension_child_dialstring *child_dialstring;
01732    struct cc_monitor_tree *interface_tree;
01733    int id;
01734 
01735    ast_channel_lock(incoming);
01736    if (!(cc_datastore = ast_channel_datastore_find(incoming, &dialed_cc_interfaces_info, NULL))) {
01737       ast_channel_unlock(incoming);
01738       return;
01739    }
01740 
01741    cc_interfaces = cc_datastore->data;
01742    interface_tree = cc_interfaces->interface_tree;
01743    id = cc_interfaces->dial_parent_id;
01744    ast_channel_unlock(incoming);
01745 
01746    AST_LIST_LOCK(interface_tree);
01747    AST_LIST_TRAVERSE(interface_tree, monitor, next) {
01748       if (monitor->id == id) {
01749          break;
01750       }
01751    }
01752 
01753    if (!monitor) {
01754       AST_LIST_UNLOCK(interface_tree);
01755       return;
01756    }
01757 
01758    extension_pvt = monitor->private_data;
01759    if (!(child_dialstring = ast_calloc(1, sizeof(*child_dialstring)))) {
01760       AST_LIST_UNLOCK(interface_tree);
01761       return;
01762    }
01763    ast_copy_string(child_dialstring->original_dialstring, dialstring, sizeof(child_dialstring->original_dialstring));
01764    ast_copy_string(child_dialstring->device_name, device_name, sizeof(child_dialstring->device_name));
01765    child_dialstring->is_valid = 1;
01766    AST_LIST_INSERT_TAIL(&extension_pvt->child_dialstrings, child_dialstring, next);
01767    AST_LIST_UNLOCK(interface_tree);
01768 }

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 3598 of file ccss.c.

References CC_FAILED, and cc_request_state_change().

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

03599 {
03600    va_list ap;
03601    int res;
03602 
03603    va_start(ap, debug);
03604    res = cc_request_state_change(CC_FAILED, core_id, debug, ap);
03605    va_end(ap);
03606    return res;
03607 }

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 2214 of file ccss.c.

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

Referenced by sig_pri_cc_available(), sig_pri_cc_generic_check(), and sip_handle_cc().

02215 {
02216    struct ast_datastore *datastore;
02217    struct dialed_cc_interfaces *cc_interfaces;
02218    int core_id_return;
02219 
02220    ast_channel_lock(chan);
02221    if (!(datastore = ast_channel_datastore_find(chan, &dialed_cc_interfaces_info, NULL))) {
02222       ast_channel_unlock(chan);
02223       return -1;
02224    }
02225 
02226    cc_interfaces = datastore->data;
02227    core_id_return = cc_interfaces->ignore ? -1 : cc_interfaces->core_id;
02228    ast_channel_unlock(chan);
02229    return core_id_return;
02230 
02231 }

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 3238 of file ccss.c.

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

Referenced by sig_pri_call(), sig_pri_cc_generic_check(), and sip_call().

03239 {
03240    struct cc_core_instance *core_instance = find_cc_core_instance(core_id);
03241    struct ast_cc_monitor *monitor_iter;
03242 
03243    if (!core_instance) {
03244       return NULL;
03245    }
03246 
03247    AST_LIST_LOCK(core_instance->monitors);
03248    AST_LIST_TRAVERSE(core_instance->monitors, monitor_iter, next) {
03249       if (!strcmp(monitor_iter->interface->device_name, device_name)) {
03250          /* Found a monitor. */
03251          cc_ref(monitor_iter, "Hand the requester of the monitor a reference");
03252          break;
03253       }
03254    }
03255    AST_LIST_UNLOCK(core_instance->monitors);
03256    cc_unref(core_instance, "Done with core instance ref in ast_cc_get_monitor_by_recall_core_id");
03257    return monitor_iter;
03258 }

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 641 of file ccss.c.

References agent_policy_to_str(), ast_copy_string(), ast_get_cc_agent_dialstring(), ast_get_cc_agent_policy(), ast_get_cc_callback_macro(), 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(), LOG_WARNING, monitor_policy_to_str(), and value.

Referenced by acf_cc_read().

00643 {
00644    const char *value = NULL;
00645 
00646    if (!strcasecmp(name, "cc_callback_macro")) {
00647       value = ast_get_cc_callback_macro(params);
00648    } else if (!strcasecmp(name, "cc_agent_policy")) {
00649       value = agent_policy_to_str(ast_get_cc_agent_policy(params));
00650    } else if (!strcasecmp(name, "cc_monitor_policy")) {
00651       value = monitor_policy_to_str(ast_get_cc_monitor_policy(params));
00652    } else if (!strcasecmp(name, "cc_agent_dialstring")) {
00653       value = ast_get_cc_agent_dialstring(params);
00654    }
00655    if (value) {
00656       ast_copy_string(buf, value, buf_len);
00657       return 0;
00658    }
00659 
00660    /* The rest of these are all ints of some sort and require some
00661     * snprintf-itude
00662     */
00663 
00664    if (!strcasecmp(name, "cc_offer_timer")) {
00665       snprintf(buf, buf_len, "%u", ast_get_cc_offer_timer(params));
00666    } else if (!strcasecmp(name, "ccnr_available_timer")) {
00667       snprintf(buf, buf_len, "%u", ast_get_ccnr_available_timer(params));
00668    } else if (!strcasecmp(name, "ccbs_available_timer")) {
00669       snprintf(buf, buf_len, "%u", ast_get_ccbs_available_timer(params));
00670    } else if (!strcasecmp(name, "cc_max_agents")) {
00671       snprintf(buf, buf_len, "%u", ast_get_cc_max_agents(params));
00672    } else if (!strcasecmp(name, "cc_max_monitors")) {
00673       snprintf(buf, buf_len, "%u", ast_get_cc_max_monitors(params));
00674    } else if (!strcasecmp(name, "cc_recall_timer")) {
00675       snprintf(buf, buf_len, "%u", ast_get_cc_recall_timer(params));
00676    } else {
00677       ast_log(LOG_WARNING, "%s is not a valid CC parameter. Ignoring.\n", name);
00678       return -1;
00679    }
00680 
00681    return 0;
00682 }

int ast_cc_init ( void   ) 

Initialize CCSS.

Since:
1.8
Performs startup routines necessary for CC operation.

Return values:
0 Success
nonzero Failure

Definition at line 4298 of file ccss.c.

References ao2_t_container_alloc, ARRAY_LEN, ast_cc_agent_register(), ast_cc_monitor_register(), ast_cli_register_multiple(), ast_logger_register_level(), ast_register_application2(), ast_sched_thread_create(), ast_taskprocessor_get(), cc_cli, cc_core_instance_cmp_fn(), cc_core_instance_hash_fn(), cc_core_instances, cc_core_taskprocessor, cc_sched_thread, cccancel_exec(), ccreq_exec(), generic_agent_callbacks, generic_monitor_cbs, generic_monitor_cmp_fn(), generic_monitor_hash_fn(), generic_monitors, initialize_cc_max_requests(), and TPS_REF_DEFAULT.

Referenced by main().

04299 {
04300    int res;
04301 
04302    if (!(cc_core_instances = ao2_t_container_alloc(CC_CORE_INSTANCES_BUCKETS,
04303                cc_core_instance_hash_fn, cc_core_instance_cmp_fn,
04304                "Create core instance container"))) {
04305       return -1;
04306    }
04307    if (!(generic_monitors = ao2_t_container_alloc(CC_CORE_INSTANCES_BUCKETS,
04308                generic_monitor_hash_fn, generic_monitor_cmp_fn,
04309                "Create generic monitor container"))) {
04310       return -1;
04311    }
04312    if (!(cc_core_taskprocessor = ast_taskprocessor_get("CCSS core", TPS_REF_DEFAULT))) {
04313       return -1;
04314    }
04315    if (!(cc_sched_thread = ast_sched_thread_create())) {
04316       return -1;
04317    }
04318    res = ast_register_application2(ccreq_app, ccreq_exec, NULL, NULL, NULL);
04319    res |= ast_register_application2(cccancel_app, cccancel_exec, NULL, NULL, NULL);
04320    res |= ast_cc_monitor_register(&generic_monitor_cbs);
04321    res |= ast_cc_agent_register(&generic_agent_callbacks);
04322    ast_cli_register_multiple(cc_cli, ARRAY_LEN(cc_cli));
04323    cc_logger_level = ast_logger_register_level(CC_LOGGER_LEVEL_NAME);
04324    dialed_cc_interface_counter = 1;
04325    initialize_cc_max_requests();
04326    return res;
04327 }

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 723 of file ccss.c.

Referenced by build_peer().

00724 {
00725    return (!strcasecmp(name, "cc_agent_policy") ||
00726             !strcasecmp(name, "cc_monitor_policy") ||
00727             !strcasecmp(name, "cc_offer_timer") ||
00728             !strcasecmp(name, "ccnr_available_timer") ||
00729             !strcasecmp(name, "ccbs_available_timer") ||
00730             !strcasecmp(name, "cc_max_agents") ||
00731             !strcasecmp(name, "cc_max_monitors") ||
00732             !strcasecmp(name, "cc_callback_macro") ||
00733             !strcasecmp(name, "cc_agent_dialstring") ||
00734             !strcasecmp(name, "cc_recall_timer"));
00735 }

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 3157 of file ccss.c.

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(), 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, cc_monitor_backend::next, and recall_ds_info.

Referenced by cc_core_init_instance(), sig_pri_call(), sip_call(), and wait_for_answer().

03158 {
03159    struct ast_datastore *recall_datastore;
03160    struct cc_recall_ds_data *recall_data;
03161    struct cc_monitor_tree *interface_tree;
03162    char device_name[AST_CHANNEL_NAME];
03163    struct ast_cc_monitor *device_monitor;
03164    int core_id_candidate;
03165 
03166    ast_assert(core_id != NULL);
03167 
03168    *core_id = -1;
03169 
03170    ast_channel_lock(chan);
03171    if (!(recall_datastore = ast_channel_datastore_find(chan, &recall_ds_info, NULL))) {
03172       /* Obviously not a recall if the datastore isn't present */
03173       ast_channel_unlock(chan);
03174       return 0;
03175    }
03176 
03177    recall_data = recall_datastore->data;
03178 
03179    if (recall_data->ignore) {
03180       /* Though this is a recall, the call to this particular interface is not part of the
03181        * recall either because this is a call forward or because this is not the first
03182        * invocation of Dial during this call
03183        */
03184       ast_channel_unlock(chan);
03185       return 0;
03186    }
03187 
03188    if (!recall_data->nested) {
03189       /* If the nested flag is not set, then this means that
03190        * the channel passed to this function is the caller making
03191        * the recall. This means that we shouldn't look through
03192        * the monitor tree for the channel because it shouldn't be
03193        * there. However, this is a recall though, so return true.
03194        */
03195       *core_id = recall_data->core_id;
03196       ast_channel_unlock(chan);
03197       return 1;
03198    }
03199 
03200    if (ast_strlen_zero(monitor_type)) {
03201       /* If someone passed a NULL or empty monitor type, then it is clear
03202        * the channel they passed in was an incoming channel, and so searching
03203        * the list of dialed interfaces is not going to be helpful. Just return
03204        * false immediately.
03205        */
03206       ast_channel_unlock(chan);
03207       return 0;
03208    }
03209 
03210    interface_tree = recall_data->interface_tree;
03211    ast_channel_get_device_name(chan, device_name, sizeof(device_name));
03212    /* We grab the value of the recall_data->core_id so that we
03213     * can unlock the channel before we start looking through the
03214     * interface list. That way we don't have to worry about a possible
03215     * clash between the channel lock and the monitor tree lock.
03216     */
03217    core_id_candidate = recall_data->core_id;
03218    ast_channel_unlock(chan);
03219 
03220    /*
03221     * Now we need to find out if the channel device name
03222     * is in the list of interfaces in the called tree.
03223     */
03224    AST_LIST_LOCK(interface_tree);
03225    AST_LIST_TRAVERSE(interface_tree, device_monitor, next) {
03226       if (!strcmp(device_monitor->interface->device_name, device_name) &&
03227             !strcmp(device_monitor->interface->monitor_type, monitor_type)) {
03228          /* BOOM! Device is in the tree! We have a winner! */
03229          *core_id = core_id_candidate;
03230          AST_LIST_UNLOCK(interface_tree);
03231          return 1;
03232       }
03233    }
03234    AST_LIST_UNLOCK(interface_tree);
03235    return 0;
03236 }

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.
Parameters:
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 3517 of file ccss.c.

References CC_CALLEE_READY, and cc_request_state_change().

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

03518 {
03519    va_list ap;
03520    int res;
03521 
03522    va_start(ap, debug);
03523    res = cc_request_state_change(CC_CALLEE_READY, core_id, debug, ap);
03524    va_end(ap);
03525    return res;
03526 }

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 4090 of file ccss.c.

References ao2_t_callback, ast_log_dynamic_level, cc_core_instances, count_monitors_cb_data::count, count_monitors_cb(), count_monitors_cb_data::device_name, and OBJ_NODATA.

Referenced by ast_queue_cc_frame().

04091 {
04092    struct count_monitors_cb_data data = {.device_name = name, .monitor_type = type,};
04093 
04094    ao2_t_callback(cc_core_instances, OBJ_NODATA, count_monitors_cb, &data, "Counting agents");
04095    ast_log_dynamic_level(cc_logger_level, "Counted %d monitors\n", data.count);
04096    return data.count;
04097 }

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
Returns:
void

Definition at line 3663 of file ccss.c.

References ast_calloc, ast_free, ast_strdup, ast_taskprocessor_push(), ast_vasprintf, cc_core_taskprocessor, and cc_monitor_failed().

Referenced by ast_cc_available_timer_expire(), cc_handle_publish_error(), handle_response_subscribe(), sig_pri_cc_link_canceled(), and sig_pri_handle_cis_subcmds().

03664 {
03665    struct ast_cc_monitor_failure_data *failure_data;
03666    int res;
03667    va_list ap;
03668 
03669    if (!(failure_data = ast_calloc(1, sizeof(*failure_data)))) {
03670       return -1;
03671    }
03672 
03673    if (!(failure_data->device_name = ast_strdup(monitor_name))) {
03674       ast_free(failure_data);
03675       return -1;
03676    }
03677 
03678    va_start(ap, debug);
03679    if (ast_vasprintf(&failure_data->debug, debug, ap) == -1) {
03680       va_end(ap);
03681       ast_free((char *)failure_data->device_name);
03682       ast_free(failure_data);
03683       return -1;
03684    }
03685    va_end(ap);
03686 
03687    failure_data->core_id = core_id;
03688 
03689    res = ast_taskprocessor_push(cc_core_taskprocessor, cc_monitor_failed, failure_data);
03690    if (res) {
03691       ast_free((char *)failure_data->device_name);
03692       ast_free((char *)failure_data->debug);
03693       ast_free(failure_data);
03694    }
03695    return res;
03696 }

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 3773 of file ccss.c.

References ast_taskprocessor_push(), cc_core_taskprocessor, cc_party_b_free(), cc_unref(), and find_cc_core_instance().

Referenced by sig_pri_handle_cis_subcmds().

03774 {
03775    int res;
03776    struct cc_core_instance *core_instance = find_cc_core_instance(core_id);
03777 
03778    if (!core_instance) {
03779       return -1;
03780    }
03781 
03782    res = ast_taskprocessor_push(cc_core_taskprocessor, cc_party_b_free, core_instance);
03783    if (res) {
03784       cc_unref(core_instance, "Unref core instance. ast_taskprocessor_push failed");
03785    }
03786    return res;
03787 }

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 891 of file ccss.c.

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

Referenced by ast_cc_init(), and load_module().

00892 {
00893    struct cc_monitor_backend *backend = ast_calloc(1, sizeof(*backend));
00894 
00895    if (!backend) {
00896       return -1;
00897    }
00898 
00899    backend->callbacks = callbacks;
00900 
00901    AST_RWLIST_WRLOCK(&cc_monitor_backends);
00902    AST_RWLIST_INSERT_TAIL(&cc_monitor_backends, backend, next);
00903    AST_RWLIST_UNLOCK(&cc_monitor_backends);
00904    return 0;
00905 }

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 3506 of file ccss.c.

References CC_ACTIVE, and cc_request_state_change().

Referenced by cc_generic_monitor_request_cc(), cc_stop_ringing(), handle_cc_notify(), and sig_pri_handle_cis_subcmds().

03507 {
03508    va_list ap;
03509    int res;
03510 
03511    va_start(ap, debug);
03512    res = cc_request_state_change(CC_ACTIVE, core_id, debug, ap);
03513    va_end(ap);
03514    return res;
03515 }

int ast_cc_monitor_status_request ( int  core_id  ) 

Request the status of a caller or callers.

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 3708 of file ccss.c.

References ast_taskprocessor_push(), cc_core_taskprocessor, cc_status_request(), cc_unref(), and find_cc_core_instance().

Referenced by sig_pri_handle_cis_subcmds().

03709 {
03710    int res;
03711    struct cc_core_instance *core_instance = find_cc_core_instance(core_id);
03712 
03713    if (!core_instance) {
03714       return -1;
03715    }
03716 
03717    res = ast_taskprocessor_push(cc_core_taskprocessor, cc_status_request, core_instance);
03718    if (res) {
03719       cc_unref(core_instance, "Unref core instance. ast_taskprocessor_push failed");
03720    }
03721    return res;
03722 }

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 3745 of file ccss.c.

References ast_taskprocessor_push(), cc_core_taskprocessor, cc_stop_ringing(), cc_unref(), and find_cc_core_instance().

Referenced by sig_pri_handle_cis_subcmds().

03746 {
03747    int res;
03748    struct cc_core_instance *core_instance = find_cc_core_instance(core_id);
03749 
03750    if (!core_instance) {
03751       return -1;
03752    }
03753 
03754    res = ast_taskprocessor_push(cc_core_taskprocessor, cc_stop_ringing, core_instance);
03755    if (res) {
03756       cc_unref(core_instance, "Unref core instance. ast_taskprocessor_push failed");
03757    }
03758    return res;
03759 }

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
Return values:
0 Successfully unregistered
-1 Failure to unregister

Definition at line 924 of file ccss.c.

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, and cc_monitor_backend::next.

Referenced by __unload_module().

00925 {
00926    struct cc_monitor_backend *backend;
00927    AST_RWLIST_WRLOCK(&cc_monitor_backends);
00928    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&cc_monitor_backends, backend, next) {
00929       if (backend->callbacks == callbacks) {
00930          AST_RWLIST_REMOVE_CURRENT(next);
00931          ast_free(backend);
00932          break;
00933       }
00934    }
00935    AST_RWLIST_TRAVERSE_SAFE_END;
00936    AST_RWLIST_UNLOCK(&cc_monitor_backends);
00937 }

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 3470 of file ccss.c.

References ast_channel_datastore_find(), ast_channel_lock, ast_channel_unlock, cc_offer(), cc_recall_ds_data::core_id, dialed_cc_interfaces::core_id, ast_datastore::data, dialed_cc_interfaces_info, dialed_cc_interfaces::is_original_caller, and ast_channel::name.

Referenced by ast_hangup().

03471 {
03472    int core_id;
03473    int res = -1;
03474    struct ast_datastore *datastore;
03475    struct dialed_cc_interfaces *cc_interfaces;
03476    char cc_is_offerable;
03477 
03478    ast_channel_lock(caller_chan);
03479    if (!(datastore = ast_channel_datastore_find(caller_chan, &dialed_cc_interfaces_info, NULL))) {
03480       ast_channel_unlock(caller_chan);
03481       return res;
03482    }
03483 
03484    cc_interfaces = datastore->data;
03485    cc_is_offerable = cc_interfaces->is_original_caller;
03486    core_id = cc_interfaces->core_id;
03487    ast_channel_unlock(caller_chan);
03488 
03489    if (cc_is_offerable) {
03490       res = cc_offer(core_id, "CC offered to caller %s", caller_chan->name);
03491    }
03492    return res;
03493 }

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 2209 of file ccss.c.

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

02210 {
02211    return cc_request_count < global_cc_max_requests;
02212 }

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 684 of file ccss.c.

References ast_log(), ast_set_cc_agent_dialstring(), ast_set_cc_agent_policy(), ast_set_cc_callback_macro(), 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, str_to_agent_policy(), and str_to_monitor_policy().

Referenced by acf_cc_write(), and build_peer().

00686 {
00687    unsigned int value_as_uint;
00688    if (!strcasecmp(name, "cc_agent_policy")) {
00689       return ast_set_cc_agent_policy(params, str_to_agent_policy(value));
00690    } else if (!strcasecmp(name, "cc_monitor_policy")) {
00691       return ast_set_cc_monitor_policy(params, str_to_monitor_policy(value));
00692    } else if (!strcasecmp(name, "cc_agent_dialstring")) {
00693       ast_set_cc_agent_dialstring(params, value);
00694    } else if (!strcasecmp(name, "cc_callback_macro")) {
00695       ast_set_cc_callback_macro(params, value);
00696       return 0;
00697    }
00698 
00699    if (!sscanf(value, "%30u", &value_as_uint) == 1) {
00700       return -1;
00701    }
00702 
00703    if (!strcasecmp(name, "cc_offer_timer")) {
00704       ast_set_cc_offer_timer(params, value_as_uint);
00705    } else if (!strcasecmp(name, "ccnr_available_timer")) {
00706       ast_set_ccnr_available_timer(params, value_as_uint);
00707    } else if (!strcasecmp(name, "ccbs_available_timer")) {
00708       ast_set_ccbs_available_timer(params, value_as_uint);
00709    } else if (!strcasecmp(name, "cc_max_agents")) {
00710       ast_set_cc_max_agents(params, value_as_uint);
00711    } else if (!strcasecmp(name, "cc_max_monitors")) {
00712       ast_set_cc_max_monitors(params, value_as_uint);
00713    } else if (!strcasecmp(name, "cc_recall_timer")) {
00714       ast_set_cc_recall_timer(params, value_as_uint);
00715    } else {
00716       ast_log(LOG_WARNING, "%s is not a valid CC parameter. Ignoring.\n", name);
00717       return -1;
00718    }
00719 
00720    return 0;
00721 }

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 836 of file ccss.c.

References config.

Referenced by ast_cc_get_param(), and generic_recall().

00837 {
00838    return config->cc_agent_dialstring;
00839 }

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 742 of file ccss.c.

References config.

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

00743 {
00744    return config->cc_agent_policy;
00745 }

const char* ast_get_cc_callback_macro ( struct ast_cc_config_params config  ) 

Get the name of the callback_macro.

Since:
1.8
Parameters:
config The configuration to retrieve the callback_macro from
Returns:
The callback_macro name

Definition at line 870 of file ccss.c.

References config.

Referenced by ast_cc_get_param(), and generic_recall().

00871 {
00872    return config->cc_callback_macro;
00873 }

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 850 of file ccss.c.

References config.

Referenced by ast_cc_get_param(), and cc_core_init_instance().

00851 {
00852    return config->cc_max_agents;
00853 }

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 860 of file ccss.c.

References config.

Referenced by ast_cc_get_param(), and ast_queue_cc_frame().

00861 {
00862    return config->cc_max_monitors;
00863 }

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 759 of file ccss.c.

References config.

Referenced by analog_call(), ast_cc_call_failed(), ast_cc_get_param(), dahdi_cc_callback(), sig_pri_cc_available(), sig_pri_cc_generic_check(), and sip_handle_cc().

00760 {
00761    return config->cc_monitor_policy;
00762 }

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 776 of file ccss.c.

References config.

Referenced by ast_cc_get_param(), cc_generic_agent_start_offer_timer(), and sip_cc_agent_start_offer_timer().

00777 {
00778    return config->cc_offer_timer;
00779 }

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 806 of file ccss.c.

References config.

Referenced by ast_cc_get_param(), and generic_recall().

00807 {
00808    return config->cc_recall_timer;
00809 }

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 821 of file ccss.c.

References config.

Referenced by ast_cc_get_param(), cc_generic_monitor_request_cc(), and sip_cc_monitor_request_cc().

00822 {
00823    return config->ccbs_available_timer;
00824 }

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 791 of file ccss.c.

References config.

Referenced by ast_cc_get_param(), cc_generic_monitor_request_cc(), and sip_cc_monitor_request_cc().

00792 {
00793    return config->ccnr_available_timer;
00794 }

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

Properly react to a CC control frame.

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 2038 of file ccss.c.

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_ref(), cc_service_to_string(), cc_unref(), dialed_cc_interfaces::core_id, cc_core_instance::core_id, ast_datastore::data, cc_control_payload::device_name, dialed_cc_interfaces_info, ast_cc_monitor::dialstring, cc_control_payload::dialstring, EVENT_FLAG_CC, find_cc_core_instance(), dialed_cc_interfaces::ignore, dialed_cc_interfaces::interface_tree, dialed_cc_interfaces::is_original_caller, LOG_WARNING, manager_event, monitor, cc_control_payload::monitor_type, cc_monitor_backend::next, cc_control_payload::private_data, and cc_control_payload::service.

Referenced by ast_cc_busy_interface(), and ast_cc_call_failed().

02039 {
02040    char *device_name;
02041    char *dialstring;
02042    struct ast_cc_monitor *monitor;
02043    struct ast_datastore *cc_datastore;
02044    struct dialed_cc_interfaces *cc_interfaces;
02045    struct cc_control_payload *cc_data = frame_data;
02046    struct cc_core_instance *core_instance;
02047 
02048    device_name = cc_data->device_name;
02049    dialstring = cc_data->dialstring;
02050 
02051    ast_channel_lock(inbound);
02052    if (!(cc_datastore = ast_channel_datastore_find(inbound, &dialed_cc_interfaces_info, NULL))) {
02053       ast_log(LOG_WARNING, "Unable to retrieve CC datastore while processing CC frame from '%s'. CC services will be unavailable.\n", device_name);
02054       ast_channel_unlock(inbound);
02055       call_destructor_with_no_monitor(cc_data->monitor_type, cc_data->private_data);
02056       return;
02057    }
02058 
02059    cc_interfaces = cc_datastore->data;
02060 
02061    if (cc_interfaces->ignore) {
02062       ast_channel_unlock(inbound);
02063       call_destructor_with_no_monitor(cc_data->monitor_type, cc_data->private_data);
02064       return;
02065    }
02066 
02067    if (!cc_interfaces->is_original_caller) {
02068       /* If the is_original_caller is not set on the *inbound* channel, then
02069        * it must be a local channel. As such, we do not want to create a core instance
02070        * or an agent for the local channel. Instead, we want to pass this along to the
02071        * other side of the local channel so that the original caller can benefit.
02072        */
02073       ast_channel_unlock(inbound);
02074       ast_indicate_data(inbound, AST_CONTROL_CC, cc_data, sizeof(*cc_data));
02075       return;
02076    }
02077 
02078    core_instance = find_cc_core_instance(cc_interfaces->core_id);
02079    if (!core_instance) {
02080       core_instance = cc_core_init_instance(inbound, cc_interfaces->interface_tree,
02081          cc_interfaces->core_id, cc_data);
02082       if (!core_instance) {
02083          cc_interfaces->ignore = 1;
02084          ast_channel_unlock(inbound);
02085          call_destructor_with_no_monitor(cc_data->monitor_type, cc_data->private_data);
02086          return;
02087       }
02088    }
02089 
02090    ast_channel_unlock(inbound);
02091 
02092    /* Yeah this kind of sucks, but luckily most people
02093     * aren't dialing thousands of interfaces on every call
02094     *
02095     * This traversal helps us to not create duplicate monitors in
02096     * case a device queues multiple CC control frames.
02097     */
02098    AST_LIST_LOCK(cc_interfaces->interface_tree);
02099    AST_LIST_TRAVERSE(cc_interfaces->interface_tree, monitor, next) {
02100       if (!strcmp(monitor->interface->device_name, device_name)) {
02101          ast_log_dynamic_level(cc_logger_level, "Core %d: Device %s sent us multiple CC control frames. Ignoring those beyond the first.\n",
02102                core_instance->core_id, device_name);
02103          AST_LIST_UNLOCK(cc_interfaces->interface_tree);
02104          cc_unref(core_instance, "Returning early from ast_handle_cc_control_frame. Unref core_instance");
02105          call_destructor_with_no_monitor(cc_data->monitor_type, cc_data->private_data);
02106          return;
02107       }
02108    }
02109    AST_LIST_UNLOCK(cc_interfaces->interface_tree);
02110 
02111    if (!(monitor = cc_device_monitor_init(device_name, dialstring, cc_data, core_instance->core_id))) {
02112       ast_log(LOG_WARNING, "Unable to create CC device interface for '%s'. CC services will be unavailable on this interface.\n", device_name);
02113       cc_unref(core_instance, "Returning early from ast_handle_cc_control_frame. Unref core_instance");
02114       call_destructor_with_no_monitor(cc_data->monitor_type, cc_data->private_data);
02115       return;
02116    }
02117 
02118    AST_LIST_LOCK(cc_interfaces->interface_tree);
02119    cc_ref(monitor, "monitor tree's reference to the monitor");
02120    AST_LIST_INSERT_TAIL(cc_interfaces->interface_tree, monitor, next);
02121    AST_LIST_UNLOCK(cc_interfaces->interface_tree);
02122 
02123    cc_extension_monitor_change_is_valid(core_instance, monitor->parent_id, monitor->interface->device_name, 0);
02124 
02125    manager_event(EVENT_FLAG_CC, "CCAvailable",
02126       "CoreID: %d\r\n"
02127       "Callee: %s\r\n"
02128       "Service: %s\r\n",
02129       cc_interfaces->core_id, device_name, cc_service_to_string(cc_data->service)
02130    );
02131 
02132    cc_unref(core_instance, "Done with core_instance after handling CC control frame");
02133    cc_unref(monitor, "Unref reference from allocating monitor");
02134 }

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.
Return values:
void 

Definition at line 3439 of file ccss.c.

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, and recall_ds_info.

Referenced by dial_exec_full(), and do_forward().

03440 {
03441    struct ast_datastore *cc_datastore;
03442    struct ast_datastore *cc_recall_datastore;
03443    struct dialed_cc_interfaces *cc_interfaces;
03444    struct cc_recall_ds_data *recall_cc_data;
03445 
03446    ast_channel_lock(chan);
03447    if ((cc_datastore = ast_channel_datastore_find(chan, &dialed_cc_interfaces_info, NULL))) {
03448       cc_interfaces = cc_datastore->data;
03449       cc_interfaces->ignore = 1;
03450    }
03451 
03452    if ((cc_recall_datastore = ast_channel_datastore_find(chan, &recall_ds_info, NULL))) {
03453       recall_cc_data = cc_recall_datastore->data;
03454       recall_cc_data->ignore = 1;
03455    }
03456    ast_channel_unlock(chan);
03457 }

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 3871 of file ccss.c.

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(), and LOG_NOTICE.

Referenced by analog_call(), sig_pri_cc_available(), sig_pri_cc_generic_check(), and sip_handle_cc().

03873 {
03874    struct ast_frame frame = {0,};
03875    char device_name[AST_CHANNEL_NAME];
03876    int retval;
03877    struct ast_cc_config_params *cc_params;
03878 
03879    cc_params = ast_channel_get_cc_config_params(chan);
03880    if (!cc_params) {
03881       return -1;
03882    }
03883    ast_channel_get_device_name(chan, device_name, sizeof(device_name));
03884    if (ast_cc_monitor_count(device_name, monitor_type) >= ast_get_cc_max_monitors(cc_params)) {
03885       ast_log(LOG_NOTICE, "Not queuing a CC frame for device %s since it already has its maximum monitors allocated\n", device_name);
03886       return -1;
03887    }
03888 
03889    if (ast_cc_build_frame(chan, cc_params, monitor_type, device_name, dialstring, service, private_data, &frame)) {
03890       /* Frame building failed. We can't use this. */
03891       return -1;
03892    }
03893    retval = ast_queue_frame(chan, &frame);
03894    ast_frfree(&frame);
03895    return retval;
03896 }

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
Return values:
void 

Definition at line 841 of file ccss.c.

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

Referenced by ast_cc_set_param().

00842 {
00843    if (ast_strlen_zero(value)) {
00844       config->cc_agent_dialstring[0] = '\0';
00845    } else {
00846       ast_copy_string(config->cc_agent_dialstring, value, sizeof(config->cc_agent_dialstring));
00847    }
00848 }

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 747 of file ccss.c.

References AST_CC_AGENT_GENERIC, and config.

Referenced by ast_cc_set_param(), and build_peer().

00748 {
00749    /* Screw C and its weak type checking for making me have to do this
00750     * validation at runtime.
00751     */
00752    if (value < AST_CC_AGENT_NEVER || value > AST_CC_AGENT_GENERIC) {
00753       return -1;
00754    }
00755    config->cc_agent_policy = value;
00756    return 0;
00757 }

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

Set the callback_macro name.

Since:
1.8
Parameters:
config The configuration to set the callback_macro on
value The new callback macro we want to change to
Return values:
void 

Definition at line 875 of file ccss.c.

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

Referenced by ast_cc_set_param().

00876 {
00877    if (ast_strlen_zero(value)) {
00878       config->cc_callback_macro[0] = '\0';
00879    } else {
00880       ast_copy_string(config->cc_callback_macro, value, sizeof(config->cc_callback_macro));
00881    }
00882 }

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 extension as a starting point.

Since:
1.8
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 chan_local, 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 3387 of file ccss.c.

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_recall_ds_data::core_id, ast_datastore::data, ast_cc_interface::device_name, ast_cc_monitor::interface, cc_recall_ds_data::interface_tree, cc_monitor_backend::next, pbx_builtin_setvar_helper(), recall_ds_info, and str.

Referenced by local_call().

03388 {
03389    struct ast_datastore *recall_datastore;
03390    struct cc_monitor_tree *interface_tree;
03391    struct ast_cc_monitor *monitor_iter;
03392    struct cc_recall_ds_data *recall_data;
03393    struct ast_str *str = ast_str_create(64);
03394    int core_id;
03395 
03396    if (!str) {
03397       return -1;
03398    }
03399 
03400    ast_channel_lock(chan);
03401    if (!(recall_datastore = ast_channel_datastore_find(chan, &recall_ds_info, NULL))) {
03402       ast_channel_unlock(chan);
03403       ast_free(str);
03404       return -1;
03405    }
03406    recall_data = recall_datastore->data;
03407    interface_tree = recall_data->interface_tree;
03408    core_id = recall_data->core_id;
03409    ast_channel_unlock(chan);
03410 
03411    AST_LIST_LOCK(interface_tree);
03412    AST_LIST_TRAVERSE(interface_tree, monitor_iter, next) {
03413       if (!strcmp(monitor_iter->interface->device_name, extension)) {
03414          break;
03415       }
03416    }
03417 
03418    if (!monitor_iter) {
03419       /* We couldn't find this extension. This may be because
03420        * we have been directed into an unexpected extension because
03421        * the admin has changed a CC_INTERFACES variable at some point.
03422        */
03423       AST_LIST_UNLOCK(interface_tree);
03424       ast_free(str);
03425       return -1;
03426    }
03427 
03428    build_cc_interfaces_chanvar(monitor_iter, str);
03429    AST_LIST_UNLOCK(interface_tree);
03430 
03431    pbx_builtin_setvar_helper(chan, "CC_INTERFACES", ast_str_buffer(str));
03432    ast_log_dynamic_level(cc_logger_level, "Core %d: CC_INTERFACES set to %s\n",
03433          core_id, ast_str_buffer(str));
03434 
03435    ast_free(str);
03436    return 0;
03437 }

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
Return values:
void 

Definition at line 855 of file ccss.c.

References config.

Referenced by ast_cc_set_param().

00856 {
00857    config->cc_max_agents = value;
00858 }

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
Return values:
void 

Definition at line 865 of file ccss.c.

References config.

Referenced by ast_cc_set_param().

00866 {
00867    config->cc_max_monitors = value;
00868 }

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 764 of file ccss.c.

References AST_CC_MONITOR_ALWAYS, and config.

Referenced by ast_cc_set_param().

00765 {
00766    /* Screw C and its weak type checking for making me have to do this
00767     * validation at runtime.
00768     */
00769    if (value < AST_CC_MONITOR_NEVER || value > AST_CC_MONITOR_ALWAYS) {
00770       return -1;
00771    }
00772    config->cc_monitor_policy = value;
00773    return 0;
00774 }

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
Return values:
void 

Definition at line 781 of file ccss.c.

References ast_log(), config, and LOG_WARNING.

Referenced by ast_cc_set_param().

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

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
Return values:
void 

Definition at line 811 of file ccss.c.

References ast_log(), config, and LOG_WARNING.

Referenced by ast_cc_set_param().

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

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
Return values:
void 

Definition at line 826 of file ccss.c.

References ast_log(), config, and LOG_WARNING.

Referenced by ast_cc_set_param().

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

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
Return values:
void 

Definition at line 796 of file ccss.c.

References ast_log(), config, and LOG_WARNING.

Referenced by ast_cc_set_param().

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

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 3124 of file ccss.c.

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(), ast_datastore::data, DATASTORE_INHERIT_FOREVER, find_cc_core_instance(), ast_datastore::inheritance, cc_core_instance::monitors, and recall_ds_info.

Referenced by generic_recall(), handle_request_invite(), and sig_pri_handle_subcmds().

03125 {
03126    struct ast_datastore *recall_datastore = ast_datastore_alloc(&recall_ds_info, NULL);
03127    struct cc_recall_ds_data *recall_data;
03128    struct cc_core_instance *core_instance;
03129 
03130    if (!recall_datastore) {
03131       return -1;
03132    }
03133 
03134    if (!(recall_data = ast_calloc(1, sizeof(*recall_data)))) {
03135       ast_datastore_free(recall_datastore);
03136       return -1;
03137    }
03138 
03139    if (!(core_instance = find_cc_core_instance(core_id))) {
03140       ast_free(recall_data);
03141       ast_datastore_free(recall_datastore);
03142       return -1;
03143    }
03144 
03145    recall_data->interface_tree = cc_ref(core_instance->monitors,
03146          "Bump refcount for monitor tree for recall datastore");
03147    recall_data->core_id = core_id;
03148    recall_datastore->data = recall_data;
03149    recall_datastore->inheritance = DATASTORE_INHERIT_FOREVER;
03150    ast_channel_lock(chan);
03151    ast_channel_datastore_add(chan, recall_datastore);
03152    ast_channel_unlock(chan);
03153    cc_unref(core_instance, "Recall datastore set up. No need for core_instance ref");
03154    return 0;
03155 }


Generated on Mon Mar 19 11:30:37 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7