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