00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2010, Digium, Inc. 00005 * 00006 * Mark Michelson <mmichelson@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 /*! \file 00020 * \brief Call Completion Supplementary Services API 00021 * \author Mark Michelson <mmichelson@digium.com> 00022 */ 00023 00024 #ifndef _ASTERISK_CCSS_H 00025 #define _ASTERISK_CCSS_H 00026 00027 #include "asterisk.h" 00028 00029 #include "asterisk/linkedlists.h" 00030 #include "asterisk/devicestate.h" 00031 00032 enum ast_cc_service_type { 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 }; 00042 00043 /*! 00044 * \since 1.8 00045 * \brief The various possibilities for cc_agent_policy values 00046 */ 00047 enum ast_cc_agent_policies { 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 }; 00055 00056 /*! 00057 * \brief agent flags that can alter core behavior 00058 */ 00059 enum ast_cc_agent_flags { 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 }; 00069 00070 /*! 00071 * \since 1.8 00072 * \brief The various possibilities for cc_monitor_policy values 00073 */ 00074 enum ast_cc_monitor_policies { 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 }; 00089 00090 /* Forward declaration. Struct is in main/ccss.c */ 00091 struct ast_cc_config_params; 00092 00093 /*! 00094 * \since 1.8 00095 * \brief Queue an AST_CONTROL_CC frame 00096 * 00097 * \note 00098 * Since this function calls ast_queue_frame, the channel will be 00099 * locked during the course of this function. 00100 * 00101 * \param chan The channel onto which to queue the frame 00102 * \param monitor_type The type of monitor to use when CC is requested 00103 * \param dialstring The dial string used to call the device 00104 * \param service The type of CC service the device is willing to offer 00105 * \param private_data If a native monitor is being used, and some channel-driver-specific private 00106 * data has been allocated, then this parameter should contain a pointer to that data. If using a generic 00107 * monitor, this parameter should remain NULL. Note that if this function should fail at some point, 00108 * it is the responsibility of the caller to free the private data upon return. 00109 * \retval 0 Success 00110 * \retval -1 Error 00111 */ 00112 int ast_queue_cc_frame(struct ast_channel *chan, const char * const monitor_type, 00113 const char * const dialstring, enum ast_cc_service_type service, void *private_data); 00114 00115 /*! 00116 * \brief Allocate and initialize an ast_cc_config_params structure 00117 * 00118 * \note 00119 * Reasonable default values are chosen for the parameters upon allocation. 00120 * 00121 * \retval NULL Unable to allocate the structure 00122 * \retval non-NULL A pointer to the newly allocated and initialized structure 00123 */ 00124 struct ast_cc_config_params *__ast_cc_config_params_init(const char *file, int line, const char *function); 00125 00126 /*! 00127 * \brief Allocate and initialize an ast_cc_config_params structure 00128 * 00129 * \note 00130 * Reasonable default values are chosen for the parameters upon allocation. 00131 * 00132 * \retval NULL Unable to allocate the structure 00133 * \retval non-NULL A pointer to the newly allocated and initialized structure 00134 */ 00135 #define ast_cc_config_params_init() __ast_cc_config_params_init(__FILE__, __LINE__, __PRETTY_FUNCTION__) 00136 00137 /*! 00138 * \brief Free memory from CCSS configuration params 00139 * 00140 * \note 00141 * Just a call to ast_free for now... 00142 * 00143 * \param params Pointer to structure whose memory we need to free 00144 * \retval void 00145 */ 00146 void ast_cc_config_params_destroy(struct ast_cc_config_params *params); 00147 00148 /*! 00149 * \brief set a CCSS configuration parameter, given its name 00150 * 00151 * \note 00152 * Useful when parsing config files when used in conjunction 00153 * with ast_ccss_is_cc_config_param. 00154 * 00155 * \param params The parameter structure to set the value on 00156 * \param name The name of the cc parameter 00157 * \param value The value of the parameter 00158 * \retval 0 Success 00159 * \retval -1 Failure 00160 */ 00161 int ast_cc_set_param(struct ast_cc_config_params *params, const char * const name, 00162 const char * value); 00163 00164 /*! 00165 * \brief get a CCSS configuration parameter, given its name 00166 * 00167 * \note 00168 * Useful when reading input as a string, like from dialplan or 00169 * manager. 00170 * 00171 * \param params The CCSS configuration from which to get the value 00172 * \param name The name of the CCSS parameter we want 00173 * \param buf A preallocated buffer to hold the value 00174 * \param buf_len The size of buf 00175 * \retval 0 Success 00176 * \retval -1 Failure 00177 */ 00178 int ast_cc_get_param(struct ast_cc_config_params *params, const char * const name, 00179 char *buf, size_t buf_len); 00180 00181 /*! 00182 * \since 1.8 00183 * \brief Is this a CCSS configuration parameter? 00184 * \param name Name of configuration option being parsed. 00185 * \retval 1 Yes, this is a CCSS configuration parameter. 00186 * \retval 0 No, this is not a CCSS configuration parameter. 00187 */ 00188 int ast_cc_is_config_param(const char * const name); 00189 00190 /*! 00191 * \since 1.8 00192 * \brief Set the specified CC config params to default values. 00193 * 00194 * \details 00195 * This is just like ast_cc_copy_config_params() and could be used in place 00196 * of it if you need to set the config params to defaults instead. 00197 * You are simply "copying" defaults into the destination. 00198 * 00199 * \param params CC config params to set to default values. 00200 * 00201 * \return Nothing 00202 */ 00203 void ast_cc_default_config_params(struct ast_cc_config_params *params); 00204 00205 /*! 00206 * \since 1.8 00207 * \brief copy CCSS configuration parameters from one structure to another 00208 * 00209 * \details 00210 * For now, this is a simple memcpy, but this function is necessary since 00211 * the size of an ast_cc_config_params structure is unknown outside of 00212 * main/ccss.c. Also, this allows for easier expansion of the function in 00213 * case it becomes more complex than just a memcpy. 00214 * 00215 * \param src The structure from which data is copied 00216 * \param dest The structure to which data is copied 00217 * 00218 * \return Nothing 00219 */ 00220 void ast_cc_copy_config_params(struct ast_cc_config_params *dest, const struct ast_cc_config_params *src); 00221 00222 /*! 00223 * \since 1.8 00224 * \brief Get the cc_agent_policy 00225 * \param config The configuration to retrieve the policy from 00226 * \return The current cc_agent_policy for this configuration 00227 */ 00228 enum ast_cc_agent_policies ast_get_cc_agent_policy(struct ast_cc_config_params *config); 00229 00230 /*! 00231 * \since 1.8 00232 * \brief Set the cc_agent_policy 00233 * \param config The configuration to set the cc_agent_policy on 00234 * \param value The new cc_agent_policy we want to change to 00235 * \retval 0 Success 00236 * \retval -1 Failure (likely due to bad input) 00237 */ 00238 int ast_set_cc_agent_policy(struct ast_cc_config_params *config, enum ast_cc_agent_policies value); 00239 00240 /*! 00241 * \since 1.8 00242 * \brief Get the cc_monitor_policy 00243 * \param config The configuration to retrieve the cc_monitor_policy from 00244 * \return The cc_monitor_policy retrieved from the configuration 00245 */ 00246 enum ast_cc_monitor_policies ast_get_cc_monitor_policy(struct ast_cc_config_params *config); 00247 00248 /*! 00249 * \since 1.8 00250 * \brief Set the cc_monitor_policy 00251 * \param config The configuration to set the cc_monitor_policy on 00252 * \param value The new cc_monitor_policy we want to change to 00253 * \retval 0 Success 00254 * \retval -1 Failure (likely due to bad input) 00255 */ 00256 int ast_set_cc_monitor_policy(struct ast_cc_config_params *config, enum ast_cc_monitor_policies value); 00257 00258 /*! 00259 * \since 1.8 00260 * \brief Get the cc_offer_timer 00261 * \param config The configuration to retrieve the cc_offer_timer from 00262 * \return The cc_offer_timer from this configuration 00263 */ 00264 unsigned int ast_get_cc_offer_timer(struct ast_cc_config_params *config); 00265 00266 /*! 00267 * \since 1.8 00268 * \brief Set the cc_offer_timer 00269 * \param config The configuration to set the cc_offer_timer on 00270 * \param value The new cc_offer_timer we want to change to 00271 * \retval void 00272 */ 00273 void ast_set_cc_offer_timer(struct ast_cc_config_params *config, unsigned int value); 00274 00275 /*! 00276 * \since 1.8 00277 * \brief Get the ccnr_available_timer 00278 * \param config The configuration to retrieve the ccnr_available_timer from 00279 * \return The ccnr_available_timer from this configuration 00280 */ 00281 unsigned int ast_get_ccnr_available_timer(struct ast_cc_config_params *config); 00282 00283 /*! 00284 * \since 1.8 00285 * \brief Set the ccnr_available_timer 00286 * \param config The configuration to set the ccnr_available_timer on 00287 * \param value The new ccnr_available_timer we want to change to 00288 * \retval void 00289 */ 00290 void ast_set_ccnr_available_timer(struct ast_cc_config_params *config, unsigned int value); 00291 00292 /*! 00293 * \since 1.8 00294 * \brief Get the cc_recall_timer 00295 * \param config The configuration to retrieve the cc_recall_timer from 00296 * \return The cc_recall_timer from this configuration 00297 */ 00298 unsigned int ast_get_cc_recall_timer(struct ast_cc_config_params *config); 00299 00300 /*! 00301 * \since 1.8 00302 * \brief Set the cc_recall_timer 00303 * \param config The configuration to set the cc_recall_timer on 00304 * \param value The new cc_recall_timer we want to change to 00305 * \retval void 00306 */ 00307 void ast_set_cc_recall_timer(struct ast_cc_config_params *config, unsigned int value); 00308 00309 /*! 00310 * \since 1.8 00311 * \brief Get the ccbs_available_timer 00312 * \param config The configuration to retrieve the ccbs_available_timer from 00313 * \return The ccbs_available_timer from this configuration 00314 */ 00315 unsigned int ast_get_ccbs_available_timer(struct ast_cc_config_params *config); 00316 00317 /*! 00318 * \since 1.8 00319 * \brief Set the ccbs_available_timer 00320 * \param config The configuration to set the ccbs_available_timer on 00321 * \param value The new ccbs_available_timer we want to change to 00322 * \retval void 00323 */ 00324 void ast_set_ccbs_available_timer(struct ast_cc_config_params *config, unsigned int value); 00325 00326 /*! 00327 * \since 1.8 00328 * \brief Get the cc_agent_dialstring 00329 * \param config The configuration to retrieve the cc_agent_dialstring from 00330 * \return The cc_agent_dialstring from this configuration 00331 */ 00332 const char *ast_get_cc_agent_dialstring(struct ast_cc_config_params *config); 00333 00334 /*! 00335 * \since 1.8 00336 * \brief Set the cc_agent_dialstring 00337 * \param config The configuration to set the cc_agent_dialstring on 00338 * \param value The new cc_agent_dialstring we want to change to 00339 * \retval void 00340 */ 00341 void ast_set_cc_agent_dialstring(struct ast_cc_config_params *config, const char *const value); 00342 00343 /*! 00344 * \since 1.8 00345 * \brief Get the cc_max_agents 00346 * \param config The configuration to retrieve the cc_max_agents from 00347 * \return The cc_max_agents from this configuration 00348 */ 00349 unsigned int ast_get_cc_max_agents(struct ast_cc_config_params *config); 00350 00351 /*! 00352 * \since 1.8 00353 * \brief Set the cc_max_agents 00354 * \param config The configuration to set the cc_max_agents on 00355 * \param value The new cc_max_agents we want to change to 00356 * \retval void 00357 */ 00358 void ast_set_cc_max_agents(struct ast_cc_config_params *config, unsigned int value); 00359 00360 /*! 00361 * \since 1.8 00362 * \brief Get the cc_max_monitors 00363 * \param config The configuration to retrieve the cc_max_monitors from 00364 * \return The cc_max_monitors from this configuration 00365 */ 00366 unsigned int ast_get_cc_max_monitors(struct ast_cc_config_params *config); 00367 00368 /*! 00369 * \since 1.8 00370 * \brief Set the cc_max_monitors 00371 * \param config The configuration to set the cc_max_monitors on 00372 * \param value The new cc_max_monitors we want to change to 00373 * \retval void 00374 */ 00375 void ast_set_cc_max_monitors(struct ast_cc_config_params *config, unsigned int value); 00376 00377 /*! 00378 * \since 1.8 00379 * \brief Get the name of the callback_macro 00380 * \param config The configuration to retrieve the callback_macro from 00381 * \return The callback_macro name 00382 */ 00383 const char *ast_get_cc_callback_macro(struct ast_cc_config_params *config); 00384 00385 /*! 00386 * \since 1.8 00387 * \brief Set the callback_macro name 00388 * \param config The configuration to set the callback_macro on 00389 * \param value The new callback macro we want to change to 00390 * \retval void 00391 */ 00392 void ast_set_cc_callback_macro(struct ast_cc_config_params *config, const char * const value); 00393 00394 /* END CONFIGURATION FUNCTIONS */ 00395 00396 /* BEGIN AGENT/MONITOR REGISTRATION API */ 00397 00398 struct ast_cc_monitor_callbacks; 00399 00400 /*! 00401 * \since 1.8 00402 * \brief Register a set of monitor callbacks with the core 00403 * 00404 * \details 00405 * This is made so that at monitor creation time, the proper callbacks 00406 * may be installed and the proper .init callback may be called for the 00407 * monitor to establish private data. 00408 * 00409 * \param callbacks The callbacks used by the monitor implementation 00410 * \retval 0 Successfully registered 00411 * \retval -1 Failure to register 00412 */ 00413 int ast_cc_monitor_register(const struct ast_cc_monitor_callbacks *callbacks); 00414 00415 /*! 00416 * \since 1.8 00417 * \brief Unregister a set of monitor callbacks with the core 00418 * 00419 * \details 00420 * If a module which makes use of a CC monitor is unloaded, then it may 00421 * unregister its monitor callbacks with the core. 00422 * 00423 * \param callbacks The callbacks used by the monitor implementation 00424 * \retval 0 Successfully unregistered 00425 * \retval -1 Failure to unregister 00426 */ 00427 void ast_cc_monitor_unregister(const struct ast_cc_monitor_callbacks *callbacks); 00428 00429 struct ast_cc_agent_callbacks; 00430 00431 /*! 00432 * \since 1.8 00433 * \brief Register a set of agent callbacks with the core 00434 * 00435 * \details 00436 * This is made so that at agent creation time, the proper callbacks 00437 * may be installed and the proper .init callback may be called for the 00438 * monitor to establish private data. 00439 * 00440 * \param callbacks The callbacks used by the agent implementation 00441 * \retval 0 Successfully registered 00442 * \retval -1 Failure to register 00443 */ 00444 int ast_cc_agent_register(const struct ast_cc_agent_callbacks *callbacks); 00445 00446 /*! 00447 * \since 1.8 00448 * \brief Unregister a set of agent callbacks with the core 00449 * 00450 * \details 00451 * If a module which makes use of a CC agent is unloaded, then it may 00452 * unregister its agent callbacks with the core. 00453 * 00454 * \param callbacks The callbacks used by the agent implementation 00455 * \retval 0 Successfully unregistered 00456 * \retval -1 Failure to unregister 00457 */ 00458 void ast_cc_agent_unregister(const struct ast_cc_agent_callbacks *callbacks); 00459 00460 /* END AGENT/MONITOR REGISTRATION API */ 00461 00462 /* BEGIN SECTION ON MONITORS AND MONITOR CALLBACKS */ 00463 00464 /*! 00465 * It is recommended that monitors use a pointer to 00466 * an ast_cc_monitor_callbacks::type when creating 00467 * an AST_CONTROL_CC frame. Since the generic monitor 00468 * callbacks are opaque and channel drivers will wish 00469 * to use that, this string is made globally available 00470 * for all to use 00471 */ 00472 #define AST_CC_GENERIC_MONITOR_TYPE "generic" 00473 00474 /*! 00475 * Used to determine which type 00476 * of monitor an ast_cc_device_monitor 00477 * is. 00478 */ 00479 enum ast_cc_monitor_class { 00480 AST_CC_DEVICE_MONITOR, 00481 AST_CC_EXTENSION_MONITOR, 00482 }; 00483 00484 /*! 00485 * \internal 00486 * \brief An item in a CC interface tree. 00487 * 00488 * These are the individual items in an interface tree. 00489 * The key difference between this structure and the ast_cc_interface 00490 * is that this structure contains data which is intrinsic to the item's 00491 * placement in the tree, such as who its parent is. 00492 */ 00493 struct ast_cc_monitor { 00494 /*! 00495 * Information regarding the interface. 00496 */ 00497 struct ast_cc_interface *interface; 00498 /*! 00499 * Every interface has an id that uniquely identifies it. It is 00500 * formed by incrementing a counter. 00501 */ 00502 unsigned int id; 00503 /*! 00504 * The ID of this monitor's parent. If this monitor is at the 00505 * top of the tree, then his parent will be 0. 00506 */ 00507 unsigned int parent_id; 00508 /*! 00509 * The instance of the CC core to which this monitor belongs 00510 */ 00511 int core_id; 00512 /*! 00513 * The type of call completion service offered by a device. 00514 */ 00515 enum ast_cc_service_type service_offered; 00516 /*! 00517 * \brief Name that should be used to recall specified interface 00518 * 00519 * \details 00520 * When issuing a CC recall, some technologies will require 00521 * that a name other than the device name is dialed. For instance, 00522 * with SIP, a specific URI will be used which chan_sip will be able 00523 * to recognize as being a CC recall. Similarly, ISDN will need a specific 00524 * dial string to know that the call is a recall. 00525 */ 00526 char *dialstring; 00527 /*! 00528 * The ID of the available timer used by the current monitor 00529 */ 00530 int available_timer_id; 00531 /*! 00532 * Monitor callbacks 00533 */ 00534 const struct ast_cc_monitor_callbacks *callbacks; 00535 /*! 00536 * \brief Data that is private to a monitor technology 00537 * 00538 * Most channel drivers that implement CC monitors will have to 00539 * allocate data that the CC core does not care about but which 00540 * is vital to the operation of the monitor. This data is stored 00541 * in this pointer so that the channel driver may use it as 00542 * needed 00543 */ 00544 void *private_data; 00545 AST_LIST_ENTRY(ast_cc_monitor) next; 00546 }; 00547 00548 /*! 00549 * \brief Callbacks defined by CC monitors 00550 * 00551 * \note 00552 * Every callback is called with the list of monitors locked. There 00553 * are several public API calls that also will try to lock this lock. 00554 * These public functions have a note in their doxygen stating so. 00555 * As such, pay attention to the lock order you establish in these callbacks 00556 * to ensure that you do not violate the lock order when calling 00557 * the functions in this file with lock order notices. 00558 */ 00559 struct ast_cc_monitor_callbacks { 00560 /*! 00561 * \brief Type of monitor the callbacks belong to. 00562 * 00563 * \note 00564 * Examples include "generic" and "SIP" 00565 */ 00566 const char *type; 00567 /*! 00568 * \brief Request CCSS. 00569 * 00570 * \param monitor CC core monitor control. 00571 * \param available_timer_id The scheduler ID for the available timer. 00572 * Will never be NULL for a device monitor. 00573 * 00574 * \details 00575 * Perform whatever steps are necessary in order to request CC. 00576 * In addition, the monitor implementation is responsible for 00577 * starting the available timer in this callback. 00578 * 00579 * \retval 0 on success 00580 * \retval -1 on failure. 00581 */ 00582 int (*request_cc)(struct ast_cc_monitor *monitor, int *available_timer_id); 00583 /*! 00584 * \brief Suspend monitoring. 00585 * 00586 * \param monitor CC core monitor control. 00587 * 00588 * \details 00589 * Implementers must perform the necessary steps to suspend 00590 * monitoring. 00591 * 00592 * \retval 0 on success 00593 * \retval -1 on failure. 00594 */ 00595 int (*suspend)(struct ast_cc_monitor *monitor); 00596 /*! 00597 * \brief Status response to an ast_cc_monitor_status_request(). 00598 * 00599 * \param monitor CC core monitor control. 00600 * \param devstate Current status of a Party A device. 00601 * 00602 * \details 00603 * Alert a monitor as to the status of the agent for which 00604 * the monitor had previously requested a status request. 00605 * 00606 * \note Zero or more responses may come as a result. 00607 * 00608 * \retval 0 on success 00609 * \retval -1 on failure. 00610 */ 00611 int (*status_response)(struct ast_cc_monitor *monitor, enum ast_device_state devstate); 00612 /*! 00613 * \brief Unsuspend monitoring. 00614 * 00615 * \param monitor CC core monitor control. 00616 * 00617 * \details 00618 * Perform the necessary steps to unsuspend monitoring. 00619 * 00620 * \retval 0 on success 00621 * \retval -1 on failure. 00622 */ 00623 int (*unsuspend)(struct ast_cc_monitor *monitor); 00624 /*! 00625 * \brief Cancel the running available timer. 00626 * 00627 * \param monitor CC core monitor control. 00628 * \param sched_id Available timer scheduler id to cancel. 00629 * Will never be NULL for a device monitor. 00630 * 00631 * \details 00632 * In most cases, this function will likely consist of just a 00633 * call to AST_SCHED_DEL. It might have been possible to do this 00634 * within the core, but unfortunately the mixture of sched_thread 00635 * and sched usage in Asterisk prevents such usage. 00636 * 00637 * \retval 0 on success 00638 * \retval -1 on failure. 00639 */ 00640 int (*cancel_available_timer)(struct ast_cc_monitor *monitor, int *sched_id); 00641 /*! 00642 * \brief Destroy private data on the monitor. 00643 * 00644 * \param private_data The private data pointer from the monitor. 00645 * 00646 * \details 00647 * Implementers of this callback are responsible for destroying 00648 * all heap-allocated data in the monitor's private_data pointer, including 00649 * the private_data itself. 00650 */ 00651 void (*destructor)(void *private_data); 00652 }; 00653 00654 /*! 00655 * \since 1.8 00656 * \brief Scheduler callback for available timer expiration 00657 * 00658 * \note 00659 * When arming the available timer from within a device monitor, you MUST 00660 * use this function as the callback for the scheduler. 00661 * 00662 * \param data A reference to the CC monitor on which the timer was running. 00663 */ 00664 int ast_cc_available_timer_expire(const void *data); 00665 00666 /* END SECTION ON MONITORS AND MONITOR CALLBACKS */ 00667 00668 /* BEGIN API FOR IN-CALL CC HANDLING */ 00669 00670 /*! 00671 * \since 1.8 00672 * 00673 * \brief Mark the channel to ignore further CC activity. 00674 * 00675 * \details 00676 * When a CC-capable application, such as Dial, has finished 00677 * with all CC processing for a channel and knows that any further 00678 * CC processing should be ignored, this function should be called. 00679 * 00680 * \param chan The channel for which further CC processing should be ignored. 00681 * \retval void 00682 */ 00683 void ast_ignore_cc(struct ast_channel *chan); 00684 00685 /*! 00686 * \since 1.8 00687 * 00688 * \brief Properly react to a CC control frame. 00689 * 00690 * \details 00691 * When a CC-capable application, such as Dial, receives a frame 00692 * of type AST_CONTROL_CC, then it may call this function in order 00693 * to have the device which sent the frame added to the tree of interfaces 00694 * which is kept on the inbound channel. 00695 * 00696 * \param inbound The inbound channel 00697 * \param outbound The outbound channel (The one from which the CC frame was read) 00698 * \param frame_data The ast_frame's data.ptr field. 00699 * \retval void 00700 */ 00701 void ast_handle_cc_control_frame(struct ast_channel *inbound, struct ast_channel *outbound, void *frame_data); 00702 00703 /*! 00704 * \since 1.8 00705 * 00706 * \brief Start the CC process on a call. 00707 * 00708 * \details 00709 * Whenever a CC-capable application, such as Dial, wishes to 00710 * engage in CC activity, it initiates the process by calling this 00711 * function. If the CC core should discover that a previous application 00712 * has called ast_ignore_cc on this channel or a "parent" channel, then 00713 * the value of the ignore_cc integer passed in will be set nonzero. 00714 * 00715 * The ignore_cc parameter is a convenience parameter. It can save an 00716 * application the trouble of trying to call CC APIs when it knows that 00717 * it should just ignore further attempts at CC actions. 00718 * 00719 * \param chan The inbound channel calling the CC-capable application. 00720 * \param[out] ignore_cc Will be set non-zero if no further CC actions need to be taken 00721 * \retval 0 Success 00722 * \retval -1 Failure 00723 */ 00724 int ast_cc_call_init(struct ast_channel *chan, int *ignore_cc); 00725 00726 /*! 00727 * \since 1.8 00728 * 00729 * \brief Add a child dialstring to an extension monitor 00730 * 00731 * Whenever we request a channel, the parent extension monitor needs 00732 * to store the dialstring of the device requested. The reason is so 00733 * that we can call the device back during the recall even if we are 00734 * not monitoring the device. 00735 * 00736 * \param incoming The caller's channel 00737 * \param dialstring The dialstring used when requesting the outbound channel 00738 * \param device_name The device name associated with the requested outbound channel 00739 * \retval void 00740 */ 00741 void ast_cc_extension_monitor_add_dialstring(struct ast_channel *incoming, const char * const dialstring, const char * const device_name); 00742 00743 /*! 00744 * \since 1.8 00745 * \brief Check if the incoming CC request is within the bounds 00746 * set by the cc_max_requests configuration option 00747 * 00748 * \details 00749 * It is recommended that an entity which receives an incoming 00750 * CC request calls this function before calling 00751 * ast_cc_agent_accept_request. This way, immediate feedback can be 00752 * given to the caller about why his request was rejected. 00753 * 00754 * If this is not called and a state change to CC_CALLER_REQUESTED 00755 * is made, then the core will still not allow for the request 00756 * to succeed. However, if done this way, it may not be obvious 00757 * to the requestor why the request failed. 00758 * 00759 * \retval 0 Not within the limits. Fail. 00760 * \retval non-zero Within the limits. Success. 00761 */ 00762 int ast_cc_request_is_within_limits(void); 00763 00764 /*! 00765 * \since 1.8 00766 * \brief Get the core id for the current call 00767 * 00768 * \details 00769 * The main use of this function is for channel drivers 00770 * who queue an AST_CONTROL_CC frame. A channel driver may 00771 * call this function in order to get the core_id for what 00772 * may become a CC request. This way, when monitor functions 00773 * are called which use a core_id as a means of identification, 00774 * the channel driver will have saved this information. 00775 * 00776 * The channel given to this function may be an inbound or outbound 00777 * channel. Both will have the necessary info on it. 00778 * 00779 * \param chan The channel from which to get the core_id. 00780 * \retval core_id on success 00781 * \retval -1 Failure 00782 */ 00783 int ast_cc_get_current_core_id(struct ast_channel *chan); 00784 00785 /* END API FOR IN-CALL CC HANDLING */ 00786 00787 /*! 00788 * \brief Structure with information about an outbound interface 00789 * 00790 * \details 00791 * This structure is first created when an outbound interface indicates that 00792 * it is capable of accepting a CC request. It is stored in a "tree" on a datastore on 00793 * the caller's channel. Once an agent structure is created, the agent gains 00794 * a reference to the tree of interfaces. If CC is requested, then the 00795 * interface tree on the agent is converted into a tree of monitors. Each 00796 * monitor will contain a pointer to an individual ast_cc_interface. Finally, 00797 * the tree of interfaces is also present on a second datastore during a 00798 * CC recall so that the CC_INTERFACES channel variable may be properly 00799 * populated. 00800 */ 00801 struct ast_cc_interface { 00802 /* What class of monitor is being offered here 00803 */ 00804 enum ast_cc_monitor_class monitor_class; 00805 /*! 00806 * \brief The type of monitor that should be used for this interface 00807 * 00808 * \details 00809 * This will be something like "extension" "generic" or "SIP". 00810 * This should point to a static const char *, so there is 00811 * no reason to make a new copy. 00812 */ 00813 const char *monitor_type; 00814 /*! 00815 * The configuration parameters used for this interface 00816 */ 00817 struct ast_cc_config_params *config_params; 00818 /* The name of the interface/extension. local channels will 00819 * have 'exten@context' for a name. Other channel types will 00820 * have 'tech/device' for a name. 00821 */ 00822 char device_name[1]; 00823 }; 00824 00825 /* BEGIN STRUCTURES FOR AGENTS */ 00826 00827 struct ast_cc_agent { 00828 /*! 00829 * Which instance of the core state machine does this 00830 * agent pertain to? 00831 */ 00832 unsigned int core_id; 00833 /*! 00834 * Callback functions needed for specific agent 00835 * implementations 00836 */ 00837 const struct ast_cc_agent_callbacks *callbacks; 00838 /*! 00839 * Configuration parameters that affect this 00840 * agent's operation. 00841 */ 00842 struct ast_cc_config_params *cc_params; 00843 /*! 00844 * \brief Flags for agent operation 00845 * 00846 * \details 00847 * There are some attributes of certain agent types 00848 * that can alter the behavior of certain CC functions. 00849 * For a list of these flags, see the ast_cc_agent_flags 00850 * enum 00851 */ 00852 unsigned int flags; 00853 /*! Data specific to agent implementation */ 00854 void *private_data; 00855 /*! The name of the device which this agent 00856 * represents/communicates with 00857 */ 00858 char device_name[1]; 00859 }; 00860 00861 enum ast_cc_agent_response_reason { 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 }; 00869 00870 struct ast_cc_agent_callbacks { 00871 /*! 00872 * \brief Type of agent the callbacks belong to. 00873 * 00874 * \note 00875 * Examples are "SIP" "ISDN" and "generic" 00876 */ 00877 const char *type; 00878 /*! 00879 * \brief CC agent initialization. 00880 * 00881 * \param agent CC core agent control. 00882 * \param chan Original channel the agent will attempt to recall. 00883 * 00884 * \details 00885 * This callback is called when the CC core 00886 * is initialized. Agents should allocate 00887 * any private data necessary for the 00888 * call and assign it to the private_data 00889 * on the agent. Additionally, if any ast_cc_agent_flags 00890 * are pertinent to the specific agent type, they should 00891 * be set in this function as well. 00892 * 00893 * \retval 0 on success. 00894 * \retval -1 on error. 00895 */ 00896 int (*init)(struct ast_cc_agent *agent, struct ast_channel *chan); 00897 /*! 00898 * \brief Start the offer timer. 00899 * 00900 * \param agent CC core agent control. 00901 * 00902 * \details 00903 * This is called by the core when the caller hangs up after 00904 * a call for which CC may be requested. The agent should 00905 * begin the timer as configured. 00906 * 00907 * The primary reason why this functionality is left to 00908 * the specific agent implementations is due to the differing 00909 * use of schedulers throughout the code. Some channel drivers 00910 * may already have a scheduler context they wish to use, and 00911 * amongst those, some may use the ast_sched API while others 00912 * may use the ast_sched_thread API, which are incompatible. 00913 * 00914 * \retval 0 on success. 00915 * \retval -1 on error. 00916 */ 00917 int (*start_offer_timer)(struct ast_cc_agent *agent); 00918 /*! 00919 * \brief Stop the offer timer. 00920 * 00921 * \param agent CC core agent control. 00922 * 00923 * \details 00924 * This callback is called by the CC core when the caller 00925 * has requested CC. 00926 * 00927 * \retval 0 on success. 00928 * \retval -1 on error. 00929 */ 00930 int (*stop_offer_timer)(struct ast_cc_agent *agent); 00931 /*! 00932 * \brief Respond to a CC request. 00933 * 00934 * \param agent CC core agent control. 00935 * \param reason CC request response status. 00936 * 00937 * \details 00938 * When the core receives knowledge that a called 00939 * party has accepted a CC request, it will call 00940 * this callback. The core may also call this 00941 * if there is some error when attempting to process 00942 * the incoming CC request. 00943 * 00944 * The duty of this is to issue a propper response to a 00945 * CC request from the caller by acknowledging receipt 00946 * of that request or rejecting it. 00947 */ 00948 void (*respond)(struct ast_cc_agent *agent, enum ast_cc_agent_response_reason reason); 00949 /*! 00950 * \brief Request the status of the agent's device. 00951 * 00952 * \param agent CC core agent control. 00953 * 00954 * \details 00955 * Asynchronous request for the status of any caller 00956 * which may be a valid caller for the CC transaction. 00957 * Status responses should be made using the 00958 * ast_cc_status_response function. 00959 * 00960 * \retval 0 on success. 00961 * \retval -1 on error. 00962 */ 00963 int (*status_request)(struct ast_cc_agent *agent); 00964 /*! 00965 * \brief Request for an agent's phone to stop ringing. 00966 * 00967 * \param agent CC core agent control. 00968 * 00969 * \details 00970 * The usefulness of this is quite limited. The only specific 00971 * known case for this is if Asterisk requests CC over an ISDN 00972 * PTMP link as the TE side. If other phones are in the same 00973 * recall group as the Asterisk server, and one of those phones 00974 * picks up the recall notice, then Asterisk will receive a 00975 * "stop ringing" notification from the NT side of the PTMP 00976 * link. This indication needs to be passed to the phone 00977 * on the other side of the Asterisk server which originally 00978 * placed the call so that it will stop ringing. Since the 00979 * phone may be of any type, it is necessary to have a callback 00980 * that the core can know about. 00981 * 00982 * \retval 0 on success. 00983 * \retval -1 on error. 00984 */ 00985 int (*stop_ringing)(struct ast_cc_agent *agent); 00986 /*! 00987 * \brief Let the caller know that the callee has become free 00988 * but that the caller cannot attempt to call back because 00989 * he is either busy or there is congestion on his line. 00990 * 00991 * \param agent CC core agent control. 00992 * 00993 * \details 00994 * This is something that really only affects a scenario where 00995 * a phone places a call over ISDN PTMP to Asterisk, who then 00996 * connects over PTMP again to the ISDN network. For most agent 00997 * types, there is no need to implement this callback at all 00998 * because they don't really need to actually do anything in 00999 * this situation. If you're having trouble understanding what 01000 * the purpose of this callback is, then you can be safe simply 01001 * not implementing it. 01002 * 01003 * \retval 0 on success. 01004 * \retval -1 on error. 01005 */ 01006 int (*party_b_free)(struct ast_cc_agent *agent); 01007 /*! 01008 * \brief Begin monitoring a busy device. 01009 * 01010 * \param agent CC core agent control. 01011 * 01012 * \details 01013 * The core will call this callback if the callee becomes 01014 * available but the caller has reported that he is busy. 01015 * The agent should begin monitoring the caller's device. 01016 * When the caller becomes available again, the agent should 01017 * call ast_cc_agent_caller_available. 01018 * 01019 * \retval 0 on success. 01020 * \retval -1 on error. 01021 */ 01022 int (*start_monitoring)(struct ast_cc_agent *agent); 01023 /*! 01024 * \brief Alert the caller that it is time to try recalling. 01025 * 01026 * \param agent CC core agent control. 01027 * 01028 * \details 01029 * The core will call this function when it receives notice 01030 * that a monitored party has become available. 01031 * 01032 * The agent's job is to send a message to the caller to 01033 * notify it of such a change. If the agent is able to 01034 * discern that the caller is currently unavailable, then 01035 * the agent should react by calling the ast_cc_caller_unavailable 01036 * function. 01037 * 01038 * \retval 0 on success. 01039 * \retval -1 on error. 01040 */ 01041 int (*callee_available)(struct ast_cc_agent *agent); 01042 /*! 01043 * \brief Destroy private data on the agent. 01044 * 01045 * \param agent CC core agent control. 01046 * 01047 * \details 01048 * The core will call this function upon completion 01049 * or failure of CC. 01050 * 01051 * \note 01052 * The agent private_data pointer may be NULL if the agent 01053 * constructor failed. 01054 */ 01055 void (*destructor)(struct ast_cc_agent *agent); 01056 }; 01057 01058 /*! 01059 * \brief Call a callback on all agents of a specific type 01060 * 01061 * \details 01062 * Since the container of CC core instances is private, and so 01063 * are the items which the container contains, we have to provide 01064 * an ao2_callback-like method so that a specific agent may be 01065 * found or so that an operation can be made on all agents of 01066 * a particular type. The first three arguments should be familiar 01067 * to anyone who has used ao2_callback. The final argument is the 01068 * type of agent you wish to have the callback called on. 01069 * 01070 * \note Since agents are refcounted, and this function returns 01071 * a reference to the agent, it is imperative that you decrement 01072 * the refcount of the agent once you have finished using it. 01073 * 01074 * \param flags astobj2 search flags 01075 * \param function an ao2 callback function to call 01076 * \param arg the argument to the callback function 01077 * \param type The type of agents to call the callback on 01078 */ 01079 struct ast_cc_agent *ast_cc_agent_callback(int flags, ao2_callback_fn *function, void *arg, const char * const type); 01080 01081 /* END STRUCTURES FOR AGENTS */ 01082 01083 /* BEGIN STATE CHANGE API */ 01084 01085 /*! 01086 * \since 1.8 01087 * \brief Offer CC to a caller 01088 * 01089 * \details 01090 * This function is called from ast_hangup if the caller is 01091 * eligible to be offered call completion service. 01092 * 01093 * \param caller_chan The calling channel 01094 * \retval -1 Error 01095 * \retval 0 Success 01096 */ 01097 int ast_cc_offer(struct ast_channel *caller_chan); 01098 01099 /*! 01100 * \since 1.8 01101 * \brief Accept inbound CC request 01102 * 01103 * \details 01104 * When a caller requests CC, this function should be called to let 01105 * the core know that the request has been accepted. 01106 * 01107 * \param core_id core_id of the CC transaction 01108 * \param debug optional string to print for debugging purposes 01109 * \retval 0 Success 01110 * \retval -1 Failure 01111 */ 01112 int __attribute__((format(printf, 2, 3))) ast_cc_agent_accept_request(int core_id, const char * const debug, ...); 01113 01114 /*! 01115 * \since 1.8 01116 * \brief Indicate that an outbound entity has accepted our CC request 01117 * 01118 * \details 01119 * When we receive confirmation that an outbound device has accepted the 01120 * CC request we sent it, this function must be called. 01121 * 01122 * \param core_id core_id of the CC transaction 01123 * \param debug optional string to print for debugging purposes 01124 * \retval 0 Success 01125 * \retval -1 Failure 01126 */ 01127 int __attribute__((format(printf, 2, 3))) ast_cc_monitor_request_acked(int core_id, const char * const debug, ...); 01128 01129 /*! 01130 * \since 1.8 01131 * \brief Indicate that the caller is busy 01132 * 01133 * \details 01134 * When the callee makes it known that he is available, the core 01135 * will let the caller's channel driver know that it may attempt 01136 * to let the caller know to attempt a recall. If the channel 01137 * driver can detect, though, that the caller is busy, then 01138 * the channel driver should call this function to let the CC 01139 * core know. 01140 * 01141 * \param core_id core_id of the CC transaction 01142 * \param debug optional string to print for debugging purposes 01143 * \retval 0 Success 01144 * \retval -1 Failure 01145 */ 01146 int __attribute__((format(printf, 2, 3))) ast_cc_agent_caller_busy(int core_id, const char * const debug, ...); 01147 01148 /*! 01149 * \since 1.8 01150 * \brief Indicate that a previously unavailable caller has become available 01151 * 01152 * \details 01153 * If a monitor is suspended due to a caller becoming unavailable, then this 01154 * function should be called to indicate that the caller has become available. 01155 * 01156 * \param core_id core_id of the CC transaction 01157 * \param debug optional string to print for debugging purposes 01158 * \retval 0 Success 01159 * \retval -1 Failure 01160 */ 01161 int __attribute__((format(printf, 2, 3))) ast_cc_agent_caller_available(int core_id, const char * const debug, ...); 01162 01163 /*! 01164 * \since 1.8 01165 * \brief Tell the CC core that a caller is currently recalling 01166 * 01167 * \details 01168 * The main purpose of this is so that the core can alert the monitor 01169 * to stop its available timer since the caller has begun its recall 01170 * phase. 01171 * 01172 * \param core_id core_id of the CC transaction 01173 * \param debug optional string to print for debugging purposes 01174 * \retval 0 Success 01175 * \retval -1 Failure 01176 */ 01177 int __attribute__((format(printf, 2, 3))) ast_cc_agent_recalling(int core_id, const char * const debug, ...); 01178 01179 /*! 01180 * \since 1.8 01181 * \brief Indicate recall has been acknowledged 01182 * 01183 * \details 01184 * When we receive confirmation that an endpoint has responded to our 01185 * CC recall, we call this function. 01186 * 01187 * \param chan The inbound channel making the CC recall 01188 * \param debug optional string to print for debugging purposes 01189 * \retval 0 Success 01190 * \retval -1 Failure 01191 */ 01192 int __attribute__((format(printf, 2, 3))) ast_cc_completed(struct ast_channel *chan, const char * const debug, ...); 01193 01194 /*! 01195 * \since 1.8 01196 * \brief Indicate failure has occurred 01197 * 01198 * \details 01199 * If at any point a failure occurs, this is the function to call 01200 * so that the core can initiate cleanup procedures. 01201 * 01202 * \param core_id core_id of the CC transaction 01203 * \param debug optional string to print for debugging purposes 01204 * \retval 0 Success 01205 * \retval -1 Failure 01206 */ 01207 int __attribute__((format(printf, 2, 3))) ast_cc_failed(int core_id, const char * const debug, ...); 01208 01209 /*! 01210 * \since 1.8 01211 * \brief Indicate that a failure has occurred on a specific monitor 01212 * 01213 * \details 01214 * If a monitor should detect that a failure has occurred when communicating 01215 * with its endpoint, then ast_cc_monitor_failed should be called. The big 01216 * difference between ast_cc_monitor_failed and ast_cc_failed is that ast_cc_failed 01217 * indicates a global failure for a CC transaction, where as ast_cc_monitor_failed 01218 * is localized to a particular monitor. When ast_cc_failed is called, the entire 01219 * CC transaction is torn down. When ast_cc_monitor_failed is called, only the 01220 * monitor on which the failure occurred is pruned from the tree of monitors. 01221 * 01222 * If there are no more devices left to monitor when this function is called, 01223 * then the core will fail the CC transaction globally. 01224 * 01225 * \param core_id The core ID for the CC transaction 01226 * \param monitor_name The name of the monitor on which the failure occurred 01227 * \param debug A debug message to print to the CC log 01228 * \return void 01229 */ 01230 int __attribute__((format(printf, 3, 4))) ast_cc_monitor_failed(int core_id, const char * const monitor_name, const char * const debug, ...); 01231 01232 /* END STATE CHANGE API */ 01233 01234 /*! 01235 * The following are all functions which are required due to the unique 01236 * case where Asterisk is acting as the NT side of an ISDN PTMP 01237 * connection to the caller and as the TE side of an ISDN PTMP connection 01238 * to the callee. In such a case, there are several times where the 01239 * PTMP monitor needs information from the agent in order to formulate 01240 * the appropriate messages to send. 01241 */ 01242 01243 /*! 01244 * \brief Request the status of a caller or callers. 01245 * 01246 * \details 01247 * When an ISDN PTMP monitor senses that the callee has become 01248 * available, it needs to know the current status of the caller 01249 * in order to determine the appropriate response to send to 01250 * the caller. In order to do this, the monitor calls this function. 01251 * Responses will arrive asynchronously. 01252 * 01253 * \note Zero or more responses may come as a result. 01254 * 01255 * \param core_id The core ID of the CC transaction 01256 * 01257 * \retval 0 Successfully requested status 01258 * \retval -1 Failed to request status 01259 */ 01260 int ast_cc_monitor_status_request(int core_id); 01261 01262 /*! 01263 * \brief Response with a caller's current status 01264 * 01265 * \details 01266 * When an ISDN PTMP monitor requests the caller's status, the 01267 * agent must respond to the request using this function. For 01268 * simplicity it is recommended that the devstate parameter 01269 * be one of AST_DEVICE_INUSE or AST_DEVICE_NOT_INUSE. 01270 * 01271 * \param core_id The core ID of the CC transaction 01272 * \param devstate The current state of the caller to which the agent pertains 01273 * \retval 0 Successfully responded with our status 01274 * \retval -1 Failed to respond with our status 01275 */ 01276 int ast_cc_agent_status_response(int core_id, enum ast_device_state devstate); 01277 01278 /*! 01279 * \brief Alert a caller to stop ringing 01280 * 01281 * \details 01282 * When an ISDN PTMP monitor becomes available, it is assumed 01283 * that the agent will then cause the caller's phone to ring. In 01284 * some cases, this is literally what happens. In other cases, it may 01285 * be that the caller gets a visible indication on his phone that he 01286 * may attempt to recall the callee. If multiple callers are recalled 01287 * (since it may be possible to have a group of callers configured as 01288 * a single party A), and one of those callers picks up his phone, then 01289 * the ISDN PTMP monitor will alert the other callers to stop ringing. 01290 * The agent's stop_ringing callback will be called, and it is up to the 01291 * agent's driver to send an appropriate message to make his caller 01292 * stop ringing. 01293 * 01294 * \param core_id The core ID of the CC transaction 01295 * \retval 0 Successfully requested for the phone to stop ringing 01296 * \retval -1 Could not request for the phone to stop ringing 01297 */ 01298 int ast_cc_monitor_stop_ringing(int core_id); 01299 01300 /*! 01301 * \brief Alert a caller that though the callee has become free, the caller 01302 * himself is not and may not call back. 01303 * 01304 * \details 01305 * When an ISDN PTMP monitor senses that his monitored party has become 01306 * available, he will request the status of the called party. If he determines 01307 * that the caller is currently not available, then he will call this function 01308 * so that an appropriate message is sent to the caller. 01309 * 01310 * Yes, you just read that correctly. The callee asks the caller what his 01311 * current status is, and if the caller is currently unavailable, the monitor 01312 * must send him a message anyway. WTF? 01313 * 01314 * This function results in the agent's party_b_free callback being called. 01315 * It is most likely that you will not need to actually implement the 01316 * party_b_free callback in an agent because it is not likely that you will 01317 * need to or even want to send a caller a message indicating the callee's 01318 * status if the caller himself is not also free. 01319 * 01320 * \param core_id The core ID of the CC transaction 01321 * \retval 0 Successfully alerted the core that party B is free 01322 * \retval -1 Could not alert the core that party B is free 01323 */ 01324 int ast_cc_monitor_party_b_free(int core_id); 01325 01326 /* BEGIN API FOR USE WITH/BY MONITORS */ 01327 01328 /*! 01329 * \since 1.8 01330 * \brief Return the number of outstanding CC requests to a specific device 01331 * 01332 * \note 01333 * This function will lock the list of monitors stored on every instance of 01334 * the CC core. Callers of this function should be aware of this and avoid 01335 * any potential lock ordering problems. 01336 * 01337 * \param name The name of the monitored device 01338 * \param type The type of the monitored device (e.g. "generic") 01339 * \return The number of CC requests for the monitor 01340 */ 01341 int ast_cc_monitor_count(const char * const name, const char * const type); 01342 01343 /*! 01344 * \since 1.8 01345 * \brief Alert the core that a device being monitored has become available. 01346 * 01347 * \note 01348 * The code in the core will take care of making sure that the information gets passed 01349 * up the ladder correctly. 01350 * 01351 * \param core_id The core ID of the corresponding CC transaction 01352 * \param debug 01353 * \retval 0 Request successfully queued 01354 * \retval -1 Request could not be queued 01355 */ 01356 int __attribute__((format(printf, 2, 3))) ast_cc_monitor_callee_available(const int core_id, const char * const debug, ...); 01357 01358 /* END API FOR USE WITH/BY MONITORS */ 01359 01360 /* BEGIN API TO BE USED ON CC RECALL */ 01361 01362 /*! 01363 * \since 1.8 01364 * \brief Set up a CC recall datastore on a channel 01365 * 01366 * \details 01367 * Implementers of protocol-specific CC agents will need to call this 01368 * function in order for the channel to have the necessary interfaces 01369 * to recall. 01370 * 01371 * This function must be called by the implementer once it has been detected 01372 * that an inbound call is a cc_recall. After allocating the channel, call this 01373 * function, followed by ast_cc_set_cc_interfaces_chanvar. While it would be nice to 01374 * be able to have the core do this automatically, it just cannot be done given 01375 * the current architecture. 01376 */ 01377 int ast_setup_cc_recall_datastore(struct ast_channel *chan, const int core_id); 01378 01379 /*! 01380 * \since 1.8 01381 * \brief Decide if a call to a particular channel is a CC recall 01382 * 01383 * \details 01384 * When a CC recall happens, it is important on the called side to 01385 * know that the call is a CC recall and not a normal call. This function 01386 * will determine first if the call in question is a CC recall. Then it 01387 * will determine based on the chan parameter if the channel is being 01388 * called is being recalled. 01389 * 01390 * As a quick example, let's say a call is placed to SIP/1000 and SIP/1000 01391 * is currently on the phone. The caller requests CCBS. SIP/1000 finishes 01392 * his call, and so the caller attempts to recall. Now, the dialplan 01393 * administrator has set up this second call so that not only is SIP/1000 01394 * called, but also SIP/2000 is called. If SIP/1000's channel were passed 01395 * to this function, the return value would be non-zero, but if SIP/2000's 01396 * channel were passed into this function, then the return would be 0 since 01397 * SIP/2000 was not one of the original devices dialed. 01398 * 01399 * \note 01400 * This function may be called on a calling channel as well to 01401 * determine if it is part of a CC recall. 01402 * 01403 * \note 01404 * This function will lock the channel as well as the list of monitors 01405 * on the channel datastore, though the locks are not held at the same time. Be 01406 * sure that you have no potential lock order issues here. 01407 * 01408 * \param chan The channel to check 01409 * \param[out] core_id If this is a valid CC recall, the core_id of the failed call 01410 * will be placed in this output parameter 01411 * \param monitor_type Clarify which type of monitor type we are looking for if this 01412 * is happening on a called channel. For incoming channels, this parameter is not used. 01413 * \retval 0 Either this is not a recall or it is but this channel is not part of the recall 01414 * \retval non-zero This is a recall and the channel in question is directly involved. 01415 */ 01416 int ast_cc_is_recall(struct ast_channel *chan, int *core_id, const char * const monitor_type); 01417 01418 /*! 01419 * \since 1.8 01420 * \brief Get the associated monitor given the device name and core_id 01421 * 01422 * \details 01423 * The function ast_cc_is_recall is helpful for determining if a call to 01424 * a specific channel is a recall. However, once you have determined that 01425 * this is a recall, you will most likely need access to the private data 01426 * within the associated monitor. This function is what one uses to get 01427 * that monitor. 01428 * 01429 * \note 01430 * This function locks the list of monitors that correspond to the core_id 01431 * passed in. Be sure that you have no potential lock order issues when 01432 * calling this function. 01433 * 01434 * \param core_id The core ID to which this recall corresponds. This likely will 01435 * have been obtained using the ast_cc_is_recall function 01436 * \param device_name Which device to find the monitor for. 01437 * 01438 * \retval NULL Appropriate monitor does not exist 01439 * \retval non-NULL The monitor to use for this recall 01440 */ 01441 struct ast_cc_monitor *ast_cc_get_monitor_by_recall_core_id(const int core_id, const char * const device_name); 01442 01443 /*! 01444 * \since 1.8 01445 * \brief Set the first level CC_INTERFACES channel variable for a channel. 01446 * 01447 * \note 01448 * Implementers of protocol-specific CC agents should call this function after 01449 * calling ast_setup_cc_recall_datastore. 01450 * 01451 * \note 01452 * This function will lock the channel as well as the list of monitors stored 01453 * on the channel's CC recall datastore, though neither are held at the same 01454 * time. Callers of this function should be aware of potential lock ordering 01455 * problems that may arise. 01456 * 01457 * \details 01458 * The CC_INTERFACES channel variable will have the interfaces that should be 01459 * called back for a specific PBX instance. 01460 * 01461 * \param chan The channel to set the CC_INTERFACES variable on 01462 */ 01463 int ast_cc_agent_set_interfaces_chanvar(struct ast_channel *chan); 01464 01465 /*! 01466 * \since 1.8 01467 * \brief Set the CC_INTERFACES channel variable for a channel using an 01468 * extension@context as a starting point 01469 * 01470 * \details 01471 * The CC_INTERFACES channel variable will have the interfaces that should be 01472 * called back for a specific PBX instance. This version of the function is used 01473 * mainly by chan_local, wherein we need to set CC_INTERFACES based on an extension 01474 * and context that appear in the middle of the tree of dialed interfaces 01475 * 01476 * \note 01477 * This function will lock the channel as well as the list of monitors stored 01478 * on the channel's CC recall datastore, though neither are held at the same 01479 * time. Callers of this function should be aware of potential lock ordering 01480 * problems that may arise. 01481 * 01482 * \param chan The channel to set the CC_INTERFACES variable on 01483 * \param extension The name of the extension for which we're setting the variable. 01484 * This should be in the form of "exten@context" 01485 */ 01486 int ast_set_cc_interfaces_chanvar(struct ast_channel *chan, const char * const extension); 01487 01488 /*! 01489 * \since 1.8 01490 * \brief Make CCBS available in the case that ast_call fails 01491 * 01492 * In some situations, notably if a call-limit is reached in SIP, ast_call will fail 01493 * due to Asterisk's knowing that the desired device is currently busy. In such a situation, 01494 * CCBS should be made available to the caller. 01495 * 01496 * One caveat is that this may only be used if generic monitoring is being used. The reason 01497 * is that since Asterisk determined that the device was busy without actually placing a call to it, 01498 * the far end will have no idea what call we are requesting call completion for if we were to send 01499 * a call completion request. 01500 */ 01501 void ast_cc_call_failed(struct ast_channel *incoming, struct ast_channel *outgoing, const char * const dialstring); 01502 01503 /*! 01504 * \since 1.8 01505 * \brief Callback made from ast_cc_callback for certain channel types 01506 * 01507 * \param inbound Incoming asterisk channel. 01508 * \param cc_params The CC configuration parameters for the outbound target 01509 * \param monitor_type The type of monitor to use when CC is requested 01510 * \param device_name The name of the outbound target device. 01511 * \param dialstring The dial string used when calling this specific interface 01512 * \param private_data If a native monitor is being used, and some channel-driver-specific private 01513 * data has been allocated, then this parameter should contain a pointer to that data. If using a generic 01514 * monitor, this parameter should remain NULL. Note that if this function should fail at some point, 01515 * it is the responsibility of the caller to free the private data upon return. 01516 * 01517 * \details 01518 * For channel types that fail ast_request when the device is busy, we call into the 01519 * channel driver with ast_cc_callback. This is the callback that is called in that 01520 * case for each device found which could have been returned by ast_request. 01521 * 01522 * This function creates a CC control frame payload, simulating the act of reading 01523 * it from the nonexistent outgoing channel's frame queue. We then handle this 01524 * simulated frame just as we would a normal CC frame which had actually been queued 01525 * by the channel driver. 01526 */ 01527 void ast_cc_busy_interface(struct ast_channel *inbound, struct ast_cc_config_params *cc_params, 01528 const char *monitor_type, const char * const device_name, const char * const dialstring, void *private_data); 01529 01530 /*! 01531 * \since 1.8 01532 * \brief Create a CC Control frame 01533 * 01534 * \details 01535 * chan_dahdi is weird. It doesn't seem to actually queue frames when it needs to tell 01536 * an application something. Instead it wakes up, tells the application that it has data 01537 * ready, and then based on set flags, creates the proper frame type. For chan_dahdi, we 01538 * provide this function. It provides us the data we need, and we'll make its frame for it. 01539 * 01540 * \param chan A channel involved in the call. What we want is on a datastore on both incoming 01541 * and outgoing so either may be provided 01542 * \param cc_params The CC configuration parameters for the outbound target 01543 * \param monitor_type The type of monitor to use when CC is requested 01544 * \param device_name The name of the outbound target device. 01545 * \param dialstring The dial string used when calling this specific interface 01546 * \param service What kind of CC service is being offered. (CCBS/CCNR/etc...) 01547 * \param private_data If a native monitor is being used, and some channel-driver-specific private 01548 * data has been allocated, then this parameter should contain a pointer to that data. If using a generic 01549 * monitor, this parameter should remain NULL. Note that if this function should fail at some point, 01550 * it is the responsibility of the caller to free the private data upon return. 01551 * \param[out] frame The frame we will be returning to the caller. It is vital that ast_frame_free be 01552 * called on this frame since the payload will be allocated on the heap. 01553 * \retval -1 Failure. At some point there was a failure. Do not attempt to use the frame in this case. 01554 * \retval 0 Success 01555 */ 01556 int ast_cc_build_frame(struct ast_channel *chan, struct ast_cc_config_params *cc_params, 01557 const char *monitor_type, const char * const device_name, 01558 const char * const dialstring, enum ast_cc_service_type service, void *private_data, 01559 struct ast_frame *frame); 01560 01561 01562 /*! 01563 * \brief Callback made from ast_cc_callback for certain channel types 01564 * \since 1.8 01565 * 01566 * \param chan A channel involved in the call. What we want is on a datastore on both incoming and outgoing so either may be provided 01567 * \param cc_params The CC configuration parameters for the outbound target 01568 * \param monitor_type The type of monitor to use when CC is requested 01569 * \param device_name The name of the outbound target device. 01570 * \param dialstring The dial string used when calling this specific interface 01571 * \param private_data If a native monitor is being used, and some channel-driver-specific private 01572 * data has been allocated, then this parameter should contain a pointer to that data. If using a generic 01573 * monitor, this parameter should remain NULL. Note that if this function should fail at some point, 01574 * it is the responsibility of the caller to free the private data upon return. 01575 * 01576 * \details 01577 * For channel types that fail ast_request when the device is busy, we call into the 01578 * channel driver with ast_cc_callback. This is the callback that is called in that 01579 * case for each device found which could have been returned by ast_request. 01580 * 01581 * \return Nothing 01582 */ 01583 typedef void (*ast_cc_callback_fn)(struct ast_channel *chan, struct ast_cc_config_params *cc_params, 01584 const char *monitor_type, const char * const device_name, const char * const dialstring, void *private_data); 01585 01586 /*! 01587 * \since 1.8 01588 * \brief Run a callback for potential matching destinations. 01589 * 01590 * \note 01591 * See the explanation in ast_channel_tech::cc_callback for more 01592 * details. 01593 * 01594 * \param inbound 01595 * \param tech Channel technology to use 01596 * \param dest Channel/group/peer or whatever the specific technology uses 01597 * \param callback Function to call when a target is reached 01598 * \retval Always 0, I guess. 01599 */ 01600 int ast_cc_callback(struct ast_channel *inbound, const char * const tech, const char * const dest, ast_cc_callback_fn callback); 01601 01602 /*! 01603 * \since 1.8 01604 * \brief Initialize CCSS 01605 * 01606 * Performs startup routines necessary for CC operation. 01607 * 01608 * \retval 0 Success 01609 * \retval nonzero Failure 01610 */ 01611 int ast_cc_init(void); 01612 01613 #endif /* _ASTERISK_CCSS_H */