Mon Oct 8 12:38:58 2012

Asterisk developer's documentation


ccss.h

Go to the documentation of this file.
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 */

Generated on Mon Oct 8 12:38:58 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7