Deprecated macro usage for connected line, redirecting, and CCSS
[asterisk/asterisk.git] / include / asterisk / ccss.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2010, Digium, Inc.
5  *
6  * Mark Michelson <mmichelson@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Call Completion Supplementary Services API
21  * \author Mark Michelson <mmichelson@digium.com>
22  */
23
24 #ifndef _ASTERISK_CCSS_H
25 #define _ASTERISK_CCSS_H
26
27 #include "asterisk.h"
28
29 #include "asterisk/linkedlists.h"
30 #include "asterisk/devicestate.h"
31
32 enum ast_cc_service_type {
33         /* No Service available/requested */
34         AST_CC_NONE,
35         /* Call Completion Busy Subscriber */
36         AST_CC_CCBS,
37         /* Call Completion No Response */
38         AST_CC_CCNR,
39         /* Call Completion Not Logged In (currently SIP only) */
40         AST_CC_CCNL,
41 };
42
43 /*!
44  * \since 1.8
45  * \brief The various possibilities for cc_agent_policy values
46  */
47 enum ast_cc_agent_policies {
48         /*! Never offer CCSS to the caller */
49         AST_CC_AGENT_NEVER,
50         /*! Offer CCSS using native signaling */
51         AST_CC_AGENT_NATIVE,
52         /*! Use generic agent for caller */
53         AST_CC_AGENT_GENERIC,
54 };
55
56 /*!
57  * \brief agent flags that can alter core behavior
58  */
59 enum ast_cc_agent_flags {
60         /* Some agent types allow for a caller to
61          * request CC without reaching the CC_CALLER_OFFERED
62          * state. In other words, the caller can request
63          * CC while he is still on the phone from the failed
64          * call. The generic agent is an agent which allows
65          * for this behavior.
66          */
67         AST_CC_AGENT_SKIP_OFFER = (1 << 0),
68 };
69
70 /*!
71  * \since 1.8
72  * \brief The various possibilities for cc_monitor_policy values
73  */
74 enum ast_cc_monitor_policies {
75         /*! Never accept CCSS offers from callee */
76         AST_CC_MONITOR_NEVER,
77         /* CCSS only available if callee offers it through signaling */
78         AST_CC_MONITOR_NATIVE,
79         /*! Always use CCSS generic monitor for callee
80          * Note that if callee offers CCSS natively, we still
81          * will use a generic CCSS monitor if this is set
82          */
83         AST_CC_MONITOR_GENERIC,
84         /*! Accept native CCSS offers, but if no offer is present,
85          * use a generic CCSS monitor
86          */
87         AST_CC_MONITOR_ALWAYS,
88 };
89
90 /* Forward declaration. Struct is in main/ccss.c */
91 struct ast_cc_config_params;
92
93 /*!
94  * \since 1.8
95  * \brief Queue an AST_CONTROL_CC frame
96  *
97  * \note
98  * Since this function calls ast_queue_frame, the channel will be
99  * locked during the course of this function.
100  *
101  * \param chan The channel onto which to queue the frame
102  * \param monitor_type The type of monitor to use when CC is requested
103  * \param dialstring The dial string used to call the device
104  * \param service The type of CC service the device is willing to offer
105  * \param private_data If a native monitor is being used, and some channel-driver-specific private
106  * data has been allocated, then this parameter should contain a pointer to that data. If using a generic
107  * monitor, this parameter should remain NULL. Note that if this function should fail at some point,
108  * it is the responsibility of the caller to free the private data upon return.
109  * \retval 0 Success
110  * \retval -1 Error
111  */
112 int ast_queue_cc_frame(struct ast_channel *chan, const char * const monitor_type,
113                 const char * const dialstring, enum ast_cc_service_type service, void *private_data);
114
115 /*!
116  * \brief Allocate and initialize an ast_cc_config_params structure
117  *
118  * \note
119  * Reasonable default values are chosen for the parameters upon allocation.
120  *
121  * \retval NULL Unable to allocate the structure
122  * \retval non-NULL A pointer to the newly allocated and initialized structure
123  */
124 struct ast_cc_config_params *__ast_cc_config_params_init(const char *file, int line, const char *function);
125
126 /*!
127  * \brief Allocate and initialize an ast_cc_config_params structure
128  *
129  * \note
130  * Reasonable default values are chosen for the parameters upon allocation.
131  *
132  * \retval NULL Unable to allocate the structure
133  * \retval non-NULL A pointer to the newly allocated and initialized structure
134  */
135 #define ast_cc_config_params_init() __ast_cc_config_params_init(__FILE__, __LINE__, __PRETTY_FUNCTION__)
136
137 /*!
138  * \brief Free memory from CCSS configuration params
139  *
140  * \note
141  * Just a call to ast_free for now...
142  *
143  * \param params Pointer to structure whose memory we need to free
144  * \retval void
145  */
146 void ast_cc_config_params_destroy(struct ast_cc_config_params *params);
147
148 /*!
149  * \brief set a CCSS configuration parameter, given its name
150  *
151  * \note
152  * Useful when parsing config files when used in conjunction
153  * with ast_ccss_is_cc_config_param.
154  *
155  * \param params The parameter structure to set the value on
156  * \param name The name of the cc parameter
157  * \param value The value of the parameter
158  * \retval 0 Success
159  * \retval -1 Failure
160  */
161 int ast_cc_set_param(struct ast_cc_config_params *params, const char * const name,
162                 const char * value);
163
164 /*!
165  * \brief get a CCSS configuration parameter, given its name
166  *
167  * \note
168  * Useful when reading input as a string, like from dialplan or
169  * manager.
170  *
171  * \param params The CCSS configuration from which to get the value
172  * \param name The name of the CCSS parameter we want
173  * \param buf A preallocated buffer to hold the value
174  * \param buf_len The size of buf
175  * \retval 0 Success
176  * \retval -1 Failure
177  */
178 int ast_cc_get_param(struct ast_cc_config_params *params, const char * const name,
179                 char *buf, size_t buf_len);
180
181 /*!
182  * \since 1.8
183  * \brief Is this a CCSS configuration parameter?
184  * \param name Name of configuration option being parsed.
185  * \retval 1 Yes, this is a CCSS configuration parameter.
186  * \retval 0 No, this is not a CCSS configuration parameter.
187  */
188 int ast_cc_is_config_param(const char * const name);
189
190 /*!
191  * \since 1.8
192  * \brief Set the specified CC config params to default values.
193  *
194  * \details
195  * This is just like ast_cc_copy_config_params() and could be used in place
196  * of it if you need to set the config params to defaults instead.
197  * You are simply "copying" defaults into the destination.
198  *
199  * \param params CC config params to set to default values.
200  *
201  * \return Nothing
202  */
203 void ast_cc_default_config_params(struct ast_cc_config_params *params);
204
205 /*!
206  * \since 1.8
207  * \brief copy CCSS configuration parameters from one structure to another
208  *
209  * \details
210  * For now, this is a simple memcpy, but this function is necessary since
211  * the size of an ast_cc_config_params structure is unknown outside of
212  * main/ccss.c. Also, this allows for easier expansion of the function in
213  * case it becomes more complex than just a memcpy.
214  *
215  * \param src The structure from which data is copied
216  * \param dest The structure to which data is copied
217  *
218  * \return Nothing
219  */
220 void ast_cc_copy_config_params(struct ast_cc_config_params *dest, const struct ast_cc_config_params *src);
221
222 /*!
223  * \since 1.8
224  * \brief Get the cc_agent_policy
225  * \param config The configuration to retrieve the policy from
226  * \return The current cc_agent_policy for this configuration
227  */
228 enum ast_cc_agent_policies ast_get_cc_agent_policy(struct ast_cc_config_params *config);
229
230 /*!
231  * \since 1.8
232  * \brief Set the cc_agent_policy
233  * \param config The configuration to set the cc_agent_policy on
234  * \param value The new cc_agent_policy we want to change to
235  * \retval 0 Success
236  * \retval -1 Failure (likely due to bad input)
237  */
238 int ast_set_cc_agent_policy(struct ast_cc_config_params *config, enum ast_cc_agent_policies value);
239
240 /*!
241  * \since 1.8
242  * \brief Get the cc_monitor_policy
243  * \param config The configuration to retrieve the cc_monitor_policy from
244  * \return The cc_monitor_policy retrieved from the configuration
245  */
246 enum ast_cc_monitor_policies ast_get_cc_monitor_policy(struct ast_cc_config_params *config);
247
248 /*!
249  * \since 1.8
250  * \brief Set the cc_monitor_policy
251  * \param config The configuration to set the cc_monitor_policy on
252  * \param value The new cc_monitor_policy we want to change to
253  * \retval 0 Success
254  * \retval -1 Failure (likely due to bad input)
255  */
256 int ast_set_cc_monitor_policy(struct ast_cc_config_params *config, enum ast_cc_monitor_policies value);
257
258 /*!
259  * \since 1.8
260  * \brief Get the cc_offer_timer
261  * \param config The configuration to retrieve the cc_offer_timer from
262  * \return The cc_offer_timer from this configuration
263  */
264 unsigned int ast_get_cc_offer_timer(struct ast_cc_config_params *config);
265
266 /*!
267  * \since 1.8
268  * \brief Set the cc_offer_timer
269  * \param config The configuration to set the cc_offer_timer on
270  * \param value The new cc_offer_timer we want to change to
271  * \retval void
272  */
273 void ast_set_cc_offer_timer(struct ast_cc_config_params *config, unsigned int value);
274
275 /*!
276  * \since 1.8
277  * \brief Get the ccnr_available_timer
278  * \param config The configuration to retrieve the ccnr_available_timer from
279  * \return The ccnr_available_timer from this configuration
280  */
281 unsigned int ast_get_ccnr_available_timer(struct ast_cc_config_params *config);
282
283 /*!
284  * \since 1.8
285  * \brief Set the ccnr_available_timer
286  * \param config The configuration to set the ccnr_available_timer on
287  * \param value The new ccnr_available_timer we want to change to
288  * \retval void
289  */
290 void ast_set_ccnr_available_timer(struct ast_cc_config_params *config, unsigned int value);
291
292 /*!
293  * \since 1.8
294  * \brief Get the cc_recall_timer
295  * \param config The configuration to retrieve the cc_recall_timer from
296  * \return The cc_recall_timer from this configuration
297  */
298 unsigned int ast_get_cc_recall_timer(struct ast_cc_config_params *config);
299
300 /*!
301  * \since 1.8
302  * \brief Set the cc_recall_timer
303  * \param config The configuration to set the cc_recall_timer on
304  * \param value The new cc_recall_timer we want to change to
305  * \retval void
306  */
307 void ast_set_cc_recall_timer(struct ast_cc_config_params *config, unsigned int value);
308
309 /*!
310  * \since 1.8
311  * \brief Get the ccbs_available_timer
312  * \param config The configuration to retrieve the ccbs_available_timer from
313  * \return The ccbs_available_timer from this configuration
314  */
315 unsigned int ast_get_ccbs_available_timer(struct ast_cc_config_params *config);
316
317 /*!
318  * \since 1.8
319  * \brief Set the ccbs_available_timer
320  * \param config The configuration to set the ccbs_available_timer on
321  * \param value The new ccbs_available_timer we want to change to
322  * \retval void
323  */
324 void ast_set_ccbs_available_timer(struct ast_cc_config_params *config, unsigned int value);
325
326 /*!
327  * \since 1.8
328  * \brief Get the cc_agent_dialstring
329  * \param config The configuration to retrieve the cc_agent_dialstring from
330  * \return The cc_agent_dialstring from this configuration
331  */
332 const char *ast_get_cc_agent_dialstring(struct ast_cc_config_params *config);
333
334 /*!
335  * \since 1.8
336  * \brief Set the cc_agent_dialstring
337  * \param config The configuration to set the cc_agent_dialstring on
338  * \param value The new cc_agent_dialstring we want to change to
339  * \retval void
340  */
341 void ast_set_cc_agent_dialstring(struct ast_cc_config_params *config, const char *const value);
342
343 /*!
344  * \since 1.8
345  * \brief Get the cc_max_agents
346  * \param config The configuration to retrieve the cc_max_agents from
347  * \return The cc_max_agents from this configuration
348  */
349 unsigned int ast_get_cc_max_agents(struct ast_cc_config_params *config);
350
351 /*!
352  * \since 1.8
353  * \brief Set the cc_max_agents
354  * \param config The configuration to set the cc_max_agents on
355  * \param value The new cc_max_agents we want to change to
356  * \retval void
357  */
358 void ast_set_cc_max_agents(struct ast_cc_config_params *config, unsigned int value);
359
360 /*!
361  * \since 1.8
362  * \brief Get the cc_max_monitors
363  * \param config The configuration to retrieve the cc_max_monitors from
364  * \return The cc_max_monitors from this configuration
365  */
366 unsigned int ast_get_cc_max_monitors(struct ast_cc_config_params *config);
367
368 /*!
369  * \since 1.8
370  * \brief Set the cc_max_monitors
371  * \param config The configuration to set the cc_max_monitors on
372  * \param value The new cc_max_monitors we want to change to
373  * \retval void
374  */
375 void ast_set_cc_max_monitors(struct ast_cc_config_params *config, unsigned int value);
376
377 /*!
378  * \since 1.8
379  * \brief Get the name of the callback_macro
380  * \param config The configuration to retrieve the callback_macro from
381  * \return The callback_macro name
382  */
383 const char *ast_get_cc_callback_macro(struct ast_cc_config_params *config);
384
385 /*!
386  * \since 1.8
387  * \brief Set the callback_macro name
388  * \param config The configuration to set the callback_macro on
389  * \param value The new callback macro we want to change to
390  * \retval void
391  */
392 void ast_set_cc_callback_macro(struct ast_cc_config_params *config, const char * const value);
393
394 /*!
395  * \since 11
396  * \brief Get the name of the callback subroutine
397  * \param config The configuration to retrieve the callback_sub from
398  * \return The callback_sub name
399  */
400 const char *ast_get_cc_callback_sub(struct ast_cc_config_params *config);
401
402 /*!
403  * \since 11
404  * \brief Set the callback subroutine name
405  * \param config The configuration to set the callback_sub on
406  * \param value The new callback subroutine we want to change to
407  * \retval void
408  */
409 void ast_set_cc_callback_sub(struct ast_cc_config_params *config, const char * const value);
410
411 /* END CONFIGURATION FUNCTIONS */
412
413 /* BEGIN AGENT/MONITOR REGISTRATION API */
414
415 struct ast_cc_monitor_callbacks;
416
417 /*!
418  * \since 1.8
419  * \brief Register a set of monitor callbacks with the core
420  *
421  * \details
422  * This is made so that at monitor creation time, the proper callbacks
423  * may be installed and the proper .init callback may be called for the
424  * monitor to establish private data.
425  *
426  * \param callbacks The callbacks used by the monitor implementation
427  * \retval 0 Successfully registered
428  * \retval -1 Failure to register
429  */
430 int ast_cc_monitor_register(const struct ast_cc_monitor_callbacks *callbacks);
431
432 /*!
433  * \since 1.8
434  * \brief Unregister a set of monitor callbacks with the core
435  *
436  * \details
437  * If a module which makes use of a CC monitor is unloaded, then it may
438  * unregister its monitor callbacks with the core.
439  *
440  * \param callbacks The callbacks used by the monitor implementation
441  * \retval 0 Successfully unregistered
442  * \retval -1 Failure to unregister
443  */
444 void ast_cc_monitor_unregister(const struct ast_cc_monitor_callbacks *callbacks);
445
446 struct ast_cc_agent_callbacks;
447
448 /*!
449  * \since 1.8
450  * \brief Register a set of agent callbacks with the core
451  *
452  * \details
453  * This is made so that at agent creation time, the proper callbacks
454  * may be installed and the proper .init callback may be called for the
455  * monitor to establish private data.
456  *
457  * \param callbacks The callbacks used by the agent implementation
458  * \retval 0 Successfully registered
459  * \retval -1 Failure to register
460  */
461 int ast_cc_agent_register(const struct ast_cc_agent_callbacks *callbacks);
462
463 /*!
464  * \since 1.8
465  * \brief Unregister a set of agent callbacks with the core
466  *
467  * \details
468  * If a module which makes use of a CC agent is unloaded, then it may
469  * unregister its agent callbacks with the core.
470  *
471  * \param callbacks The callbacks used by the agent implementation
472  * \retval 0 Successfully unregistered
473  * \retval -1 Failure to unregister
474  */
475 void ast_cc_agent_unregister(const struct ast_cc_agent_callbacks *callbacks);
476
477 /* END AGENT/MONITOR REGISTRATION API */
478
479 /* BEGIN SECTION ON MONITORS AND MONITOR CALLBACKS */
480
481 /*!
482  * It is recommended that monitors use a pointer to
483  * an ast_cc_monitor_callbacks::type when creating
484  * an AST_CONTROL_CC frame. Since the generic monitor
485  * callbacks are opaque and channel drivers will wish
486  * to use that, this string is made globally available
487  * for all to use
488  */
489 #define AST_CC_GENERIC_MONITOR_TYPE "generic"
490
491 /*!
492  * Used to determine which type
493  * of monitor an ast_cc_device_monitor
494  * is.
495  */
496 enum ast_cc_monitor_class {
497         AST_CC_DEVICE_MONITOR,
498         AST_CC_EXTENSION_MONITOR,
499 };
500
501 /*!
502  * \internal
503  * \brief An item in a CC interface tree.
504  *
505  * These are the individual items in an interface tree.
506  * The key difference between this structure and the ast_cc_interface
507  * is that this structure contains data which is intrinsic to the item's
508  * placement in the tree, such as who its parent is.
509  */
510 struct ast_cc_monitor {
511         /*!
512          * Information regarding the interface.
513          */
514         struct ast_cc_interface *interface;
515         /*!
516          * Every interface has an id that uniquely identifies it. It is
517          * formed by incrementing a counter.
518          */
519         unsigned int id;
520         /*!
521          * The ID of this monitor's parent. If this monitor is at the
522          * top of the tree, then his parent will be 0.
523          */
524         unsigned int parent_id;
525         /*!
526          * The instance of the CC core to which this monitor belongs
527          */
528         int core_id;
529         /*!
530          * The type of call completion service offered by a device.
531          */
532         enum ast_cc_service_type service_offered;
533         /*!
534          * \brief Name that should be used to recall specified interface
535          *
536          * \details
537          * When issuing a CC recall, some technologies will require
538          * that a name other than the device name is dialed. For instance,
539          * with SIP, a specific URI will be used which chan_sip will be able
540          * to recognize as being a CC recall. Similarly, ISDN will need a specific
541          * dial string to know that the call is a recall.
542          */
543         char *dialstring;
544         /*!
545          * The ID of the available timer used by the current monitor
546          */
547         int available_timer_id;
548         /*!
549          * Monitor callbacks
550          */
551         const struct ast_cc_monitor_callbacks *callbacks;
552         /*!
553          * \brief Data that is private to a monitor technology
554          *
555          * Most channel drivers that implement CC monitors will have to
556          * allocate data that the CC core does not care about but which
557          * is vital to the operation of the monitor. This data is stored
558          * in this pointer so that the channel driver may use it as
559          * needed
560          */
561         void *private_data;
562         AST_LIST_ENTRY(ast_cc_monitor) next;
563 };
564
565 /*!
566  * \brief Callbacks defined by CC monitors
567  *
568  * \note
569  * Every callback is called with the list of monitors locked. There
570  * are several public API calls that also will try to lock this lock.
571  * These public functions have a note in their doxygen stating so.
572  * As such, pay attention to the lock order you establish in these callbacks
573  * to ensure that you do not violate the lock order when calling
574  * the functions in this file with lock order notices.
575  */
576 struct ast_cc_monitor_callbacks {
577         /*!
578          * \brief Type of monitor the callbacks belong to.
579          *
580          * \note
581          * Examples include "generic" and "SIP"
582          */
583         const char *type;
584         /*!
585          * \brief Request CCSS.
586          *
587          * \param monitor CC core monitor control.
588          * \param available_timer_id The scheduler ID for the available timer.
589          * Will never be NULL for a device monitor.
590          *
591          * \details
592          * Perform whatever steps are necessary in order to request CC.
593          * In addition, the monitor implementation is responsible for
594          * starting the available timer in this callback.
595          *
596          * \retval 0 on success
597          * \retval -1 on failure.
598          */
599         int (*request_cc)(struct ast_cc_monitor *monitor, int *available_timer_id);
600         /*!
601          * \brief Suspend monitoring.
602          *
603          * \param monitor CC core monitor control.
604          *
605          * \details
606          * Implementers must perform the necessary steps to suspend
607          * monitoring.
608          *
609          * \retval 0 on success
610          * \retval -1 on failure.
611          */
612         int (*suspend)(struct ast_cc_monitor *monitor);
613         /*!
614          * \brief Status response to an ast_cc_monitor_status_request().
615          *
616          * \param monitor CC core monitor control.
617          * \param devstate Current status of a Party A device.
618          *
619          * \details
620          * Alert a monitor as to the status of the agent for which
621          * the monitor had previously requested a status request.
622          *
623          * \note Zero or more responses may come as a result.
624          *
625          * \retval 0 on success
626          * \retval -1 on failure.
627          */
628         int (*status_response)(struct ast_cc_monitor *monitor, enum ast_device_state devstate);
629         /*!
630          * \brief Unsuspend monitoring.
631          *
632          * \param monitor CC core monitor control.
633          *
634          * \details
635          * Perform the necessary steps to unsuspend monitoring.
636          *
637          * \retval 0 on success
638          * \retval -1 on failure.
639          */
640         int (*unsuspend)(struct ast_cc_monitor *monitor);
641         /*!
642          * \brief Cancel the running available timer.
643          *
644          * \param monitor CC core monitor control.
645          * \param sched_id Available timer scheduler id to cancel.
646          * Will never be NULL for a device monitor.
647          *
648          * \details
649          * In most cases, this function will likely consist of just a
650          * call to AST_SCHED_DEL. It might have been possible to do this
651          * within the core, but unfortunately the mixture of sched_thread
652          * and sched usage in Asterisk prevents such usage.
653          *
654          * \retval 0 on success
655          * \retval -1 on failure.
656          */
657         int (*cancel_available_timer)(struct ast_cc_monitor *monitor, int *sched_id);
658         /*!
659          * \brief Destroy private data on the monitor.
660          *
661          * \param private_data The private data pointer from the monitor.
662          *
663          * \details
664          * Implementers of this callback are responsible for destroying
665          * all heap-allocated data in the monitor's private_data pointer, including
666          * the private_data itself.
667          */
668         void (*destructor)(void *private_data);
669 };
670
671 /*!
672  * \since 1.8
673  * \brief Scheduler callback for available timer expiration
674  *
675  * \note
676  * When arming the available timer from within a device monitor, you MUST
677  * use this function as the callback for the scheduler.
678  *
679  * \param data A reference to the CC monitor on which the timer was running.
680  */
681 int ast_cc_available_timer_expire(const void *data);
682
683 /* END SECTION ON MONITORS AND MONITOR CALLBACKS */
684
685 /* BEGIN API FOR IN-CALL CC HANDLING */
686
687 /*!
688  * \since 1.8
689  *
690  * \brief Mark the channel to ignore further CC activity.
691  *
692  * \details
693  * When a CC-capable application, such as Dial, has finished
694  * with all CC processing for a channel and knows that any further
695  * CC processing should be ignored, this function should be called.
696  *
697  * \param chan The channel for which further CC processing should be ignored.
698  * \retval void
699  */
700 void ast_ignore_cc(struct ast_channel *chan);
701
702 /*!
703  * \since 1.8
704  *
705  * \brief Properly react to a CC control frame.
706  *
707  * \details
708  * When a CC-capable application, such as Dial, receives a frame
709  * of type AST_CONTROL_CC, then it may call this function in order
710  * to have the device which sent the frame added to the tree of interfaces
711  * which is kept on the inbound channel.
712  *
713  * \param inbound The inbound channel
714  * \param outbound The outbound channel (The one from which the CC frame was read)
715  * \param frame_data The ast_frame's data.ptr field.
716  * \retval void
717  */
718 void ast_handle_cc_control_frame(struct ast_channel *inbound, struct ast_channel *outbound, void *frame_data);
719
720 /*!
721  * \since 1.8
722  *
723  * \brief Start the CC process on a call.
724  *
725  * \details
726  * Whenever a CC-capable application, such as Dial, wishes to
727  * engage in CC activity, it initiates the process by calling this
728  * function. If the CC core should discover that a previous application
729  * has called ast_ignore_cc on this channel or a "parent" channel, then
730  * the value of the ignore_cc integer passed in will be set nonzero.
731  *
732  * The ignore_cc parameter is a convenience parameter. It can save an
733  * application the trouble of trying to call CC APIs when it knows that
734  * it should just ignore further attempts at CC actions.
735  *
736  * \param chan The inbound channel calling the CC-capable application.
737  * \param[out] ignore_cc Will be set non-zero if no further CC actions need to be taken
738  * \retval 0 Success
739  * \retval -1 Failure
740  */
741 int ast_cc_call_init(struct ast_channel *chan, int *ignore_cc);
742
743 /*!
744  * \since 1.8
745  *
746  * \brief Add a child dialstring to an extension monitor
747  *
748  * Whenever we request a channel, the parent extension monitor needs
749  * to store the dialstring of the device requested. The reason is so
750  * that we can call the device back during the recall even if we are
751  * not monitoring the device.
752  *
753  * \param incoming The caller's channel
754  * \param dialstring The dialstring used when requesting the outbound channel
755  * \param device_name The device name associated with the requested outbound channel
756  * \retval void
757  */
758 void ast_cc_extension_monitor_add_dialstring(struct ast_channel *incoming, const char * const dialstring, const char * const device_name);
759
760 /*!
761  * \since 1.8
762  * \brief Check if the incoming CC request is within the bounds
763  * set by the cc_max_requests configuration option
764  *
765  * \details
766  * It is recommended that an entity which receives an incoming
767  * CC request calls this function before calling
768  * ast_cc_agent_accept_request. This way, immediate feedback can be
769  * given to the caller about why his request was rejected.
770  *
771  * If this is not called and a state change to CC_CALLER_REQUESTED
772  * is made, then the core will still not allow for the request
773  * to succeed. However, if done this way, it may not be obvious
774  * to the requestor why the request failed.
775  *
776  * \retval 0 Not within the limits. Fail.
777  * \retval non-zero Within the limits. Success.
778  */
779 int ast_cc_request_is_within_limits(void);
780
781 /*!
782  * \since 1.8
783  * \brief Get the core id for the current call
784  *
785  * \details
786  * The main use of this function is for channel drivers
787  * who queue an AST_CONTROL_CC frame. A channel driver may
788  * call this function in order to get the core_id for what
789  * may become a CC request. This way, when monitor functions
790  * are called which use a core_id as a means of identification,
791  * the channel driver will have saved this information.
792  *
793  * The channel given to this function may be an inbound or outbound
794  * channel. Both will have the necessary info on it.
795  *
796  * \param chan The channel from which to get the core_id.
797  * \retval core_id on success
798  * \retval -1 Failure
799  */
800 int ast_cc_get_current_core_id(struct ast_channel *chan);
801
802 /* END API FOR IN-CALL CC HANDLING */
803
804 /*!
805  * \brief Structure with information about an outbound interface
806  *
807  * \details
808  * This structure is first created when an outbound interface indicates that
809  * it is capable of accepting a CC request. It is stored in a "tree" on a datastore on
810  * the caller's channel. Once an agent structure is created, the agent gains
811  * a reference to the tree of interfaces. If CC is requested, then the
812  * interface tree on the agent is converted into a tree of monitors. Each
813  * monitor will contain a pointer to an individual ast_cc_interface. Finally,
814  * the tree of interfaces is also present on a second datastore during a
815  * CC recall so that the CC_INTERFACES channel variable may be properly
816  * populated.
817  */
818 struct ast_cc_interface {
819         /* What class of monitor is being offered here
820          */
821         enum ast_cc_monitor_class monitor_class;
822         /*!
823          * \brief The type of monitor that should be used for this interface
824          *
825          * \details
826          * This will be something like "extension" "generic" or "SIP".
827          * This should point to a static const char *, so there is
828          * no reason to make a new copy.
829          */
830         const char *monitor_type;
831         /*!
832          * The configuration parameters used for this interface
833          */
834         struct ast_cc_config_params *config_params;
835         /* The name of the interface/extension. local channels will
836          * have 'exten@context' for a name. Other channel types will
837          * have 'tech/device' for a name.
838          */
839         char device_name[1];
840 };
841
842 /* BEGIN STRUCTURES FOR AGENTS */
843
844 struct ast_cc_agent {
845         /*!
846          * Which instance of the core state machine does this
847          * agent pertain to?
848          */
849         unsigned int core_id;
850         /*!
851          * Callback functions needed for specific agent
852          * implementations
853          */
854         const struct ast_cc_agent_callbacks *callbacks;
855         /*!
856          * Configuration parameters that affect this
857          * agent's operation.
858          */
859         struct ast_cc_config_params *cc_params;
860         /*!
861          * \brief Flags for agent operation
862          *
863          * \details
864          * There are some attributes of certain agent types
865          * that can alter the behavior of certain CC functions.
866          * For a list of these flags, see the ast_cc_agent_flags
867          * enum
868          */
869         unsigned int flags;
870         /*! Data specific to agent implementation */
871         void *private_data;
872         /*! The name of the device which this agent
873          * represents/communicates with
874          */
875         char device_name[1];
876 };
877
878 enum ast_cc_agent_response_reason {
879         /*! CC request accepted */
880         AST_CC_AGENT_RESPONSE_SUCCESS,
881         /*! CC request not allowed at this time. Invalid state transition. */
882         AST_CC_AGENT_RESPONSE_FAILURE_INVALID,
883         /*! Too many CC requests in the system. */
884         AST_CC_AGENT_RESPONSE_FAILURE_TOO_MANY,
885 };
886
887 struct ast_cc_agent_callbacks {
888         /*!
889          * \brief Type of agent the callbacks belong to.
890          *
891          * \note
892          * Examples are "SIP" "ISDN" and "generic"
893          */
894         const char *type;
895         /*!
896          * \brief CC agent initialization.
897          *
898          * \param agent CC core agent control.
899          * \param chan Original channel the agent will attempt to recall.
900          *
901          * \details
902          * This callback is called when the CC core
903          * is initialized. Agents should allocate
904          * any private data necessary for the
905          * call and assign it to the private_data
906          * on the agent. Additionally, if any ast_cc_agent_flags
907          * are pertinent to the specific agent type, they should
908          * be set in this function as well.
909          *
910          * \retval 0 on success.
911          * \retval -1 on error.
912          */
913         int (*init)(struct ast_cc_agent *agent, struct ast_channel *chan);
914         /*!
915          * \brief Start the offer timer.
916          *
917          * \param agent CC core agent control.
918          *
919          * \details
920          * This is called by the core when the caller hangs up after
921          * a call for which CC may be requested. The agent should
922          * begin the timer as configured.
923          *
924          * The primary reason why this functionality is left to
925          * the specific agent implementations is due to the differing
926          * use of schedulers throughout the code. Some channel drivers
927          * may already have a scheduler context they wish to use, and
928          * amongst those, some may use the ast_sched API while others
929          * may use the ast_sched_thread API, which are incompatible.
930          *
931          * \retval 0 on success.
932          * \retval -1 on error.
933          */
934         int (*start_offer_timer)(struct ast_cc_agent *agent);
935         /*!
936          * \brief Stop the offer timer.
937          *
938          * \param agent CC core agent control.
939          *
940          * \details
941          * This callback is called by the CC core when the caller
942          * has requested CC.
943          *
944          * \retval 0 on success.
945          * \retval -1 on error.
946          */
947         int (*stop_offer_timer)(struct ast_cc_agent *agent);
948         /*!
949          * \brief Respond to a CC request.
950          *
951          * \param agent CC core agent control.
952          * \param reason CC request response status.
953          *
954          * \details
955          * When the core receives knowledge that a called
956          * party has accepted a CC request, it will call
957          * this callback. The core may also call this
958          * if there is some error when attempting to process
959          * the incoming CC request.
960          *
961          * The duty of this is to issue a propper response to a
962          * CC request from the caller by acknowledging receipt
963          * of that request or rejecting it.
964          */
965         void (*respond)(struct ast_cc_agent *agent, enum ast_cc_agent_response_reason reason);
966         /*!
967          * \brief Request the status of the agent's device.
968          *
969          * \param agent CC core agent control.
970          *
971          * \details
972          * Asynchronous request for the status of any caller
973          * which may be a valid caller for the CC transaction.
974          * Status responses should be made using the
975          * ast_cc_status_response function.
976          *
977          * \retval 0 on success.
978          * \retval -1 on error.
979          */
980         int (*status_request)(struct ast_cc_agent *agent);
981         /*!
982          * \brief Request for an agent's phone to stop ringing.
983          *
984          * \param agent CC core agent control.
985          *
986          * \details
987          * The usefulness of this is quite limited. The only specific
988          * known case for this is if Asterisk requests CC over an ISDN
989          * PTMP link as the TE side. If other phones are in the same
990          * recall group as the Asterisk server, and one of those phones
991          * picks up the recall notice, then Asterisk will receive a
992          * "stop ringing" notification from the NT side of the PTMP
993          * link. This indication needs to be passed to the phone
994          * on the other side of the Asterisk server which originally
995          * placed the call so that it will stop ringing. Since the
996          * phone may be of any type, it is necessary to have a callback
997          * that the core can know about.
998          *
999          * \retval 0 on success.
1000          * \retval -1 on error.
1001          */
1002         int (*stop_ringing)(struct ast_cc_agent *agent);
1003         /*!
1004          * \brief Let the caller know that the callee has become free
1005          * but that the caller cannot attempt to call back because
1006          * he is either busy or there is congestion on his line.
1007          *
1008          * \param agent CC core agent control.
1009          *
1010          * \details
1011          * This is something that really only affects a scenario where
1012          * a phone places a call over ISDN PTMP to Asterisk, who then
1013          * connects over PTMP again to the ISDN network. For most agent
1014          * types, there is no need to implement this callback at all
1015          * because they don't really need to actually do anything in
1016          * this situation. If you're having trouble understanding what
1017          * the purpose of this callback is, then you can be safe simply
1018          * not implementing it.
1019          *
1020          * \retval 0 on success.
1021          * \retval -1 on error.
1022          */
1023         int (*party_b_free)(struct ast_cc_agent *agent);
1024         /*!
1025          * \brief Begin monitoring a busy device.
1026          *
1027          * \param agent CC core agent control.
1028          *
1029          * \details
1030          * The core will call this callback if the callee becomes
1031          * available but the caller has reported that he is busy.
1032          * The agent should begin monitoring the caller's device.
1033          * When the caller becomes available again, the agent should
1034          * call ast_cc_agent_caller_available.
1035          *
1036          * \retval 0 on success.
1037          * \retval -1 on error.
1038          */
1039         int (*start_monitoring)(struct ast_cc_agent *agent);
1040         /*!
1041          * \brief Alert the caller that it is time to try recalling.
1042          *
1043          * \param agent CC core agent control.
1044          *
1045          * \details
1046          * The core will call this function when it receives notice
1047          * that a monitored party has become available.
1048          *
1049          * The agent's job is to send a message to the caller to
1050          * notify it of such a change. If the agent is able to
1051          * discern that the caller is currently unavailable, then
1052          * the agent should react by calling the ast_cc_caller_unavailable
1053          * function.
1054          *
1055          * \retval 0 on success.
1056          * \retval -1 on error.
1057          */
1058         int (*callee_available)(struct ast_cc_agent *agent);
1059         /*!
1060          * \brief Destroy private data on the agent.
1061          *
1062          * \param agent CC core agent control.
1063          *
1064          * \details
1065          * The core will call this function upon completion
1066          * or failure of CC.
1067          *
1068          * \note
1069          * The agent private_data pointer may be NULL if the agent
1070          * constructor failed.
1071          */
1072         void (*destructor)(struct ast_cc_agent *agent);
1073 };
1074
1075 /*!
1076  * \brief Call a callback on all agents of a specific type
1077  *
1078  * \details
1079  * Since the container of CC core instances is private, and so
1080  * are the items which the container contains, we have to provide
1081  * an ao2_callback-like method so that a specific agent may be
1082  * found or so that an operation can be made on all agents of
1083  * a particular type. The first three arguments should be familiar
1084  * to anyone who has used ao2_callback. The final argument is the
1085  * type of agent you wish to have the callback called on.
1086  *
1087  * \note Since agents are refcounted, and this function returns
1088  * a reference to the agent, it is imperative that you decrement
1089  * the refcount of the agent once you have finished using it.
1090  *
1091  * \param flags astobj2 search flags
1092  * \param function an ao2 callback function to call
1093  * \param arg the argument to the callback function
1094  * \param type The type of agents to call the callback on
1095  */
1096 struct ast_cc_agent *ast_cc_agent_callback(int flags, ao2_callback_fn *function, void *arg, const char * const type);
1097
1098 /* END STRUCTURES FOR AGENTS */
1099
1100 /* BEGIN STATE CHANGE API */
1101
1102 /*!
1103  * \since 1.8
1104  * \brief Offer CC to a caller
1105  *
1106  * \details
1107  * This function is called from ast_hangup if the caller is
1108  * eligible to be offered call completion service.
1109  *
1110  * \param caller_chan The calling channel
1111  * \retval -1 Error
1112  * \retval 0 Success
1113  */
1114 int ast_cc_offer(struct ast_channel *caller_chan);
1115
1116 /*!
1117  * \since 1.8
1118  * \brief Accept inbound CC request
1119  *
1120  * \details
1121  * When a caller requests CC, this function should be called to let
1122  * the core know that the request has been accepted.
1123  *
1124  * \param core_id core_id of the CC transaction
1125  * \param debug optional string to print for debugging purposes
1126  * \retval 0 Success
1127  * \retval -1 Failure
1128  */
1129 int __attribute__((format(printf, 2, 3))) ast_cc_agent_accept_request(int core_id, const char * const debug, ...);
1130
1131 /*!
1132  * \since 1.8
1133  * \brief Indicate that an outbound entity has accepted our CC request
1134  *
1135  * \details
1136  * When we receive confirmation that an outbound device has accepted the
1137  * CC request we sent it, this function must be called.
1138  *
1139  * \param core_id core_id of the CC transaction
1140  * \param debug optional string to print for debugging purposes
1141  * \retval 0 Success
1142  * \retval -1 Failure
1143  */
1144 int __attribute__((format(printf, 2, 3))) ast_cc_monitor_request_acked(int core_id, const char * const debug, ...);
1145
1146 /*!
1147  * \since 1.8
1148  * \brief Indicate that the caller is busy
1149  *
1150  * \details
1151  * When the callee makes it known that he is available, the core
1152  * will let the caller's channel driver know that it may attempt
1153  * to let the caller know to attempt a recall. If the channel
1154  * driver can detect, though, that the caller is busy, then
1155  * the channel driver should call this function to let the CC
1156  * core know.
1157  *
1158  * \param core_id core_id of the CC transaction
1159  * \param debug optional string to print for debugging purposes
1160  * \retval 0 Success
1161  * \retval -1 Failure
1162  */
1163 int __attribute__((format(printf, 2, 3))) ast_cc_agent_caller_busy(int core_id, const char * const debug, ...);
1164
1165 /*!
1166  * \since 1.8
1167  * \brief Indicate that a previously unavailable caller has become available
1168  *
1169  * \details
1170  * If a monitor is suspended due to a caller becoming unavailable, then this
1171  * function should be called to indicate that the caller has become available.
1172  *
1173  * \param core_id core_id of the CC transaction
1174  * \param debug optional string to print for debugging purposes
1175  * \retval 0 Success
1176  * \retval -1 Failure
1177  */
1178 int __attribute__((format(printf, 2, 3))) ast_cc_agent_caller_available(int core_id, const char * const debug, ...);
1179
1180 /*!
1181  * \since 1.8
1182  * \brief Tell the CC core that a caller is currently recalling
1183  *
1184  * \details
1185  * The main purpose of this is so that the core can alert the monitor
1186  * to stop its available timer since the caller has begun its recall
1187  * phase.
1188  *
1189  * \param core_id core_id of the CC transaction
1190  * \param debug optional string to print for debugging purposes
1191  * \retval 0 Success
1192  * \retval -1 Failure
1193  */
1194 int __attribute__((format(printf, 2, 3))) ast_cc_agent_recalling(int core_id, const char * const debug, ...);
1195
1196 /*!
1197  * \since 1.8
1198  * \brief Indicate recall has been acknowledged
1199  *
1200  * \details
1201  * When we receive confirmation that an endpoint has responded to our
1202  * CC recall, we call this function.
1203  *
1204  * \param chan The inbound channel making the CC recall
1205  * \param debug optional string to print for debugging purposes
1206  * \retval 0 Success
1207  * \retval -1 Failure
1208  */
1209 int __attribute__((format(printf, 2, 3))) ast_cc_completed(struct ast_channel *chan, const char * const debug, ...);
1210
1211 /*!
1212  * \since 1.8
1213  * \brief Indicate failure has occurred
1214  *
1215  * \details
1216  * If at any point a failure occurs, this is the function to call
1217  * so that the core can initiate cleanup procedures.
1218  *
1219  * \param core_id core_id of the CC transaction
1220  * \param debug optional string to print for debugging purposes
1221  * \retval 0 Success
1222  * \retval -1 Failure
1223  */
1224 int __attribute__((format(printf, 2, 3))) ast_cc_failed(int core_id, const char * const debug, ...);
1225
1226 /*!
1227  * \since 1.8
1228  * \brief Indicate that a failure has occurred on a specific monitor
1229  *
1230  * \details
1231  * If a monitor should detect that a failure has occurred when communicating
1232  * with its endpoint, then ast_cc_monitor_failed should be called. The big
1233  * difference between ast_cc_monitor_failed and ast_cc_failed is that ast_cc_failed
1234  * indicates a global failure for a CC transaction, where as ast_cc_monitor_failed
1235  * is localized to a particular monitor. When ast_cc_failed is called, the entire
1236  * CC transaction is torn down. When ast_cc_monitor_failed is called, only the
1237  * monitor on which the failure occurred is pruned from the tree of monitors.
1238  *
1239  * If there are no more devices left to monitor when this function is called,
1240  * then the core will fail the CC transaction globally.
1241  *
1242  * \param core_id The core ID for the CC transaction
1243  * \param monitor_name The name of the monitor on which the failure occurred
1244  * \param debug A debug message to print to the CC log
1245  * \return void
1246  */
1247 int __attribute__((format(printf, 3, 4))) ast_cc_monitor_failed(int core_id, const char * const monitor_name, const char * const debug, ...);
1248
1249 /* END STATE CHANGE API */
1250
1251 /*!
1252  * The following are all functions which are required due to the unique
1253  * case where Asterisk is acting as the NT side of an ISDN PTMP
1254  * connection to the caller and as the TE side of an ISDN PTMP connection
1255  * to the callee. In such a case, there are several times where the
1256  * PTMP monitor needs information from the agent in order to formulate
1257  * the appropriate messages to send.
1258  */
1259
1260 /*!
1261  * \brief Request the status of a caller or callers.
1262  *
1263  * \details
1264  * When an ISDN PTMP monitor senses that the callee has become
1265  * available, it needs to know the current status of the caller
1266  * in order to determine the appropriate response to send to
1267  * the caller. In order to do this, the monitor calls this function.
1268  * Responses will arrive asynchronously.
1269  *
1270  * \note Zero or more responses may come as a result.
1271  *
1272  * \param core_id The core ID of the CC transaction
1273  *
1274  * \retval 0 Successfully requested status
1275  * \retval -1 Failed to request status
1276  */
1277 int ast_cc_monitor_status_request(int core_id);
1278
1279 /*!
1280  * \brief Response with a caller's current status
1281  *
1282  * \details
1283  * When an ISDN PTMP monitor requests the caller's status, the
1284  * agent must respond to the request using this function. For
1285  * simplicity it is recommended that the devstate parameter
1286  * be one of AST_DEVICE_INUSE or AST_DEVICE_NOT_INUSE.
1287  *
1288  * \param core_id The core ID of the CC transaction
1289  * \param devstate The current state of the caller to which the agent pertains
1290  * \retval 0 Successfully responded with our status
1291  * \retval -1 Failed to respond with our status
1292  */
1293 int ast_cc_agent_status_response(int core_id, enum ast_device_state devstate);
1294
1295 /*!
1296  * \brief Alert a caller to stop ringing
1297  *
1298  * \details
1299  * When an ISDN PTMP monitor becomes available, it is assumed
1300  * that the agent will then cause the caller's phone to ring. In
1301  * some cases, this is literally what happens. In other cases, it may
1302  * be that the caller gets a visible indication on his phone that he
1303  * may attempt to recall the callee. If multiple callers are recalled
1304  * (since it may be possible to have a group of callers configured as
1305  * a single party A), and one of those callers picks up his phone, then
1306  * the ISDN PTMP monitor will alert the other callers to stop ringing.
1307  * The agent's stop_ringing callback will be called, and it is up to the
1308  * agent's driver to send an appropriate message to make his caller
1309  * stop ringing.
1310  *
1311  * \param core_id The core ID of the CC transaction
1312  * \retval 0 Successfully requested for the phone to stop ringing
1313  * \retval -1 Could not request for the phone to stop ringing
1314  */
1315 int ast_cc_monitor_stop_ringing(int core_id);
1316
1317 /*!
1318  * \brief Alert a caller that though the callee has become free, the caller
1319  * himself is not and may not call back.
1320  *
1321  * \details
1322  * When an ISDN PTMP monitor senses that his monitored party has become
1323  * available, he will request the status of the called party. If he determines
1324  * that the caller is currently not available, then he will call this function
1325  * so that an appropriate message is sent to the caller.
1326  *
1327  * Yes, you just read that correctly. The callee asks the caller what his
1328  * current status is, and if the caller is currently unavailable, the monitor
1329  * must send him a message anyway. WTF?
1330  *
1331  * This function results in the agent's party_b_free callback being called.
1332  * It is most likely that you will not need to actually implement the
1333  * party_b_free callback in an agent because it is not likely that you will
1334  * need to or even want to send a caller a message indicating the callee's
1335  * status if the caller himself is not also free.
1336  *
1337  * \param core_id The core ID of the CC transaction
1338  * \retval 0 Successfully alerted the core that party B is free
1339  * \retval -1 Could not alert the core that party B is free
1340  */
1341 int ast_cc_monitor_party_b_free(int core_id);
1342
1343 /* BEGIN API FOR USE WITH/BY MONITORS */
1344
1345 /*!
1346  * \since 1.8
1347  * \brief Return the number of outstanding CC requests to a specific device
1348  *
1349  * \note
1350  * This function will lock the list of monitors stored on every instance of
1351  * the CC core. Callers of this function should be aware of this and avoid
1352  * any potential lock ordering problems.
1353  *
1354  * \param name The name of the monitored device
1355  * \param type The type of the monitored device (e.g. "generic")
1356  * \return The number of CC requests for the monitor
1357  */
1358 int ast_cc_monitor_count(const char * const name, const char * const type);
1359
1360 /*!
1361  * \since 1.8
1362  * \brief Alert the core that a device being monitored has become available.
1363  *
1364  * \note
1365  * The code in the core will take care of making sure that the information gets passed
1366  * up the ladder correctly.
1367  *
1368  * \param core_id The core ID of the corresponding CC transaction
1369  * \param debug
1370  * \retval 0 Request successfully queued
1371  * \retval -1 Request could not be queued
1372  */
1373 int __attribute__((format(printf, 2, 3))) ast_cc_monitor_callee_available(const int core_id, const char * const debug, ...);
1374
1375 /* END API FOR USE WITH/BY MONITORS */
1376
1377 /* BEGIN API TO BE USED ON CC RECALL */
1378
1379 /*!
1380  * \since 1.8
1381  * \brief Set up a CC recall datastore on a channel
1382  *
1383  * \details
1384  * Implementers of protocol-specific CC agents will need to call this
1385  * function in order for the channel to have the necessary interfaces
1386  * to recall.
1387  *
1388  * This function must be called by the implementer once it has been detected
1389  * that an inbound call is a cc_recall. After allocating the channel, call this
1390  * function, followed by ast_cc_set_cc_interfaces_chanvar. While it would be nice to
1391  * be able to have the core do this automatically, it just cannot be done given
1392  * the current architecture.
1393  */
1394 int ast_setup_cc_recall_datastore(struct ast_channel *chan, const int core_id);
1395
1396 /*!
1397  * \since 1.8
1398  * \brief Decide if a call to a particular channel is a CC recall
1399  *
1400  * \details
1401  * When a CC recall happens, it is important on the called side to
1402  * know that the call is a CC recall and not a normal call. This function
1403  * will determine first if the call in question is a CC recall. Then it
1404  * will determine based on the chan parameter if the channel is being
1405  * called is being recalled.
1406  *
1407  * As a quick example, let's say a call is placed to SIP/1000 and SIP/1000
1408  * is currently on the phone. The caller requests CCBS. SIP/1000 finishes
1409  * his call, and so the caller attempts to recall. Now, the dialplan
1410  * administrator has set up this second call so that not only is SIP/1000
1411  * called, but also SIP/2000 is called. If SIP/1000's channel were passed
1412  * to this function, the return value would be non-zero, but if SIP/2000's
1413  * channel were passed into this function, then the return would be 0 since
1414  * SIP/2000 was not one of the original devices dialed.
1415  *
1416  * \note
1417  * This function may be called on a calling channel as well to
1418  * determine if it is part of a CC recall.
1419  *
1420  * \note
1421  * This function will lock the channel as well as the list of monitors
1422  * on the channel datastore, though the locks are not held at the same time. Be
1423  * sure that you have no potential lock order issues here.
1424  *
1425  * \param chan The channel to check
1426  * \param[out] core_id If this is a valid CC recall, the core_id of the failed call
1427  * will be placed in this output parameter
1428  * \param monitor_type Clarify which type of monitor type we are looking for if this
1429  * is happening on a called channel. For incoming channels, this parameter is not used.
1430  * \retval 0 Either this is not a recall or it is but this channel is not part of the recall
1431  * \retval non-zero This is a recall and the channel in question is directly involved.
1432  */
1433 int ast_cc_is_recall(struct ast_channel *chan, int *core_id, const char * const monitor_type);
1434
1435 /*!
1436  * \since 1.8
1437  * \brief Get the associated monitor given the device name and core_id
1438  *
1439  * \details
1440  * The function ast_cc_is_recall is helpful for determining if a call to
1441  * a specific channel is a recall. However, once you have determined that
1442  * this is a recall, you will most likely need access to the private data
1443  * within the associated monitor. This function is what one uses to get
1444  * that monitor.
1445  *
1446  * \note
1447  * This function locks the list of monitors that correspond to the core_id
1448  * passed in. Be sure that you have no potential lock order issues when
1449  * calling this function.
1450  *
1451  * \param core_id The core ID to which this recall corresponds. This likely will
1452  * have been obtained using the ast_cc_is_recall function
1453  * \param device_name Which device to find the monitor for.
1454  *
1455  * \retval NULL Appropriate monitor does not exist
1456  * \retval non-NULL The monitor to use for this recall
1457  */
1458 struct ast_cc_monitor *ast_cc_get_monitor_by_recall_core_id(const int core_id, const char * const device_name);
1459
1460 /*!
1461  * \since 1.8
1462  * \brief Set the first level CC_INTERFACES channel variable for a channel.
1463  *
1464  * \note
1465  * Implementers of protocol-specific CC agents should call this function after
1466  * calling ast_setup_cc_recall_datastore.
1467  *
1468  * \note
1469  * This function will lock the channel as well as the list of monitors stored
1470  * on the channel's CC recall datastore, though neither are held at the same
1471  * time. Callers of this function should be aware of potential lock ordering
1472  * problems that may arise.
1473  *
1474  * \details
1475  * The CC_INTERFACES channel variable will have the interfaces that should be
1476  * called back for a specific PBX instance.
1477  *
1478  * \param chan The channel to set the CC_INTERFACES variable on
1479  */
1480 int ast_cc_agent_set_interfaces_chanvar(struct ast_channel *chan);
1481
1482 /*!
1483  * \since 1.8
1484  * \brief Set the CC_INTERFACES channel variable for a channel using an
1485  * extension@context as a starting point
1486  *
1487  * \details
1488  * The CC_INTERFACES channel variable will have the interfaces that should be
1489  * called back for a specific PBX instance. This version of the function is used
1490  * mainly by chan_local, wherein we need to set CC_INTERFACES based on an extension
1491  * and context that appear in the middle of the tree of dialed interfaces
1492  *
1493  * \note
1494  * This function will lock the channel as well as the list of monitors stored
1495  * on the channel's CC recall datastore, though neither are held at the same
1496  * time. Callers of this function should be aware of potential lock ordering
1497  * problems that may arise.
1498  *
1499  * \param chan The channel to set the CC_INTERFACES variable on
1500  * \param extension The name of the extension for which we're setting the variable.
1501  * This should be in the form of "exten@context"
1502  */
1503 int ast_set_cc_interfaces_chanvar(struct ast_channel *chan, const char * const extension);
1504
1505 /*!
1506  * \since 1.8
1507  * \brief Make CCBS available in the case that ast_call fails
1508  *
1509  * In some situations, notably if a call-limit is reached in SIP, ast_call will fail
1510  * due to Asterisk's knowing that the desired device is currently busy. In such a situation,
1511  * CCBS should be made available to the caller.
1512  *
1513  * One caveat is that this may only be used if generic monitoring is being used. The reason
1514  * is that since Asterisk determined that the device was busy without actually placing a call to it,
1515  * the far end will have no idea what call we are requesting call completion for if we were to send
1516  * a call completion request.
1517  */
1518 void ast_cc_call_failed(struct ast_channel *incoming, struct ast_channel *outgoing, const char * const dialstring);
1519
1520 /*!
1521  * \since 1.8
1522  * \brief Callback made from ast_cc_callback for certain channel types
1523  *
1524  * \param inbound Incoming asterisk channel.
1525  * \param cc_params The CC configuration parameters for the outbound target
1526  * \param monitor_type The type of monitor to use when CC is requested
1527  * \param device_name The name of the outbound target device.
1528  * \param dialstring The dial string used when calling this specific interface
1529  * \param private_data If a native monitor is being used, and some channel-driver-specific private
1530  * data has been allocated, then this parameter should contain a pointer to that data. If using a generic
1531  * monitor, this parameter should remain NULL. Note that if this function should fail at some point,
1532  * it is the responsibility of the caller to free the private data upon return.
1533  *
1534  * \details
1535  * For channel types that fail ast_request when the device is busy, we call into the
1536  * channel driver with ast_cc_callback. This is the callback that is called in that
1537  * case for each device found which could have been returned by ast_request.
1538  *
1539  * This function creates a CC control frame payload, simulating the act of reading
1540  * it from the nonexistent outgoing channel's frame queue. We then handle this
1541  * simulated frame just as we would a normal CC frame which had actually been queued
1542  * by the channel driver.
1543  */
1544 void ast_cc_busy_interface(struct ast_channel *inbound, struct ast_cc_config_params *cc_params,
1545         const char *monitor_type, const char * const device_name, const char * const dialstring, void *private_data);
1546
1547 /*!
1548  * \since 1.8
1549  * \brief Create a CC Control frame
1550  *
1551  * \details
1552  * chan_dahdi is weird. It doesn't seem to actually queue frames when it needs to tell
1553  * an application something. Instead it wakes up, tells the application that it has data
1554  * ready, and then based on set flags, creates the proper frame type. For chan_dahdi, we
1555  * provide this function. It provides us the data we need, and we'll make its frame for it.
1556  *
1557  * \param chan A channel involved in the call. What we want is on a datastore on both incoming 
1558  * and outgoing so either may be provided
1559  * \param cc_params The CC configuration parameters for the outbound target
1560  * \param monitor_type The type of monitor to use when CC is requested
1561  * \param device_name The name of the outbound target device.
1562  * \param dialstring The dial string used when calling this specific interface
1563  * \param service What kind of CC service is being offered. (CCBS/CCNR/etc...)
1564  * \param private_data If a native monitor is being used, and some channel-driver-specific private
1565  * data has been allocated, then this parameter should contain a pointer to that data. If using a generic
1566  * monitor, this parameter should remain NULL. Note that if this function should fail at some point,
1567  * it is the responsibility of the caller to free the private data upon return.
1568  * \param[out] frame The frame we will be returning to the caller. It is vital that ast_frame_free be 
1569  * called on this frame since the payload will be allocated on the heap.
1570  * \retval -1 Failure. At some point there was a failure. Do not attempt to use the frame in this case.
1571  * \retval 0 Success
1572  */
1573 int ast_cc_build_frame(struct ast_channel *chan, struct ast_cc_config_params *cc_params,
1574         const char *monitor_type, const char * const device_name,
1575         const char * const dialstring, enum ast_cc_service_type service, void *private_data,
1576         struct ast_frame *frame);
1577
1578
1579 /*!
1580  * \brief Callback made from ast_cc_callback for certain channel types
1581  * \since 1.8
1582  *
1583  * \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
1584  * \param cc_params The CC configuration parameters for the outbound target
1585  * \param monitor_type The type of monitor to use when CC is requested
1586  * \param device_name The name of the outbound target device.
1587  * \param dialstring The dial string used when calling this specific interface
1588  * \param private_data If a native monitor is being used, and some channel-driver-specific private
1589  * data has been allocated, then this parameter should contain a pointer to that data. If using a generic
1590  * monitor, this parameter should remain NULL. Note that if this function should fail at some point,
1591  * it is the responsibility of the caller to free the private data upon return.
1592  *
1593  * \details
1594  * For channel types that fail ast_request when the device is busy, we call into the
1595  * channel driver with ast_cc_callback. This is the callback that is called in that
1596  * case for each device found which could have been returned by ast_request.
1597  *
1598  * \return Nothing
1599  */
1600 typedef void (*ast_cc_callback_fn)(struct ast_channel *chan, struct ast_cc_config_params *cc_params,
1601         const char *monitor_type, const char * const device_name, const char * const dialstring, void *private_data);
1602
1603 /*!
1604  * \since 1.8
1605  * \brief Run a callback for potential matching destinations.
1606  *
1607  * \note
1608  * See the explanation in ast_channel_tech::cc_callback for more
1609  * details.
1610  *
1611  * \param inbound
1612  * \param tech Channel technology to use
1613  * \param dest Channel/group/peer or whatever the specific technology uses
1614  * \param callback Function to call when a target is reached
1615  * \retval Always 0, I guess.
1616  */
1617 int ast_cc_callback(struct ast_channel *inbound, const char * const tech, const char * const dest, ast_cc_callback_fn callback);
1618
1619 /*!
1620  * \since 1.8
1621  * \brief Initialize CCSS
1622  *
1623  * Performs startup routines necessary for CC operation.
1624  *
1625  * \retval 0 Success
1626  * \retval nonzero Failure
1627  */
1628 int ast_cc_init(void);
1629
1630 #endif /* _ASTERISK_CCSS_H */