Wed Apr 6 11:29:40 2011

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 struct ast_cc_agent_callbacks {
00862    /*!
00863     * \brief Type of agent the callbacks belong to.
00864     *
00865     * \note
00866     * Examples are "SIP" "ISDN" and "generic"
00867     */
00868    const char *type;
00869    /*!
00870     * \brief CC agent initialization.
00871     *
00872     * \param agent CC core agent control.
00873     * \param chan Original channel the agent will attempt to recall.
00874     *
00875     * \details
00876     * This callback is called when the CC core
00877     * is initialized. Agents should allocate
00878     * any private data necessary for the
00879     * call and assign it to the private_data
00880     * on the agent. Additionally, if any ast_cc_agent_flags
00881     * are pertinent to the specific agent type, they should
00882     * be set in this function as well.
00883     *
00884     * \retval 0 on success.
00885     * \retval -1 on error.
00886     */
00887    int (*init)(struct ast_cc_agent *agent, struct ast_channel *chan);
00888    /*!
00889     * \brief Start the offer timer.
00890     *
00891     * \param agent CC core agent control.
00892     *
00893     * \details
00894     * This is called by the core when the caller hangs up after
00895     * a call for which CC may be requested. The agent should
00896     * begin the timer as configured.
00897     *
00898     * The primary reason why this functionality is left to
00899     * the specific agent implementations is due to the differing
00900     * use of schedulers throughout the code. Some channel drivers
00901     * may already have a scheduler context they wish to use, and
00902     * amongst those, some may use the ast_sched API while others
00903     * may use the ast_sched_thread API, which are incompatible.
00904     *
00905     * \retval 0 on success.
00906     * \retval -1 on error.
00907     */
00908    int (*start_offer_timer)(struct ast_cc_agent *agent);
00909    /*!
00910     * \brief Stop the offer timer.
00911     *
00912     * \param agent CC core agent control.
00913     *
00914     * \details
00915     * This callback is called by the CC core when the caller
00916     * has requested CC.
00917     *
00918     * \retval 0 on success.
00919     * \retval -1 on error.
00920     */
00921    int (*stop_offer_timer)(struct ast_cc_agent *agent);
00922    /*!
00923     * \brief Acknowledge CC request.
00924     *
00925     * \param agent CC core agent control.
00926     *
00927     * \details
00928     * When the core receives knowledge that a called
00929     * party has accepted a CC request, it will call
00930     * this callback.
00931     *
00932     * The duty of this is to accept a CC request from
00933     * the caller by acknowledging receipt of that request.
00934     */
00935    void (*ack)(struct ast_cc_agent *agent);
00936    /*!
00937     * \brief Request the status of the agent's device.
00938     *
00939     * \param agent CC core agent control.
00940     *
00941     * \details
00942     * Asynchronous request for the status of any caller
00943     * which may be a valid caller for the CC transaction.
00944     * Status responses should be made using the
00945     * ast_cc_status_response function.
00946     *
00947     * \retval 0 on success.
00948     * \retval -1 on error.
00949     */
00950    int (*status_request)(struct ast_cc_agent *agent);
00951    /*!
00952     * \brief Request for an agent's phone to stop ringing.
00953     *
00954     * \param agent CC core agent control.
00955     *
00956     * \details
00957     * The usefulness of this is quite limited. The only specific
00958     * known case for this is if Asterisk requests CC over an ISDN
00959     * PTMP link as the TE side. If other phones are in the same
00960     * recall group as the Asterisk server, and one of those phones
00961     * picks up the recall notice, then Asterisk will receive a
00962     * "stop ringing" notification from the NT side of the PTMP
00963     * link. This indication needs to be passed to the phone
00964     * on the other side of the Asterisk server which originally
00965     * placed the call so that it will stop ringing. Since the
00966     * phone may be of any type, it is necessary to have a callback
00967     * that the core can know about.
00968     *
00969     * \retval 0 on success.
00970     * \retval -1 on error.
00971     */
00972    int (*stop_ringing)(struct ast_cc_agent *agent);
00973    /*!
00974     * \brief Let the caller know that the callee has become free
00975     * but that the caller cannot attempt to call back because
00976     * he is either busy or there is congestion on his line.
00977     *
00978     * \param agent CC core agent control.
00979     *
00980     * \details
00981     * This is something that really only affects a scenario where
00982     * a phone places a call over ISDN PTMP to Asterisk, who then
00983     * connects over PTMP again to the ISDN network. For most agent
00984     * types, there is no need to implement this callback at all
00985     * because they don't really need to actually do anything in
00986     * this situation. If you're having trouble understanding what
00987     * the purpose of this callback is, then you can be safe simply
00988     * not implementing it.
00989     *
00990     * \retval 0 on success.
00991     * \retval -1 on error.
00992     */
00993    int (*party_b_free)(struct ast_cc_agent *agent);
00994    /*!
00995     * \brief Begin monitoring a busy device.
00996     *
00997     * \param agent CC core agent control.
00998     *
00999     * \details
01000     * The core will call this callback if the callee becomes
01001     * available but the caller has reported that he is busy.
01002     * The agent should begin monitoring the caller's device.
01003     * When the caller becomes available again, the agent should
01004     * call ast_cc_agent_caller_available.
01005     *
01006     * \retval 0 on success.
01007     * \retval -1 on error.
01008     */
01009    int (*start_monitoring)(struct ast_cc_agent *agent);
01010    /*!
01011     * \brief Alert the caller that it is time to try recalling.
01012     *
01013     * \param agent CC core agent control.
01014     *
01015     * \details
01016     * The core will call this function when it receives notice
01017     * that a monitored party has become available.
01018     *
01019     * The agent's job is to send a message to the caller to
01020     * notify it of such a change. If the agent is able to
01021     * discern that the caller is currently unavailable, then
01022     * the agent should react by calling the ast_cc_caller_unavailable
01023     * function.
01024     *
01025     * \retval 0 on success.
01026     * \retval -1 on error.
01027     */
01028    int (*callee_available)(struct ast_cc_agent *agent);
01029    /*!
01030     * \brief Destroy private data on the agent.
01031     *
01032     * \param agent CC core agent control.
01033     *
01034     * \details
01035     * The core will call this function upon completion
01036     * or failure of CC.
01037     *
01038     * \note
01039     * The agent private_data pointer may be NULL if the agent
01040     * constructor failed.
01041     */
01042    void (*destructor)(struct ast_cc_agent *agent);
01043 };
01044 
01045 /*!
01046  * \brief Call a callback on all agents of a specific type
01047  *
01048  * \details
01049  * Since the container of CC core instances is private, and so
01050  * are the items which the container contains, we have to provide
01051  * an ao2_callback-like method so that a specific agent may be
01052  * found or so that an operation can be made on all agents of
01053  * a particular type. The first three arguments should be familiar
01054  * to anyone who has used ao2_callback. The final argument is the
01055  * type of agent you wish to have the callback called on.
01056  *
01057  * \note Since agents are refcounted, and this function returns
01058  * a reference to the agent, it is imperative that you decrement
01059  * the refcount of the agent once you have finished using it.
01060  *
01061  * \param flags astobj2 search flags
01062  * \param function an ao2 callback function to call
01063  * \param arg the argument to the callback function
01064  * \param type The type of agents to call the callback on
01065  */
01066 struct ast_cc_agent *ast_cc_agent_callback(int flags, ao2_callback_fn *function, void *arg, const char * const type);
01067 
01068 /* END STRUCTURES FOR AGENTS */
01069 
01070 /* BEGIN STATE CHANGE API */
01071 
01072 /*!
01073  * \since 1.8
01074  * \brief Offer CC to a caller
01075  *
01076  * \details
01077  * This function is called from ast_hangup if the caller is
01078  * eligible to be offered call completion service.
01079  *
01080  * \param caller_chan The calling channel
01081  * \retval -1 Error
01082  * \retval 0 Success
01083  */
01084 int ast_cc_offer(struct ast_channel *caller_chan);
01085 
01086 /*!
01087  * \since 1.8
01088  * \brief Accept inbound CC request
01089  *
01090  * \details
01091  * When a caller requests CC, this function should be called to let
01092  * the core know that the request has been accepted.
01093  *
01094  * \param core_id core_id of the CC transaction
01095  * \param debug optional string to print for debugging purposes
01096  * \retval 0 Success
01097  * \retval -1 Failure
01098  */
01099 int __attribute__((format(printf, 2, 3))) ast_cc_agent_accept_request(int core_id, const char * const debug, ...);
01100 
01101 /*!
01102  * \since 1.8
01103  * \brief Indicate that an outbound entity has accepted our CC request
01104  *
01105  * \details
01106  * When we receive confirmation that an outbound device has accepted the
01107  * CC request we sent it, this function must be called.
01108  *
01109  * \param core_id core_id of the CC transaction
01110  * \param debug optional string to print for debugging purposes
01111  * \retval 0 Success
01112  * \retval -1 Failure
01113  */
01114 int __attribute__((format(printf, 2, 3))) ast_cc_monitor_request_acked(int core_id, const char * const debug, ...);
01115 
01116 /*!
01117  * \since 1.8
01118  * \brief Indicate that the caller is busy
01119  *
01120  * \details
01121  * When the callee makes it known that he is available, the core
01122  * will let the caller's channel driver know that it may attempt
01123  * to let the caller know to attempt a recall. If the channel
01124  * driver can detect, though, that the caller is busy, then
01125  * the channel driver should call this function to let the CC
01126  * core know.
01127  *
01128  * \param core_id core_id of the CC transaction
01129  * \param debug optional string to print for debugging purposes
01130  * \retval 0 Success
01131  * \retval -1 Failure
01132  */
01133 int __attribute__((format(printf, 2, 3))) ast_cc_agent_caller_busy(int core_id, const char * const debug, ...);
01134 
01135 /*!
01136  * \since 1.8
01137  * \brief Indicate that a previously unavailable caller has become available
01138  *
01139  * \details
01140  * If a monitor is suspended due to a caller becoming unavailable, then this
01141  * function should be called to indicate that the caller has become available.
01142  *
01143  * \param core_id core_id of the CC transaction
01144  * \param debug optional string to print for debugging purposes
01145  * \retval 0 Success
01146  * \retval -1 Failure
01147  */
01148 int __attribute__((format(printf, 2, 3))) ast_cc_agent_caller_available(int core_id, const char * const debug, ...);
01149 
01150 /*!
01151  * \since 1.8
01152  * \brief Tell the CC core that a caller is currently recalling
01153  *
01154  * \details
01155  * The main purpose of this is so that the core can alert the monitor
01156  * to stop its available timer since the caller has begun its recall
01157  * phase.
01158  *
01159  * \param core_id core_id of the CC transaction
01160  * \param debug optional string to print for debugging purposes
01161  * \retval 0 Success
01162  * \retval -1 Failure
01163  */
01164 int __attribute__((format(printf, 2, 3))) ast_cc_agent_recalling(int core_id, const char * const debug, ...);
01165 
01166 /*!
01167  * \since 1.8
01168  * \brief Indicate recall has been acknowledged
01169  *
01170  * \details
01171  * When we receive confirmation that an endpoint has responded to our
01172  * CC recall, we call this function.
01173  *
01174  * \param chan The inbound channel making the CC recall
01175  * \param debug optional string to print for debugging purposes
01176  * \retval 0 Success
01177  * \retval -1 Failure
01178  */
01179 int __attribute__((format(printf, 2, 3))) ast_cc_completed(struct ast_channel *chan, const char * const debug, ...);
01180 
01181 /*!
01182  * \since 1.8
01183  * \brief Indicate failure has occurred
01184  *
01185  * \details
01186  * If at any point a failure occurs, this is the function to call
01187  * so that the core can initiate cleanup procedures.
01188  *
01189  * \param core_id core_id of the CC transaction
01190  * \param debug optional string to print for debugging purposes
01191  * \retval 0 Success
01192  * \retval -1 Failure
01193  */
01194 int __attribute__((format(printf, 2, 3))) ast_cc_failed(int core_id, const char * const debug, ...);
01195 
01196 /*!
01197  * \since 1.8
01198  * \brief Indicate that a failure has occurred on a specific monitor
01199  *
01200  * \details
01201  * If a monitor should detect that a failure has occurred when communicating
01202  * with its endpoint, then ast_cc_monitor_failed should be called. The big
01203  * difference between ast_cc_monitor_failed and ast_cc_failed is that ast_cc_failed
01204  * indicates a global failure for a CC transaction, where as ast_cc_monitor_failed
01205  * is localized to a particular monitor. When ast_cc_failed is called, the entire
01206  * CC transaction is torn down. When ast_cc_monitor_failed is called, only the
01207  * monitor on which the failure occurred is pruned from the tree of monitors.
01208  *
01209  * If there are no more devices left to monitor when this function is called,
01210  * then the core will fail the CC transaction globally.
01211  *
01212  * \param core_id The core ID for the CC transaction
01213  * \param monitor_name The name of the monitor on which the failure occurred
01214  * \param debug A debug message to print to the CC log
01215  * \return void
01216  */
01217 int __attribute__((format(printf, 3, 4))) ast_cc_monitor_failed(int core_id, const char * const monitor_name, const char * const debug, ...);
01218 
01219 /* END STATE CHANGE API */
01220 
01221 /*!
01222  * The following are all functions which are required due to the unique
01223  * case where Asterisk is acting as the NT side of an ISDN PTMP
01224  * connection to the caller and as the TE side of an ISDN PTMP connection
01225  * to the callee. In such a case, there are several times where the
01226  * PTMP monitor needs information from the agent in order to formulate
01227  * the appropriate messages to send.
01228  */
01229 
01230 /*!
01231  * \brief Request the status of a caller or callers.
01232  *
01233  * \details
01234  * When an ISDN PTMP monitor senses that the callee has become
01235  * available, it needs to know the current status of the caller
01236  * in order to determine the appropriate response to send to
01237  * the caller. In order to do this, the monitor calls this function.
01238  * Responses will arrive asynchronously.
01239  *
01240  * \note Zero or more responses may come as a result.
01241  *
01242  * \param core_id The core ID of the CC transaction
01243  *
01244  * \retval 0 Successfully requested status
01245  * \retval -1 Failed to request status
01246  */
01247 int ast_cc_monitor_status_request(int core_id);
01248 
01249 /*!
01250  * \brief Response with a caller's current status
01251  *
01252  * \details
01253  * When an ISDN PTMP monitor requests the caller's status, the
01254  * agent must respond to the request using this function. For
01255  * simplicity it is recommended that the devstate parameter
01256  * be one of AST_DEVICE_INUSE or AST_DEVICE_NOT_INUSE.
01257  *
01258  * \param core_id The core ID of the CC transaction
01259  * \param devstate The current state of the caller to which the agent pertains
01260  * \retval 0 Successfully responded with our status
01261  * \retval -1 Failed to respond with our status
01262  */
01263 int ast_cc_agent_status_response(int core_id, enum ast_device_state devstate);
01264 
01265 /*!
01266  * \brief Alert a caller to stop ringing
01267  *
01268  * \details
01269  * When an ISDN PTMP monitor becomes available, it is assumed
01270  * that the agent will then cause the caller's phone to ring. In
01271  * some cases, this is literally what happens. In other cases, it may
01272  * be that the caller gets a visible indication on his phone that he
01273  * may attempt to recall the callee. If multiple callers are recalled
01274  * (since it may be possible to have a group of callers configured as
01275  * a single party A), and one of those callers picks up his phone, then
01276  * the ISDN PTMP monitor will alert the other callers to stop ringing.
01277  * The agent's stop_ringing callback will be called, and it is up to the
01278  * agent's driver to send an appropriate message to make his caller
01279  * stop ringing.
01280  *
01281  * \param core_id The core ID of the CC transaction
01282  * \retval 0 Successfully requested for the phone to stop ringing
01283  * \retval -1 Could not request for the phone to stop ringing
01284  */
01285 int ast_cc_monitor_stop_ringing(int core_id);
01286 
01287 /*!
01288  * \brief Alert a caller that though the callee has become free, the caller
01289  * himself is not and may not call back.
01290  *
01291  * \details
01292  * When an ISDN PTMP monitor senses that his monitored party has become
01293  * available, he will request the status of the called party. If he determines
01294  * that the caller is currently not available, then he will call this function
01295  * so that an appropriate message is sent to the caller.
01296  *
01297  * Yes, you just read that correctly. The callee asks the caller what his
01298  * current status is, and if the caller is currently unavailable, the monitor
01299  * must send him a message anyway. WTF?
01300  *
01301  * This function results in the agent's party_b_free callback being called.
01302  * It is most likely that you will not need to actually implement the
01303  * party_b_free callback in an agent because it is not likely that you will
01304  * need to or even want to send a caller a message indicating the callee's
01305  * status if the caller himself is not also free.
01306  *
01307  * \param core_id The core ID of the CC transaction
01308  * \retval 0 Successfully alerted the core that party B is free
01309  * \retval -1 Could not alert the core that party B is free
01310  */
01311 int ast_cc_monitor_party_b_free(int core_id);
01312 
01313 /* BEGIN API FOR USE WITH/BY MONITORS */
01314 
01315 /*!
01316  * \since 1.8
01317  * \brief Return the number of outstanding CC requests to a specific device
01318  *
01319  * \note
01320  * This function will lock the list of monitors stored on every instance of
01321  * the CC core. Callers of this function should be aware of this and avoid
01322  * any potential lock ordering problems.
01323  *
01324  * \param name The name of the monitored device
01325  * \param type The type of the monitored device (e.g. "generic")
01326  * \return The number of CC requests for the monitor
01327  */
01328 int ast_cc_monitor_count(const char * const name, const char * const type);
01329 
01330 /*!
01331  * \since 1.8
01332  * \brief Alert the core that a device being monitored has become available.
01333  *
01334  * \note
01335  * The code in the core will take care of making sure that the information gets passed
01336  * up the ladder correctly.
01337  *
01338  * \param core_id The core ID of the corresponding CC transaction
01339  * \param debug
01340  * \retval 0 Request successfully queued
01341  * \retval -1 Request could not be queued
01342  */
01343 int __attribute__((format(printf, 2, 3))) ast_cc_monitor_callee_available(const int core_id, const char * const debug, ...);
01344 
01345 /* END API FOR USE WITH/BY MONITORS */
01346 
01347 /* BEGIN API TO BE USED ON CC RECALL */
01348 
01349 /*!
01350  * \since 1.8
01351  * \brief Set up a CC recall datastore on a channel
01352  *
01353  * \details
01354  * Implementers of protocol-specific CC agents will need to call this
01355  * function in order for the channel to have the necessary interfaces
01356  * to recall.
01357  *
01358  * This function must be called by the implementer once it has been detected
01359  * that an inbound call is a cc_recall. After allocating the channel, call this
01360  * function, followed by ast_cc_set_cc_interfaces_chanvar. While it would be nice to
01361  * be able to have the core do this automatically, it just cannot be done given
01362  * the current architecture.
01363  */
01364 int ast_setup_cc_recall_datastore(struct ast_channel *chan, const int core_id);
01365 
01366 /*!
01367  * \since 1.8
01368  * \brief Decide if a call to a particular channel is a CC recall
01369  *
01370  * \details
01371  * When a CC recall happens, it is important on the called side to
01372  * know that the call is a CC recall and not a normal call. This function
01373  * will determine first if the call in question is a CC recall. Then it
01374  * will determine based on the chan parameter if the channel is being
01375  * called is being recalled.
01376  *
01377  * As a quick example, let's say a call is placed to SIP/1000 and SIP/1000
01378  * is currently on the phone. The caller requests CCBS. SIP/1000 finishes
01379  * his call, and so the caller attempts to recall. Now, the dialplan
01380  * administrator has set up this second call so that not only is SIP/1000
01381  * called, but also SIP/2000 is called. If SIP/1000's channel were passed
01382  * to this function, the return value would be non-zero, but if SIP/2000's
01383  * channel were passed into this function, then the return would be 0 since
01384  * SIP/2000 was not one of the original devices dialed.
01385  *
01386  * \note
01387  * This function may be called on a calling channel as well to
01388  * determine if it is part of a CC recall.
01389  *
01390  * \note
01391  * This function will lock the channel as well as the list of monitors
01392  * on the channel datastore, though the locks are not held at the same time. Be
01393  * sure that you have no potential lock order issues here.
01394  *
01395  * \param chan The channel to check
01396  * \param[out] core_id If this is a valid CC recall, the core_id of the failed call
01397  * will be placed in this output parameter
01398  * \param monitor_type Clarify which type of monitor type we are looking for if this
01399  * is happening on a called channel. For incoming channels, this parameter is not used.
01400  * \retval 0 Either this is not a recall or it is but this channel is not part of the recall
01401  * \retval non-zero This is a recall and the channel in question is directly involved.
01402  */
01403 int ast_cc_is_recall(struct ast_channel *chan, int *core_id, const char * const monitor_type);
01404 
01405 /*!
01406  * \since 1.8
01407  * \brief Get the associated monitor given the device name and core_id
01408  *
01409  * \details
01410  * The function ast_cc_is_recall is helpful for determining if a call to
01411  * a specific channel is a recall. However, once you have determined that
01412  * this is a recall, you will most likely need access to the private data
01413  * within the associated monitor. This function is what one uses to get
01414  * that monitor.
01415  *
01416  * \note
01417  * This function locks the list of monitors that correspond to the core_id
01418  * passed in. Be sure that you have no potential lock order issues when
01419  * calling this function.
01420  *
01421  * \param core_id The core ID to which this recall corresponds. This likely will
01422  * have been obtained using the ast_cc_is_recall function
01423  * \param device_name Which device to find the monitor for.
01424  *
01425  * \retval NULL Appropriate monitor does not exist
01426  * \retval non-NULL The monitor to use for this recall
01427  */
01428 struct ast_cc_monitor *ast_cc_get_monitor_by_recall_core_id(const int core_id, const char * const device_name);
01429 
01430 /*!
01431  * \since 1.8
01432  * \brief Set the first level CC_INTERFACES channel variable for a channel.
01433  *
01434  * \note
01435  * Implementers of protocol-specific CC agents should call this function after
01436  * calling ast_setup_cc_recall_datastore.
01437  *
01438  * \note
01439  * This function will lock the channel as well as the list of monitors stored
01440  * on the channel's CC recall datastore, though neither are held at the same
01441  * time. Callers of this function should be aware of potential lock ordering
01442  * problems that may arise.
01443  *
01444  * \details
01445  * The CC_INTERFACES channel variable will have the interfaces that should be
01446  * called back for a specific PBX instance.
01447  *
01448  * \param chan The channel to set the CC_INTERFACES variable on
01449  */
01450 int ast_cc_agent_set_interfaces_chanvar(struct ast_channel *chan);
01451 
01452 /*!
01453  * \since 1.8
01454  * \brief Set the CC_INTERFACES channel variable for a channel using an
01455  * extension@context as a starting point
01456  *
01457  * \details
01458  * The CC_INTERFACES channel variable will have the interfaces that should be
01459  * called back for a specific PBX instance. This version of the function is used
01460  * mainly by chan_local, wherein we need to set CC_INTERFACES based on an extension
01461  * and context that appear in the middle of the tree of dialed interfaces
01462  *
01463  * \note
01464  * This function will lock the channel as well as the list of monitors stored
01465  * on the channel's CC recall datastore, though neither are held at the same
01466  * time. Callers of this function should be aware of potential lock ordering
01467  * problems that may arise.
01468  *
01469  * \param chan The channel to set the CC_INTERFACES variable on
01470  * \param extension The name of the extension for which we're setting the variable.
01471  * This should be in the form of "exten@context"
01472  */
01473 int ast_set_cc_interfaces_chanvar(struct ast_channel *chan, const char * const extension);
01474 
01475 /*!
01476  * \since 1.8
01477  * \brief Make CCBS available in the case that ast_call fails
01478  *
01479  * In some situations, notably if a call-limit is reached in SIP, ast_call will fail
01480  * due to Asterisk's knowing that the desired device is currently busy. In such a situation,
01481  * CCBS should be made available to the caller.
01482  *
01483  * One caveat is that this may only be used if generic monitoring is being used. The reason
01484  * is that since Asterisk determined that the device was busy without actually placing a call to it,
01485  * the far end will have no idea what call we are requesting call completion for if we were to send
01486  * a call completion request.
01487  */
01488 void ast_cc_call_failed(struct ast_channel *incoming, struct ast_channel *outgoing, const char * const dialstring);
01489 
01490 /*!
01491  * \since 1.8
01492  * \brief Callback made from ast_cc_callback for certain channel types
01493  *
01494  * \param inbound Incoming asterisk channel.
01495  * \param cc_params The CC configuration parameters for the outbound target
01496  * \param monitor_type The type of monitor to use when CC is requested
01497  * \param device_name The name of the outbound target device.
01498  * \param dialstring The dial string used when calling this specific interface
01499  * \param private_data If a native monitor is being used, and some channel-driver-specific private
01500  * data has been allocated, then this parameter should contain a pointer to that data. If using a generic
01501  * monitor, this parameter should remain NULL. Note that if this function should fail at some point,
01502  * it is the responsibility of the caller to free the private data upon return.
01503  *
01504  * \details
01505  * For channel types that fail ast_request when the device is busy, we call into the
01506  * channel driver with ast_cc_callback. This is the callback that is called in that
01507  * case for each device found which could have been returned by ast_request.
01508  *
01509  * This function creates a CC control frame payload, simulating the act of reading
01510  * it from the nonexistent outgoing channel's frame queue. We then handle this
01511  * simulated frame just as we would a normal CC frame which had actually been queued
01512  * by the channel driver.
01513  */
01514 void ast_cc_busy_interface(struct ast_channel *inbound, struct ast_cc_config_params *cc_params,
01515    const char *monitor_type, const char * const device_name, const char * const dialstring, void *private_data);
01516 
01517 /*!
01518  * \since 1.8
01519  * \brief Create a CC Control frame
01520  *
01521  * \details
01522  * chan_dahdi is weird. It doesn't seem to actually queue frames when it needs to tell
01523  * an application something. Instead it wakes up, tells the application that it has data
01524  * ready, and then based on set flags, creates the proper frame type. For chan_dahdi, we
01525  * provide this function. It provides us the data we need, and we'll make its frame for it.
01526  *
01527  * \param chan A channel involved in the call. What we want is on a datastore on both incoming 
01528  * and outgoing so either may be provided
01529  * \param cc_params The CC configuration parameters for the outbound target
01530  * \param monitor_type The type of monitor to use when CC is requested
01531  * \param device_name The name of the outbound target device.
01532  * \param dialstring The dial string used when calling this specific interface
01533  * \param service What kind of CC service is being offered. (CCBS/CCNR/etc...)
01534  * \param private_data If a native monitor is being used, and some channel-driver-specific private
01535  * data has been allocated, then this parameter should contain a pointer to that data. If using a generic
01536  * monitor, this parameter should remain NULL. Note that if this function should fail at some point,
01537  * it is the responsibility of the caller to free the private data upon return.
01538  * \param[out] frame The frame we will be returning to the caller. It is vital that ast_frame_free be 
01539  * called on this frame since the payload will be allocated on the heap.
01540  * \retval -1 Failure. At some point there was a failure. Do not attempt to use the frame in this case.
01541  * \retval 0 Success
01542  */
01543 int ast_cc_build_frame(struct ast_channel *chan, struct ast_cc_config_params *cc_params,
01544    const char *monitor_type, const char * const device_name,
01545    const char * const dialstring, enum ast_cc_service_type service, void *private_data,
01546    struct ast_frame *frame);
01547 
01548 
01549 /*!
01550  * \brief Callback made from ast_cc_callback for certain channel types
01551  * \since 1.8
01552  *
01553  * \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
01554  * \param cc_params The CC configuration parameters for the outbound target
01555  * \param monitor_type The type of monitor to use when CC is requested
01556  * \param device_name The name of the outbound target device.
01557  * \param dialstring The dial string used when calling this specific interface
01558  * \param private_data If a native monitor is being used, and some channel-driver-specific private
01559  * data has been allocated, then this parameter should contain a pointer to that data. If using a generic
01560  * monitor, this parameter should remain NULL. Note that if this function should fail at some point,
01561  * it is the responsibility of the caller to free the private data upon return.
01562  *
01563  * \details
01564  * For channel types that fail ast_request when the device is busy, we call into the
01565  * channel driver with ast_cc_callback. This is the callback that is called in that
01566  * case for each device found which could have been returned by ast_request.
01567  *
01568  * \return Nothing
01569  */
01570 typedef void (*ast_cc_callback_fn)(struct ast_channel *chan, struct ast_cc_config_params *cc_params,
01571    const char *monitor_type, const char * const device_name, const char * const dialstring, void *private_data);
01572 
01573 /*!
01574  * \since 1.8
01575  * \brief Run a callback for potential matching destinations.
01576  *
01577  * \note
01578  * See the explanation in ast_channel_tech::cc_callback for more
01579  * details.
01580  *
01581  * \param inbound
01582  * \param tech Channel technology to use
01583  * \param dest Channel/group/peer or whatever the specific technology uses
01584  * \param callback Function to call when a target is reached
01585  * \retval Always 0, I guess.
01586  */
01587 int ast_cc_callback(struct ast_channel *inbound, const char * const tech, const char * const dest, ast_cc_callback_fn callback);
01588 
01589 /*!
01590  * \since 1.8
01591  * \brief Initialize CCSS
01592  *
01593  * Performs startup routines necessary for CC operation.
01594  *
01595  * \retval 0 Success
01596  * \retval nonzero Failure
01597  */
01598 int ast_cc_init(void);
01599 
01600 #endif /* _ASTERISK_CCSS_H */

Generated on Wed Apr 6 11:29:40 2011 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7