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 /*!
00395  * \since 11
00396  * \brief Get the name of the callback subroutine
00397  * \param config The configuration to retrieve the callback_sub from
00398  * \return The callback_sub name
00399  */
00400 const char *ast_get_cc_callback_sub(struct ast_cc_config_params *config);
00401 
00402 /*!
00403  * \since 11
00404  * \brief Set the callback subroutine name
00405  * \param config The configuration to set the callback_sub on
00406  * \param value The new callback subroutine we want to change to
00407  * \retval void
00408  */
00409 void ast_set_cc_callback_sub(struct ast_cc_config_params *config, const char * const value);
00410 
00411 /* END CONFIGURATION FUNCTIONS */
00412 
00413 /* BEGIN AGENT/MONITOR REGISTRATION API */
00414 
00415 struct ast_cc_monitor_callbacks;
00416 
00417 /*!
00418  * \since 1.8
00419  * \brief Register a set of monitor callbacks with the core
00420  *
00421  * \details
00422  * This is made so that at monitor creation time, the proper callbacks
00423  * may be installed and the proper .init callback may be called for the
00424  * monitor to establish private data.
00425  *
00426  * \param callbacks The callbacks used by the monitor implementation
00427  * \retval 0 Successfully registered
00428  * \retval -1 Failure to register
00429  */
00430 int ast_cc_monitor_register(const struct ast_cc_monitor_callbacks *callbacks);
00431 
00432 /*!
00433  * \since 1.8
00434  * \brief Unregister a set of monitor callbacks with the core
00435  *
00436  * \details
00437  * If a module which makes use of a CC monitor is unloaded, then it may
00438  * unregister its monitor callbacks with the core.
00439  *
00440  * \param callbacks The callbacks used by the monitor implementation
00441  * \retval 0 Successfully unregistered
00442  * \retval -1 Failure to unregister
00443  */
00444 void ast_cc_monitor_unregister(const struct ast_cc_monitor_callbacks *callbacks);
00445 
00446 struct ast_cc_agent_callbacks;
00447 
00448 /*!
00449  * \since 1.8
00450  * \brief Register a set of agent callbacks with the core
00451  *
00452  * \details
00453  * This is made so that at agent creation time, the proper callbacks
00454  * may be installed and the proper .init callback may be called for the
00455  * monitor to establish private data.
00456  *
00457  * \param callbacks The callbacks used by the agent implementation
00458  * \retval 0 Successfully registered
00459  * \retval -1 Failure to register
00460  */
00461 int ast_cc_agent_register(const struct ast_cc_agent_callbacks *callbacks);
00462 
00463 /*!
00464  * \since 1.8
00465  * \brief Unregister a set of agent callbacks with the core
00466  *
00467  * \details
00468  * If a module which makes use of a CC agent is unloaded, then it may
00469  * unregister its agent callbacks with the core.
00470  *
00471  * \param callbacks The callbacks used by the agent implementation
00472  * \retval 0 Successfully unregistered
00473  * \retval -1 Failure to unregister
00474  */
00475 void ast_cc_agent_unregister(const struct ast_cc_agent_callbacks *callbacks);
00476 
00477 /* END AGENT/MONITOR REGISTRATION API */
00478 
00479 /* BEGIN SECTION ON MONITORS AND MONITOR CALLBACKS */
00480 
00481 /*!
00482  * It is recommended that monitors use a pointer to
00483  * an ast_cc_monitor_callbacks::type when creating
00484  * an AST_CONTROL_CC frame. Since the generic monitor
00485  * callbacks are opaque and channel drivers will wish
00486  * to use that, this string is made globally available
00487  * for all to use
00488  */
00489 #define AST_CC_GENERIC_MONITOR_TYPE "generic"
00490 
00491 /*!
00492  * Used to determine which type
00493  * of monitor an ast_cc_device_monitor
00494  * is.
00495  */
00496 enum ast_cc_monitor_class {
00497    AST_CC_DEVICE_MONITOR,
00498    AST_CC_EXTENSION_MONITOR,
00499 };
00500 
00501 /*!
00502  * \internal
00503  * \brief An item in a CC interface tree.
00504  *
00505  * These are the individual items in an interface tree.
00506  * The key difference between this structure and the ast_cc_interface
00507  * is that this structure contains data which is intrinsic to the item's
00508  * placement in the tree, such as who its parent is.
00509  */
00510 struct ast_cc_monitor {
00511    /*!
00512     * Information regarding the interface.
00513     */
00514    struct ast_cc_interface *interface;
00515    /*!
00516     * Every interface has an id that uniquely identifies it. It is
00517     * formed by incrementing a counter.
00518     */
00519    unsigned int id;
00520    /*!
00521     * The ID of this monitor's parent. If this monitor is at the
00522     * top of the tree, then his parent will be 0.
00523     */
00524    unsigned int parent_id;
00525    /*!
00526     * The instance of the CC core to which this monitor belongs
00527     */
00528    int core_id;
00529    /*!
00530     * The type of call completion service offered by a device.
00531     */
00532    enum ast_cc_service_type service_offered;
00533    /*!
00534     * \brief Name that should be used to recall specified interface
00535     *
00536     * \details
00537     * When issuing a CC recall, some technologies will require
00538     * that a name other than the device name is dialed. For instance,
00539     * with SIP, a specific URI will be used which chan_sip will be able
00540     * to recognize as being a CC recall. Similarly, ISDN will need a specific
00541     * dial string to know that the call is a recall.
00542     */
00543    char *dialstring;
00544    /*!
00545     * The ID of the available timer used by the current monitor
00546     */
00547    int available_timer_id;
00548    /*!
00549     * Monitor callbacks
00550     */
00551    const struct ast_cc_monitor_callbacks *callbacks;
00552    /*!
00553     * \brief Data that is private to a monitor technology
00554     *
00555     * Most channel drivers that implement CC monitors will have to
00556     * allocate data that the CC core does not care about but which
00557     * is vital to the operation of the monitor. This data is stored
00558     * in this pointer so that the channel driver may use it as
00559     * needed
00560     */
00561    void *private_data;
00562    AST_LIST_ENTRY(ast_cc_monitor) next;
00563 };
00564 
00565 /*!
00566  * \brief Callbacks defined by CC monitors
00567  *
00568  * \note
00569  * Every callback is called with the list of monitors locked. There
00570  * are several public API calls that also will try to lock this lock.
00571  * These public functions have a note in their doxygen stating so.
00572  * As such, pay attention to the lock order you establish in these callbacks
00573  * to ensure that you do not violate the lock order when calling
00574  * the functions in this file with lock order notices.
00575  */
00576 struct ast_cc_monitor_callbacks {
00577    /*!
00578     * \brief Type of monitor the callbacks belong to.
00579     *
00580     * \note
00581     * Examples include "generic" and "SIP"
00582     */
00583    const char *type;
00584    /*!
00585     * \brief Request CCSS.
00586     *
00587     * \param monitor CC core monitor control.
00588     * \param available_timer_id The scheduler ID for the available timer.
00589     * Will never be NULL for a device monitor.
00590     *
00591     * \details
00592     * Perform whatever steps are necessary in order to request CC.
00593     * In addition, the monitor implementation is responsible for
00594     * starting the available timer in this callback.
00595     *
00596     * \retval 0 on success
00597     * \retval -1 on failure.
00598     */
00599    int (*request_cc)(struct ast_cc_monitor *monitor, int *available_timer_id);
00600    /*!
00601     * \brief Suspend monitoring.
00602     *
00603     * \param monitor CC core monitor control.
00604     *
00605     * \details
00606     * Implementers must perform the necessary steps to suspend
00607     * monitoring.
00608     *
00609     * \retval 0 on success
00610     * \retval -1 on failure.
00611     */
00612    int (*suspend)(struct ast_cc_monitor *monitor);
00613    /*!
00614     * \brief Status response to an ast_cc_monitor_status_request().
00615     *
00616     * \param monitor CC core monitor control.
00617     * \param devstate Current status of a Party A device.
00618     *
00619     * \details
00620     * Alert a monitor as to the status of the agent for which
00621     * the monitor had previously requested a status request.
00622     *
00623     * \note Zero or more responses may come as a result.
00624     *
00625     * \retval 0 on success
00626     * \retval -1 on failure.
00627     */
00628    int (*status_response)(struct ast_cc_monitor *monitor, enum ast_device_state devstate);
00629    /*!
00630     * \brief Unsuspend monitoring.
00631     *
00632     * \param monitor CC core monitor control.
00633     *
00634     * \details
00635     * Perform the necessary steps to unsuspend monitoring.
00636     *
00637     * \retval 0 on success
00638     * \retval -1 on failure.
00639     */
00640    int (*unsuspend)(struct ast_cc_monitor *monitor);
00641    /*!
00642     * \brief Cancel the running available timer.
00643     *
00644     * \param monitor CC core monitor control.
00645     * \param sched_id Available timer scheduler id to cancel.
00646     * Will never be NULL for a device monitor.
00647     *
00648     * \details
00649     * In most cases, this function will likely consist of just a
00650     * call to AST_SCHED_DEL. It might have been possible to do this
00651     * within the core, but unfortunately the mixture of sched_thread
00652     * and sched usage in Asterisk prevents such usage.
00653     *
00654     * \retval 0 on success
00655     * \retval -1 on failure.
00656     */
00657    int (*cancel_available_timer)(struct ast_cc_monitor *monitor, int *sched_id);
00658    /*!
00659     * \brief Destroy private data on the monitor.
00660     *
00661     * \param private_data The private data pointer from the monitor.
00662     *
00663     * \details
00664     * Implementers of this callback are responsible for destroying
00665     * all heap-allocated data in the monitor's private_data pointer, including
00666     * the private_data itself.
00667     */
00668    void (*destructor)(void *private_data);
00669 };
00670 
00671 /*!
00672  * \since 1.8
00673  * \brief Scheduler callback for available timer expiration
00674  *
00675  * \note
00676  * When arming the available timer from within a device monitor, you MUST
00677  * use this function as the callback for the scheduler.
00678  *
00679  * \param data A reference to the CC monitor on which the timer was running.
00680  */
00681 int ast_cc_available_timer_expire(const void *data);
00682 
00683 /* END SECTION ON MONITORS AND MONITOR CALLBACKS */
00684 
00685 /* BEGIN API FOR IN-CALL CC HANDLING */
00686 
00687 /*!
00688  * \since 1.8
00689  *
00690  * \brief Mark the channel to ignore further CC activity.
00691  *
00692  * \details
00693  * When a CC-capable application, such as Dial, has finished
00694  * with all CC processing for a channel and knows that any further
00695  * CC processing should be ignored, this function should be called.
00696  *
00697  * \param chan The channel for which further CC processing should be ignored.
00698  * \retval void
00699  */
00700 void ast_ignore_cc(struct ast_channel *chan);
00701 
00702 /*!
00703  * \since 1.8
00704  *
00705  * \brief Properly react to a CC control frame.
00706  *
00707  * \details
00708  * When a CC-capable application, such as Dial, receives a frame
00709  * of type AST_CONTROL_CC, then it may call this function in order
00710  * to have the device which sent the frame added to the tree of interfaces
00711  * which is kept on the inbound channel.
00712  *
00713  * \param inbound The inbound channel
00714  * \param outbound The outbound channel (The one from which the CC frame was read)
00715  * \param frame_data The ast_frame's data.ptr field.
00716  * \retval void
00717  */
00718 void ast_handle_cc_control_frame(struct ast_channel *inbound, struct ast_channel *outbound, void *frame_data);
00719 
00720 /*!
00721  * \since 1.8
00722  *
00723  * \brief Start the CC process on a call.
00724  *
00725  * \details
00726  * Whenever a CC-capable application, such as Dial, wishes to
00727  * engage in CC activity, it initiates the process by calling this
00728  * function. If the CC core should discover that a previous application
00729  * has called ast_ignore_cc on this channel or a "parent" channel, then
00730  * the value of the ignore_cc integer passed in will be set nonzero.
00731  *
00732  * The ignore_cc parameter is a convenience parameter. It can save an
00733  * application the trouble of trying to call CC APIs when it knows that
00734  * it should just ignore further attempts at CC actions.
00735  *
00736  * \param chan The inbound channel calling the CC-capable application.
00737  * \param[out] ignore_cc Will be set non-zero if no further CC actions need to be taken
00738  * \retval 0 Success
00739  * \retval -1 Failure
00740  */
00741 int ast_cc_call_init(struct ast_channel *chan, int *ignore_cc);
00742 
00743 /*!
00744  * \since 1.8
00745  *
00746  * \brief Add a child dialstring to an extension monitor
00747  *
00748  * Whenever we request a channel, the parent extension monitor needs
00749  * to store the dialstring of the device requested. The reason is so
00750  * that we can call the device back during the recall even if we are
00751  * not monitoring the device.
00752  *
00753  * \param incoming The caller's channel
00754  * \param dialstring The dialstring used when requesting the outbound channel
00755  * \param device_name The device name associated with the requested outbound channel
00756  * \retval void
00757  */
00758 void ast_cc_extension_monitor_add_dialstring(struct ast_channel *incoming, const char * const dialstring, const char * const device_name);
00759 
00760 /*!
00761  * \since 1.8
00762  * \brief Check if the incoming CC request is within the bounds
00763  * set by the cc_max_requests configuration option
00764  *
00765  * \details
00766  * It is recommended that an entity which receives an incoming
00767  * CC request calls this function before calling
00768  * ast_cc_agent_accept_request. This way, immediate feedback can be
00769  * given to the caller about why his request was rejected.
00770  *
00771  * If this is not called and a state change to CC_CALLER_REQUESTED
00772  * is made, then the core will still not allow for the request
00773  * to succeed. However, if done this way, it may not be obvious
00774  * to the requestor why the request failed.
00775  *
00776  * \retval 0 Not within the limits. Fail.
00777  * \retval non-zero Within the limits. Success.
00778  */
00779 int ast_cc_request_is_within_limits(void);
00780 
00781 /*!
00782  * \since 1.8
00783  * \brief Get the core id for the current call
00784  *
00785  * \details
00786  * The main use of this function is for channel drivers
00787  * who queue an AST_CONTROL_CC frame. A channel driver may
00788  * call this function in order to get the core_id for what
00789  * may become a CC request. This way, when monitor functions
00790  * are called which use a core_id as a means of identification,
00791  * the channel driver will have saved this information.
00792  *
00793  * The channel given to this function may be an inbound or outbound
00794  * channel. Both will have the necessary info on it.
00795  *
00796  * \param chan The channel from which to get the core_id.
00797  * \retval core_id on success
00798  * \retval -1 Failure
00799  */
00800 int ast_cc_get_current_core_id(struct ast_channel *chan);
00801 
00802 /* END API FOR IN-CALL CC HANDLING */
00803 
00804 /*!
00805  * \brief Structure with information about an outbound interface
00806  *
00807  * \details
00808  * This structure is first created when an outbound interface indicates that
00809  * it is capable of accepting a CC request. It is stored in a "tree" on a datastore on
00810  * the caller's channel. Once an agent structure is created, the agent gains
00811  * a reference to the tree of interfaces. If CC is requested, then the
00812  * interface tree on the agent is converted into a tree of monitors. Each
00813  * monitor will contain a pointer to an individual ast_cc_interface. Finally,
00814  * the tree of interfaces is also present on a second datastore during a
00815  * CC recall so that the CC_INTERFACES channel variable may be properly
00816  * populated.
00817  */
00818 struct ast_cc_interface {
00819    /* What class of monitor is being offered here
00820     */
00821    enum ast_cc_monitor_class monitor_class;
00822    /*!
00823     * \brief The type of monitor that should be used for this interface
00824     *
00825     * \details
00826     * This will be something like "extension" "generic" or "SIP".
00827     * This should point to a static const char *, so there is
00828     * no reason to make a new copy.
00829     */
00830    const char *monitor_type;
00831    /*!
00832     * The configuration parameters used for this interface
00833     */
00834    struct ast_cc_config_params *config_params;
00835    /* The name of the interface/extension. local channels will
00836     * have 'exten@context' for a name. Other channel types will
00837     * have 'tech/device' for a name.
00838     */
00839    char device_name[1];
00840 };
00841 
00842 /* BEGIN STRUCTURES FOR AGENTS */
00843 
00844 struct ast_cc_agent {
00845    /*!
00846     * Which instance of the core state machine does this
00847     * agent pertain to?
00848     */
00849    unsigned int core_id;
00850    /*!
00851     * Callback functions needed for specific agent
00852     * implementations
00853     */
00854    const struct ast_cc_agent_callbacks *callbacks;
00855    /*!
00856     * Configuration parameters that affect this
00857     * agent's operation.
00858     */
00859    struct ast_cc_config_params *cc_params;
00860    /*!
00861     * \brief Flags for agent operation
00862     *
00863     * \details
00864     * There are some attributes of certain agent types
00865     * that can alter the behavior of certain CC functions.
00866     * For a list of these flags, see the ast_cc_agent_flags
00867     * enum
00868     */
00869    unsigned int flags;
00870    /*! Data specific to agent implementation */
00871    void *private_data;
00872    /*! The name of the device which this agent
00873     * represents/communicates with
00874     */
00875    char device_name[1];
00876 };
00877 
00878 enum ast_cc_agent_response_reason {
00879    /*! CC request accepted */
00880    AST_CC_AGENT_RESPONSE_SUCCESS,
00881    /*! CC request not allowed at this time. Invalid state transition. */
00882    AST_CC_AGENT_RESPONSE_FAILURE_INVALID,
00883    /*! Too many CC requests in the system. */
00884    AST_CC_AGENT_RESPONSE_FAILURE_TOO_MANY,
00885 };
00886 
00887 struct ast_cc_agent_callbacks {
00888    /*!
00889     * \brief Type of agent the callbacks belong to.
00890     *
00891     * \note
00892     * Examples are "SIP" "ISDN" and "generic"
00893     */
00894    const char *type;
00895    /*!
00896     * \brief CC agent initialization.
00897     *
00898     * \param agent CC core agent control.
00899     * \param chan Original channel the agent will attempt to recall.
00900     *
00901     * \details
00902     * This callback is called when the CC core
00903     * is initialized. Agents should allocate
00904     * any private data necessary for the
00905     * call and assign it to the private_data
00906     * on the agent. Additionally, if any ast_cc_agent_flags
00907     * are pertinent to the specific agent type, they should
00908     * be set in this function as well.
00909     *
00910     * \retval 0 on success.
00911     * \retval -1 on error.
00912     */
00913    int (*init)(struct ast_cc_agent *agent, struct ast_channel *chan);
00914    /*!
00915     * \brief Start the offer timer.
00916     *
00917     * \param agent CC core agent control.
00918     *
00919     * \details
00920     * This is called by the core when the caller hangs up after
00921     * a call for which CC may be requested. The agent should
00922     * begin the timer as configured.
00923     *
00924     * The primary reason why this functionality is left to
00925     * the specific agent implementations is due to the differing
00926     * use of schedulers throughout the code. Some channel drivers
00927     * may already have a scheduler context they wish to use, and
00928     * amongst those, some may use the ast_sched API while others
00929     * may use the ast_sched_thread API, which are incompatible.
00930     *
00931     * \retval 0 on success.
00932     * \retval -1 on error.
00933     */
00934    int (*start_offer_timer)(struct ast_cc_agent *agent);
00935    /*!
00936     * \brief Stop the offer timer.
00937     *
00938     * \param agent CC core agent control.
00939     *
00940     * \details
00941     * This callback is called by the CC core when the caller
00942     * has requested CC.
00943     *
00944     * \retval 0 on success.
00945     * \retval -1 on error.
00946     */
00947    int (*stop_offer_timer)(struct ast_cc_agent *agent);
00948    /*!
00949     * \brief Respond to a CC request.
00950     *
00951     * \param agent CC core agent control.
00952     * \param reason CC request response status.
00953     *
00954     * \details
00955     * When the core receives knowledge that a called
00956     * party has accepted a CC request, it will call
00957     * this callback. The core may also call this
00958     * if there is some error when attempting to process
00959     * the incoming CC request.
00960     *
00961     * The duty of this is to issue a propper response to a
00962     * CC request from the caller by acknowledging receipt
00963     * of that request or rejecting it.
00964     */
00965    void (*respond)(struct ast_cc_agent *agent, enum ast_cc_agent_response_reason reason);
00966    /*!
00967     * \brief Request the status of the agent's device.
00968     *
00969     * \param agent CC core agent control.
00970     *
00971     * \details
00972     * Asynchronous request for the status of any caller
00973     * which may be a valid caller for the CC transaction.
00974     * Status responses should be made using the
00975     * ast_cc_status_response function.
00976     *
00977     * \retval 0 on success.
00978     * \retval -1 on error.
00979     */
00980    int (*status_request)(struct ast_cc_agent *agent);
00981    /*!
00982     * \brief Request for an agent's phone to stop ringing.
00983     *
00984     * \param agent CC core agent control.
00985     *
00986     * \details
00987     * The usefulness of this is quite limited. The only specific
00988     * known case for this is if Asterisk requests CC over an ISDN
00989     * PTMP link as the TE side. If other phones are in the same
00990     * recall group as the Asterisk server, and one of those phones
00991     * picks up the recall notice, then Asterisk will receive a
00992     * "stop ringing" notification from the NT side of the PTMP
00993     * link. This indication needs to be passed to the phone
00994     * on the other side of the Asterisk server which originally
00995     * placed the call so that it will stop ringing. Since the
00996     * phone may be of any type, it is necessary to have a callback
00997     * that the core can know about.
00998     *
00999     * \retval 0 on success.
01000     * \retval -1 on error.
01001     */
01002    int (*stop_ringing)(struct ast_cc_agent *agent);
01003    /*!
01004     * \brief Let the caller know that the callee has become free
01005     * but that the caller cannot attempt to call back because
01006     * he is either busy or there is congestion on his line.
01007     *
01008     * \param agent CC core agent control.
01009     *
01010     * \details
01011     * This is something that really only affects a scenario where
01012     * a phone places a call over ISDN PTMP to Asterisk, who then
01013     * connects over PTMP again to the ISDN network. For most agent
01014     * types, there is no need to implement this callback at all
01015     * because they don't really need to actually do anything in
01016     * this situation. If you're having trouble understanding what
01017     * the purpose of this callback is, then you can be safe simply
01018     * not implementing it.
01019     *
01020     * \retval 0 on success.
01021     * \retval -1 on error.
01022     */
01023    int (*party_b_free)(struct ast_cc_agent *agent);
01024    /*!
01025     * \brief Begin monitoring a busy device.
01026     *
01027     * \param agent CC core agent control.
01028     *
01029     * \details
01030     * The core will call this callback if the callee becomes
01031     * available but the caller has reported that he is busy.
01032     * The agent should begin monitoring the caller's device.
01033     * When the caller becomes available again, the agent should
01034     * call ast_cc_agent_caller_available.
01035     *
01036     * \retval 0 on success.
01037     * \retval -1 on error.
01038     */
01039    int (*start_monitoring)(struct ast_cc_agent *agent);
01040    /*!
01041     * \brief Alert the caller that it is time to try recalling.
01042     *
01043     * \param agent CC core agent control.
01044     *
01045     * \details
01046     * The core will call this function when it receives notice
01047     * that a monitored party has become available.
01048     *
01049     * The agent's job is to send a message to the caller to
01050     * notify it of such a change. If the agent is able to
01051     * discern that the caller is currently unavailable, then
01052     * the agent should react by calling the ast_cc_caller_unavailable
01053     * function.
01054     *
01055     * \retval 0 on success.
01056     * \retval -1 on error.
01057     */
01058    int (*callee_available)(struct ast_cc_agent *agent);
01059    /*!
01060     * \brief Destroy private data on the agent.
01061     *
01062     * \param agent CC core agent control.
01063     *
01064     * \details
01065     * The core will call this function upon completion
01066     * or failure of CC.
01067     *
01068     * \note
01069     * The agent private_data pointer may be NULL if the agent
01070     * constructor failed.
01071     */
01072    void (*destructor)(struct ast_cc_agent *agent);
01073 };
01074 
01075 /*!
01076  * \brief Call a callback on all agents of a specific type
01077  *
01078  * \details
01079  * Since the container of CC core instances is private, and so
01080  * are the items which the container contains, we have to provide
01081  * an ao2_callback-like method so that a specific agent may be
01082  * found or so that an operation can be made on all agents of
01083  * a particular type. The first three arguments should be familiar
01084  * to anyone who has used ao2_callback. The final argument is the
01085  * type of agent you wish to have the callback called on.
01086  *
01087  * \note Since agents are refcounted, and this function returns
01088  * a reference to the agent, it is imperative that you decrement
01089  * the refcount of the agent once you have finished using it.
01090  *
01091  * \param flags astobj2 search flags
01092  * \param function an ao2 callback function to call
01093  * \param arg the argument to the callback function
01094  * \param type The type of agents to call the callback on
01095  */
01096 struct ast_cc_agent *ast_cc_agent_callback(int flags, ao2_callback_fn *function, void *arg, const char * const type);
01097 
01098 /* END STRUCTURES FOR AGENTS */
01099 
01100 /* BEGIN STATE CHANGE API */
01101 
01102 /*!
01103  * \since 1.8
01104  * \brief Offer CC to a caller
01105  *
01106  * \details
01107  * This function is called from ast_hangup if the caller is
01108  * eligible to be offered call completion service.
01109  *
01110  * \param caller_chan The calling channel
01111  * \retval -1 Error
01112  * \retval 0 Success
01113  */
01114 int ast_cc_offer(struct ast_channel *caller_chan);
01115 
01116 /*!
01117  * \since 1.8
01118  * \brief Accept inbound CC request
01119  *
01120  * \details
01121  * When a caller requests CC, this function should be called to let
01122  * the core know that the request has been accepted.
01123  *
01124  * \param core_id core_id of the CC transaction
01125  * \param debug optional string to print for debugging purposes
01126  * \retval 0 Success
01127  * \retval -1 Failure
01128  */
01129 int __attribute__((format(printf, 2, 3))) ast_cc_agent_accept_request(int core_id, const char * const debug, ...);
01130 
01131 /*!
01132  * \since 1.8
01133  * \brief Indicate that an outbound entity has accepted our CC request
01134  *
01135  * \details
01136  * When we receive confirmation that an outbound device has accepted the
01137  * CC request we sent it, this function must be called.
01138  *
01139  * \param core_id core_id of the CC transaction
01140  * \param debug optional string to print for debugging purposes
01141  * \retval 0 Success
01142  * \retval -1 Failure
01143  */
01144 int __attribute__((format(printf, 2, 3))) ast_cc_monitor_request_acked(int core_id, const char * const debug, ...);
01145 
01146 /*!
01147  * \since 1.8
01148  * \brief Indicate that the caller is busy
01149  *
01150  * \details
01151  * When the callee makes it known that he is available, the core
01152  * will let the caller's channel driver know that it may attempt
01153  * to let the caller know to attempt a recall. If the channel
01154  * driver can detect, though, that the caller is busy, then
01155  * the channel driver should call this function to let the CC
01156  * core know.
01157  *
01158  * \param core_id core_id of the CC transaction
01159  * \param debug optional string to print for debugging purposes
01160  * \retval 0 Success
01161  * \retval -1 Failure
01162  */
01163 int __attribute__((format(printf, 2, 3))) ast_cc_agent_caller_busy(int core_id, const char * const debug, ...);
01164 
01165 /*!
01166  * \since 1.8
01167  * \brief Indicate that a previously unavailable caller has become available
01168  *
01169  * \details
01170  * If a monitor is suspended due to a caller becoming unavailable, then this
01171  * function should be called to indicate that the caller has become available.
01172  *
01173  * \param core_id core_id of the CC transaction
01174  * \param debug optional string to print for debugging purposes
01175  * \retval 0 Success
01176  * \retval -1 Failure
01177  */
01178 int __attribute__((format(printf, 2, 3))) ast_cc_agent_caller_available(int core_id, const char * const debug, ...);
01179 
01180 /*!
01181  * \since 1.8
01182  * \brief Tell the CC core that a caller is currently recalling
01183  *
01184  * \details
01185  * The main purpose of this is so that the core can alert the monitor
01186  * to stop its available timer since the caller has begun its recall
01187  * phase.
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_agent_recalling(int core_id, const char * const debug, ...);
01195 
01196 /*!
01197  * \since 1.8
01198  * \brief Indicate recall has been acknowledged
01199  *
01200  * \details
01201  * When we receive confirmation that an endpoint has responded to our
01202  * CC recall, we call this function.
01203  *
01204  * \param chan The inbound channel making the CC recall
01205  * \param debug optional string to print for debugging purposes
01206  * \retval 0 Success
01207  * \retval -1 Failure
01208  */
01209 int __attribute__((format(printf, 2, 3))) ast_cc_completed(struct ast_channel *chan, const char * const debug, ...);
01210 
01211 /*!
01212  * \since 1.8
01213  * \brief Indicate failure has occurred
01214  *
01215  * \details
01216  * If at any point a failure occurs, this is the function to call
01217  * so that the core can initiate cleanup procedures.
01218  *
01219  * \param core_id core_id of the CC transaction
01220  * \param debug optional string to print for debugging purposes
01221  * \retval 0 Success
01222  * \retval -1 Failure
01223  */
01224 int __attribute__((format(printf, 2, 3))) ast_cc_failed(int core_id, const char * const debug, ...);
01225 
01226 /*!
01227  * \since 1.8
01228  * \brief Indicate that a failure has occurred on a specific monitor
01229  *
01230  * \details
01231  * If a monitor should detect that a failure has occurred when communicating
01232  * with its endpoint, then ast_cc_monitor_failed should be called. The big
01233  * difference between ast_cc_monitor_failed and ast_cc_failed is that ast_cc_failed
01234  * indicates a global failure for a CC transaction, where as ast_cc_monitor_failed
01235  * is localized to a particular monitor. When ast_cc_failed is called, the entire
01236  * CC transaction is torn down. When ast_cc_monitor_failed is called, only the
01237  * monitor on which the failure occurred is pruned from the tree of monitors.
01238  *
01239  * If there are no more devices left to monitor when this function is called,
01240  * then the core will fail the CC transaction globally.
01241  *
01242  * \param core_id The core ID for the CC transaction
01243  * \param monitor_name The name of the monitor on which the failure occurred
01244  * \param debug A debug message to print to the CC log
01245  * \return void
01246  */
01247 int __attribute__((format(printf, 3, 4))) ast_cc_monitor_failed(int core_id, const char * const monitor_name, const char * const debug, ...);
01248 
01249 /* END STATE CHANGE API */
01250 
01251 /*!
01252  * The following are all functions which are required due to the unique
01253  * case where Asterisk is acting as the NT side of an ISDN PTMP
01254  * connection to the caller and as the TE side of an ISDN PTMP connection
01255  * to the callee. In such a case, there are several times where the
01256  * PTMP monitor needs information from the agent in order to formulate
01257  * the appropriate messages to send.
01258  */
01259 
01260 /*!
01261  * \brief Request the status of a caller or callers.
01262  *
01263  * \details
01264  * When an ISDN PTMP monitor senses that the callee has become
01265  * available, it needs to know the current status of the caller
01266  * in order to determine the appropriate response to send to
01267  * the caller. In order to do this, the monitor calls this function.
01268  * Responses will arrive asynchronously.
01269  *
01270  * \note Zero or more responses may come as a result.
01271  *
01272  * \param core_id The core ID of the CC transaction
01273  *
01274  * \retval 0 Successfully requested status
01275  * \retval -1 Failed to request status
01276  */
01277 int ast_cc_monitor_status_request(int core_id);
01278 
01279 /*!
01280  * \brief Response with a caller's current status
01281  *
01282  * \details
01283  * When an ISDN PTMP monitor requests the caller's status, the
01284  * agent must respond to the request using this function. For
01285  * simplicity it is recommended that the devstate parameter
01286  * be one of AST_DEVICE_INUSE or AST_DEVICE_NOT_INUSE.
01287  *
01288  * \param core_id The core ID of the CC transaction
01289  * \param devstate The current state of the caller to which the agent pertains
01290  * \retval 0 Successfully responded with our status
01291  * \retval -1 Failed to respond with our status
01292  */
01293 int ast_cc_agent_status_response(int core_id, enum ast_device_state devstate);
01294 
01295 /*!
01296  * \brief Alert a caller to stop ringing
01297  *
01298  * \details
01299  * When an ISDN PTMP monitor becomes available, it is assumed
01300  * that the agent will then cause the caller's phone to ring. In
01301  * some cases, this is literally what happens. In other cases, it may
01302  * be that the caller gets a visible indication on his phone that he
01303  * may attempt to recall the callee. If multiple callers are recalled
01304  * (since it may be possible to have a group of callers configured as
01305  * a single party A), and one of those callers picks up his phone, then
01306  * the ISDN PTMP monitor will alert the other callers to stop ringing.
01307  * The agent's stop_ringing callback will be called, and it is up to the
01308  * agent's driver to send an appropriate message to make his caller
01309  * stop ringing.
01310  *
01311  * \param core_id The core ID of the CC transaction
01312  * \retval 0 Successfully requested for the phone to stop ringing
01313  * \retval -1 Could not request for the phone to stop ringing
01314  */
01315 int ast_cc_monitor_stop_ringing(int core_id);
01316 
01317 /*!
01318  * \brief Alert a caller that though the callee has become free, the caller
01319  * himself is not and may not call back.
01320  *
01321  * \details
01322  * When an ISDN PTMP monitor senses that his monitored party has become
01323  * available, he will request the status of the called party. If he determines
01324  * that the caller is currently not available, then he will call this function
01325  * so that an appropriate message is sent to the caller.
01326  *
01327  * Yes, you just read that correctly. The callee asks the caller what his
01328  * current status is, and if the caller is currently unavailable, the monitor
01329  * must send him a message anyway. WTF?
01330  *
01331  * This function results in the agent's party_b_free callback being called.
01332  * It is most likely that you will not need to actually implement the
01333  * party_b_free callback in an agent because it is not likely that you will
01334  * need to or even want to send a caller a message indicating the callee's
01335  * status if the caller himself is not also free.
01336  *
01337  * \param core_id The core ID of the CC transaction
01338  * \retval 0 Successfully alerted the core that party B is free
01339  * \retval -1 Could not alert the core that party B is free
01340  */
01341 int ast_cc_monitor_party_b_free(int core_id);
01342 
01343 /* BEGIN API FOR USE WITH/BY MONITORS */
01344 
01345 /*!
01346  * \since 1.8
01347  * \brief Return the number of outstanding CC requests to a specific device
01348  *
01349  * \note
01350  * This function will lock the list of monitors stored on every instance of
01351  * the CC core. Callers of this function should be aware of this and avoid
01352  * any potential lock ordering problems.
01353  *
01354  * \param name The name of the monitored device
01355  * \param type The type of the monitored device (e.g. "generic")
01356  * \return The number of CC requests for the monitor
01357  */
01358 int ast_cc_monitor_count(const char * const name, const char * const type);
01359 
01360 /*!
01361  * \since 1.8
01362  * \brief Alert the core that a device being monitored has become available.
01363  *
01364  * \note
01365  * The code in the core will take care of making sure that the information gets passed
01366  * up the ladder correctly.
01367  *
01368  * \par core_id The core ID of the corresponding CC transaction
01369  * \par debug
01370  * \retval 0 Request successfully queued
01371  * \retval -1 Request could not be queued
01372  */
01373 int __attribute__((format(printf, 2, 3))) ast_cc_monitor_callee_available(const int core_id, const char * const debug, ...);
01374 
01375 /* END API FOR USE WITH/BY MONITORS */
01376 
01377 /* BEGIN API TO BE USED ON CC RECALL */
01378 
01379 /*!
01380  * \since 1.8
01381  * \brief Set up a CC recall datastore on a channel
01382  *
01383  * \details
01384  * Implementers of protocol-specific CC agents will need to call this
01385  * function in order for the channel to have the necessary interfaces
01386  * to recall.
01387  *
01388  * This function must be called by the implementer once it has been detected
01389  * that an inbound call is a cc_recall. After allocating the channel, call this
01390  * function, followed by ast_cc_set_cc_interfaces_chanvar. While it would be nice to
01391  * be able to have the core do this automatically, it just cannot be done given
01392  * the current architecture.
01393  */
01394 int ast_setup_cc_recall_datastore(struct ast_channel *chan, const int core_id);
01395 
01396 /*!
01397  * \since 1.8
01398  * \brief Decide if a call to a particular channel is a CC recall
01399  *
01400  * \details
01401  * When a CC recall happens, it is important on the called side to
01402  * know that the call is a CC recall and not a normal call. This function
01403  * will determine first if the call in question is a CC recall. Then it
01404  * will determine based on the chan parameter if the channel is being
01405  * called is being recalled.
01406  *
01407  * As a quick example, let's say a call is placed to SIP/1000 and SIP/1000
01408  * is currently on the phone. The caller requests CCBS. SIP/1000 finishes
01409  * his call, and so the caller attempts to recall. Now, the dialplan
01410  * administrator has set up this second call so that not only is SIP/1000
01411  * called, but also SIP/2000 is called. If SIP/1000's channel were passed
01412  * to this function, the return value would be non-zero, but if SIP/2000's
01413  * channel were passed into this function, then the return would be 0 since
01414  * SIP/2000 was not one of the original devices dialed.
01415  *
01416  * \note
01417  * This function may be called on a calling channel as well to
01418  * determine if it is part of a CC recall.
01419  *
01420  * \note
01421  * This function will lock the channel as well as the list of monitors
01422  * on the channel datastore, though the locks are not held at the same time. Be
01423  * sure that you have no potential lock order issues here.
01424  *
01425  * \param chan The channel to check
01426  * \param[out] core_id If this is a valid CC recall, the core_id of the failed call
01427  * will be placed in this output parameter
01428  * \param monitor_type Clarify which type of monitor type we are looking for if this
01429  * is happening on a called channel. For incoming channels, this parameter is not used.
01430  * \retval 0 Either this is not a recall or it is but this channel is not part of the recall
01431  * \retval non-zero This is a recall and the channel in question is directly involved.
01432  */
01433 int ast_cc_is_recall(struct ast_channel *chan, int *core_id, const char * const monitor_type);
01434 
01435 /*!
01436  * \since 1.8
01437  * \brief Get the associated monitor given the device name and core_id
01438  *
01439  * \details
01440  * The function ast_cc_is_recall is helpful for determining if a call to
01441  * a specific channel is a recall. However, once you have determined that
01442  * this is a recall, you will most likely need access to the private data
01443  * within the associated monitor. This function is what one uses to get
01444  * that monitor.
01445  *
01446  * \note
01447  * This function locks the list of monitors that correspond to the core_id
01448  * passed in. Be sure that you have no potential lock order issues when
01449  * calling this function.
01450  *
01451  * \param core_id The core ID to which this recall corresponds. This likely will
01452  * have been obtained using the ast_cc_is_recall function
01453  * \param device_name Which device to find the monitor for.
01454  *
01455  * \retval NULL Appropriate monitor does not exist
01456  * \retval non-NULL The monitor to use for this recall
01457  */
01458 struct ast_cc_monitor *ast_cc_get_monitor_by_recall_core_id(const int core_id, const char * const device_name);
01459 
01460 /*!
01461  * \since 1.8
01462  * \brief Set the first level CC_INTERFACES channel variable for a channel.
01463  *
01464  * \note
01465  * Implementers of protocol-specific CC agents should call this function after
01466  * calling ast_setup_cc_recall_datastore.
01467  *
01468  * \note
01469  * This function will lock the channel as well as the list of monitors stored
01470  * on the channel's CC recall datastore, though neither are held at the same
01471  * time. Callers of this function should be aware of potential lock ordering
01472  * problems that may arise.
01473  *
01474  * \details
01475  * The CC_INTERFACES channel variable will have the interfaces that should be
01476  * called back for a specific PBX instance.
01477  *
01478  * \param chan The channel to set the CC_INTERFACES variable on
01479  */
01480 int ast_cc_agent_set_interfaces_chanvar(struct ast_channel *chan);
01481 
01482 /*!
01483  * \since 1.8
01484  * \brief Set the CC_INTERFACES channel variable for a channel using an
01485  * \verbatim extension@context \endverbatim as a starting point
01486  *
01487  * \details
01488  * The CC_INTERFACES channel variable will have the interfaces
01489  * that should be called back for a specific PBX instance.  This
01490  * version of the function is used mainly by local channels,
01491  * wherein we need to set CC_INTERFACES based on an extension
01492  * and context that appear in the middle of the tree of dialed
01493  * interfaces.
01494  *
01495  * \note
01496  * This function will lock the channel as well as the list of monitors stored
01497  * on the channel's CC recall datastore, though neither are held at the same
01498  * time. Callers of this function should be aware of potential lock ordering
01499  * problems that may arise.
01500  *
01501  * \param chan The channel to set the CC_INTERFACES variable on
01502  * \param extension The name of the extension for which we're setting the variable.
01503  * This should be in the form of \verbatim exten@context \endverbatim
01504  */
01505 int ast_set_cc_interfaces_chanvar(struct ast_channel *chan, const char * const extension);
01506 
01507 /*!
01508  * \since 1.8
01509  * \brief Make CCBS available in the case that ast_call fails
01510  *
01511  * In some situations, notably if a call-limit is reached in SIP, ast_call will fail
01512  * due to Asterisk's knowing that the desired device is currently busy. In such a situation,
01513  * CCBS should be made available to the caller.
01514  *
01515  * One caveat is that this may only be used if generic monitoring is being used. The reason
01516  * is that since Asterisk determined that the device was busy without actually placing a call to it,
01517  * the far end will have no idea what call we are requesting call completion for if we were to send
01518  * a call completion request.
01519  */
01520 void ast_cc_call_failed(struct ast_channel *incoming, struct ast_channel *outgoing, const char * const dialstring);
01521 
01522 /*!
01523  * \since 1.8
01524  * \brief Callback made from ast_cc_callback for certain channel types
01525  *
01526  * \param inbound Incoming asterisk channel.
01527  * \param cc_params The CC configuration parameters for the outbound target
01528  * \param monitor_type The type of monitor to use when CC is requested
01529  * \param device_name The name of the outbound target device.
01530  * \param dialstring The dial string used when calling this specific interface
01531  * \param private_data If a native monitor is being used, and some channel-driver-specific private
01532  * data has been allocated, then this parameter should contain a pointer to that data. If using a generic
01533  * monitor, this parameter should remain NULL. Note that if this function should fail at some point,
01534  * it is the responsibility of the caller to free the private data upon return.
01535  *
01536  * \details
01537  * For channel types that fail ast_request when the device is busy, we call into the
01538  * channel driver with ast_cc_callback. This is the callback that is called in that
01539  * case for each device found which could have been returned by ast_request.
01540  *
01541  * This function creates a CC control frame payload, simulating the act of reading
01542  * it from the nonexistent outgoing channel's frame queue. We then handle this
01543  * simulated frame just as we would a normal CC frame which had actually been queued
01544  * by the channel driver.
01545  */
01546 void ast_cc_busy_interface(struct ast_channel *inbound, struct ast_cc_config_params *cc_params,
01547    const char *monitor_type, const char * const device_name, const char * const dialstring, void *private_data);
01548 
01549 /*!
01550  * \since 1.8
01551  * \brief Create a CC Control frame
01552  *
01553  * \details
01554  * chan_dahdi is weird. It doesn't seem to actually queue frames when it needs to tell
01555  * an application something. Instead it wakes up, tells the application that it has data
01556  * ready, and then based on set flags, creates the proper frame type. For chan_dahdi, we
01557  * provide this function. It provides us the data we need, and we'll make its frame for it.
01558  *
01559  * \param chan A channel involved in the call. What we want is on a datastore on both incoming 
01560  * and outgoing so either may be provided
01561  * \param cc_params The CC configuration parameters for the outbound target
01562  * \param monitor_type The type of monitor to use when CC is requested
01563  * \param device_name The name of the outbound target device.
01564  * \param dialstring The dial string used when calling this specific interface
01565  * \param service What kind of CC service is being offered. (CCBS/CCNR/etc...)
01566  * \param private_data If a native monitor is being used, and some channel-driver-specific private
01567  * data has been allocated, then this parameter should contain a pointer to that data. If using a generic
01568  * monitor, this parameter should remain NULL. Note that if this function should fail at some point,
01569  * it is the responsibility of the caller to free the private data upon return.
01570  * \param[out] frame The frame we will be returning to the caller. It is vital that ast_frame_free be 
01571  * called on this frame since the payload will be allocated on the heap.
01572  * \retval -1 Failure. At some point there was a failure. Do not attempt to use the frame in this case.
01573  * \retval 0 Success
01574  */
01575 int ast_cc_build_frame(struct ast_channel *chan, struct ast_cc_config_params *cc_params,
01576    const char *monitor_type, const char * const device_name,
01577    const char * const dialstring, enum ast_cc_service_type service, void *private_data,
01578    struct ast_frame *frame);
01579 
01580 
01581 /*!
01582  * \brief Callback made from ast_cc_callback for certain channel types
01583  * \since 1.8
01584  *
01585  * \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
01586  * \param cc_params The CC configuration parameters for the outbound target
01587  * \param monitor_type The type of monitor to use when CC is requested
01588  * \param device_name The name of the outbound target device.
01589  * \param dialstring The dial string used when calling this specific interface
01590  * \param private_data If a native monitor is being used, and some channel-driver-specific private
01591  * data has been allocated, then this parameter should contain a pointer to that data. If using a generic
01592  * monitor, this parameter should remain NULL. Note that if this function should fail at some point,
01593  * it is the responsibility of the caller to free the private data upon return.
01594  *
01595  * \details
01596  * For channel types that fail ast_request when the device is busy, we call into the
01597  * channel driver with ast_cc_callback. This is the callback that is called in that
01598  * case for each device found which could have been returned by ast_request.
01599  *
01600  * \return Nothing
01601  */
01602 typedef void (*ast_cc_callback_fn)(struct ast_channel *chan, struct ast_cc_config_params *cc_params,
01603    const char *monitor_type, const char * const device_name, const char * const dialstring, void *private_data);
01604 
01605 /*!
01606  * \since 1.8
01607  * \brief Run a callback for potential matching destinations.
01608  *
01609  * \note
01610  * See the explanation in ast_channel_tech::cc_callback for more
01611  * details.
01612  *
01613  * \param inbound
01614  * \param tech Channel technology to use
01615  * \param dest Channel/group/peer or whatever the specific technology uses
01616  * \param callback Function to call when a target is reached
01617  * \retval Always 0, I guess.
01618  */
01619 int ast_cc_callback(struct ast_channel *inbound, const char * const tech, const char * const dest, ast_cc_callback_fn callback);
01620 
01621 /*!
01622  * \since 1.8
01623  * \brief Initialize CCSS
01624  *
01625  * Performs startup routines necessary for CC operation.
01626  *
01627  * \retval 0 Success
01628  * \retval nonzero Failure
01629  */
01630 int ast_cc_init(void);
01631 
01632 #endif /* _ASTERISK_CCSS_H */

Generated on Thu Apr 16 06:27:17 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6