Asterisk - The Open Source Telephony Project  GIT-master-a1fa8df
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 
33  /* No Service available/requested */
35  /* Call Completion Busy Subscriber */
37  /* Call Completion No Response */
39  /* Call Completion Not Logged In (currently SIP only) */
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  */
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 */
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  * \retval void
145  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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 
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 
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  */
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  */
511  /*!
512  * Information regarding the interface.
513  */
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  */
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  */
548  /*!
549  * Monitor callbacks
550  */
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  */
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  */
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  */
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  */
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  */
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  */
855  /*!
856  * Configuration parameters that affect this
857  * agent's operation.
858  */
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 */
872  /*! The name of the device which this agent
873  * represents/communicates with
874  */
875  char device_name[1];
876 };
877 
879  /*! CC request accepted */
881  /*! CC request not allowed at this time. Invalid state transition. */
883  /*! Too many CC requests in the system. */
885 };
886 
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  * \par core_id The core ID of the corresponding CC transaction
1369  * \par 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  */
1481 
1482 /*!
1483  * \since 1.8
1484  * \brief Set the CC_INTERFACES channel variable for a channel using an
1485  * \verbatim extension@context \endverbatim as a starting point
1486  *
1487  * \details
1488  * The CC_INTERFACES channel variable will have the interfaces
1489  * that should be called back for a specific PBX instance. This
1490  * version of the function is used mainly by local channels,
1491  * wherein we need to set CC_INTERFACES based on an extension
1492  * and context that appear in the middle of the tree of dialed
1493  * interfaces.
1494  *
1495  * \note
1496  * This function will lock the channel as well as the list of monitors stored
1497  * on the channel's CC recall datastore, though neither are held at the same
1498  * time. Callers of this function should be aware of potential lock ordering
1499  * problems that may arise.
1500  *
1501  * \param chan The channel to set the CC_INTERFACES variable on
1502  * \param extension The name of the extension for which we're setting the variable.
1503  * This should be in the form of \verbatim exten@context \endverbatim
1504  */
1505 int ast_set_cc_interfaces_chanvar(struct ast_channel *chan, const char * const extension);
1506 
1507 /*!
1508  * \since 1.8
1509  * \brief Make CCBS available in the case that ast_call fails
1510  *
1511  * In some situations, notably if a call-limit is reached in SIP, ast_call will fail
1512  * due to Asterisk's knowing that the desired device is currently busy. In such a situation,
1513  * CCBS should be made available to the caller.
1514  *
1515  * One caveat is that this may only be used if generic monitoring is being used. The reason
1516  * is that since Asterisk determined that the device was busy without actually placing a call to it,
1517  * the far end will have no idea what call we are requesting call completion for if we were to send
1518  * a call completion request.
1519  */
1520 void ast_cc_call_failed(struct ast_channel *incoming, struct ast_channel *outgoing, const char * const dialstring);
1521 
1522 /*!
1523  * \since 1.8
1524  * \brief Callback made from ast_cc_callback for certain channel types
1525  *
1526  * \param inbound Incoming asterisk channel.
1527  * \param cc_params The CC configuration parameters for the outbound target
1528  * \param monitor_type The type of monitor to use when CC is requested
1529  * \param device_name The name of the outbound target device.
1530  * \param dialstring The dial string used when calling this specific interface
1531  * \param private_data If a native monitor is being used, and some channel-driver-specific private
1532  * data has been allocated, then this parameter should contain a pointer to that data. If using a generic
1533  * monitor, this parameter should remain NULL. Note that if this function should fail at some point,
1534  * it is the responsibility of the caller to free the private data upon return.
1535  *
1536  * \details
1537  * For channel types that fail ast_request when the device is busy, we call into the
1538  * channel driver with ast_cc_callback. This is the callback that is called in that
1539  * case for each device found which could have been returned by ast_request.
1540  *
1541  * This function creates a CC control frame payload, simulating the act of reading
1542  * it from the nonexistent outgoing channel's frame queue. We then handle this
1543  * simulated frame just as we would a normal CC frame which had actually been queued
1544  * by the channel driver.
1545  */
1546 void ast_cc_busy_interface(struct ast_channel *inbound, struct ast_cc_config_params *cc_params,
1547  const char *monitor_type, const char * const device_name, const char * const dialstring, void *private_data);
1548 
1549 /*!
1550  * \since 1.8
1551  * \brief Create a CC Control frame
1552  *
1553  * \details
1554  * chan_dahdi is weird. It doesn't seem to actually queue frames when it needs to tell
1555  * an application something. Instead it wakes up, tells the application that it has data
1556  * ready, and then based on set flags, creates the proper frame type. For chan_dahdi, we
1557  * provide this function. It provides us the data we need, and we'll make its frame for it.
1558  *
1559  * \param chan A channel involved in the call. What we want is on a datastore on both incoming
1560  * and outgoing so either may be provided
1561  * \param cc_params The CC configuration parameters for the outbound target
1562  * \param monitor_type The type of monitor to use when CC is requested
1563  * \param device_name The name of the outbound target device.
1564  * \param dialstring The dial string used when calling this specific interface
1565  * \param service What kind of CC service is being offered. (CCBS/CCNR/etc...)
1566  * \param private_data If a native monitor is being used, and some channel-driver-specific private
1567  * data has been allocated, then this parameter should contain a pointer to that data. If using a generic
1568  * monitor, this parameter should remain NULL. Note that if this function should fail at some point,
1569  * it is the responsibility of the caller to free the private data upon return.
1570  * \param[out] frame The frame we will be returning to the caller. It is vital that ast_frame_free be
1571  * called on this frame since the payload will be allocated on the heap.
1572  * \retval -1 Failure. At some point there was a failure. Do not attempt to use the frame in this case.
1573  * \retval 0 Success
1574  */
1575 int ast_cc_build_frame(struct ast_channel *chan, struct ast_cc_config_params *cc_params,
1576  const char *monitor_type, const char * const device_name,
1577  const char * const dialstring, enum ast_cc_service_type service, void *private_data,
1578  struct ast_frame *frame);
1579 
1580 
1581 /*!
1582  * \brief Callback made from ast_cc_callback for certain channel types
1583  * \since 1.8
1584  *
1585  * \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
1586  * \param cc_params The CC configuration parameters for the outbound target
1587  * \param monitor_type The type of monitor to use when CC is requested
1588  * \param device_name The name of the outbound target device.
1589  * \param dialstring The dial string used when calling this specific interface
1590  * \param private_data If a native monitor is being used, and some channel-driver-specific private
1591  * data has been allocated, then this parameter should contain a pointer to that data. If using a generic
1592  * monitor, this parameter should remain NULL. Note that if this function should fail at some point,
1593  * it is the responsibility of the caller to free the private data upon return.
1594  *
1595  * \details
1596  * For channel types that fail ast_request when the device is busy, we call into the
1597  * channel driver with ast_cc_callback. This is the callback that is called in that
1598  * case for each device found which could have been returned by ast_request.
1599  *
1600  * \return Nothing
1601  */
1602 typedef void (*ast_cc_callback_fn)(struct ast_channel *chan, struct ast_cc_config_params *cc_params,
1603  const char *monitor_type, const char * const device_name, const char * const dialstring, void *private_data);
1604 
1605 /*!
1606  * \since 1.8
1607  * \brief Run a callback for potential matching destinations.
1608  *
1609  * \note
1610  * See the explanation in ast_channel_tech::cc_callback for more
1611  * details.
1612  *
1613  * \param inbound
1614  * \param tech Channel technology to use
1615  * \param dest Channel/group/peer or whatever the specific technology uses
1616  * \param callback Function to call when a target is reached
1617  * \retval Always 0, I guess.
1618  */
1619 int ast_cc_callback(struct ast_channel *inbound, const char * const tech, const char * const dest, ast_cc_callback_fn callback);
1620 
1621 #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:1602
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:3941
int ast_cc_agent_register(const struct ast_cc_agent_callbacks *callbacks)
Register a set of agent callbacks with the core.
Definition: ccss.c:1239
static const char type[]
Definition: chan_ooh323.c:109
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:871
const char * ast_get_cc_callback_sub(struct ast_cc_config_params *config)
Get the name of the callback subroutine.
Definition: ccss.c:999
Main Channel structure associated with a channel.
struct ast_cc_monitor * next
Definition: ccss.h:562
ast_device_state
Device States.
Definition: devicestate.h:52
const char * type
Type of monitor the callbacks belong to.
Definition: ccss.h:583
void ast_cc_agent_unregister(const struct ast_cc_agent_callbacks *callbacks)
Unregister a set of agent callbacks with the core.
Definition: ccss.c:1254
static const char name[]
Definition: format_mp3.c:68
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:3879
void * private_data
Definition: ccss.h:871
static const char config[]
Definition: chan_ooh323.c:111
void ast_cc_config_params_destroy(struct ast_cc_config_params *params)
Free memory from CCSS configuration params.
Definition: ccss.c:693
static void unsuspend(struct cc_core_instance *core_instance)
Definition: ccss.c:3146
unsigned int id
Definition: ccss.h:519
int ast_cc_get_current_core_id(struct ast_channel *chan)
Get the core id for the current call.
Definition: ccss.c:2487
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:4368
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
int ast_cc_is_config_param(const char *const name)
Is this a CCSS configuration parameter?
Definition: ccss.c:846
unsigned int ast_get_cc_max_monitors(struct ast_cc_config_params *config)
Get the cc_max_monitors.
Definition: ccss.c:984
struct ast_cc_config_params * cc_params
Definition: ccss.h:859
static int debug
Global debug status.
Definition: res_xmpp.c:435
unsigned int ast_get_cc_recall_timer(struct ast_cc_config_params *config)
Get the cc_recall_timer.
Definition: ccss.c:930
int ast_cc_agent_caller_busy(int core_id, const char *const debug,...)
Indicate that the caller is busy.
Definition: ccss.c:3809
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&#39;s current status.
Definition: ccss.c:4093
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:3787
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:4051
enum ast_cc_service_type service
Definition: chan_sip.c:953
int ast_cc_available_timer_expire(const void *data)
Scheduler callback for available timer expiration.
Definition: ccss.c:1509
void ast_set_cc_max_monitors(struct ast_cc_config_params *config, unsigned int value)
Set the cc_max_monitors.
Definition: ccss.c:989
Scheduler ID holder.
Definition: sched.c:70
const struct ast_cc_monitor_callbacks * callbacks
Definition: ccss.h:551
ast_cc_agent_response_reason
Definition: ccss.h:878
void ast_set_ccnr_available_timer(struct ast_cc_config_params *config, unsigned int value)
Set the ccnr_available_timer.
Definition: ccss.c:920
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:4149
int ast_cc_agent_accept_request(int core_id, const char *const debug,...)
Accept inbound CC request.
Definition: ccss.c:3776
int value
Definition: syslog.c:37
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:3831
ast_cc_service_type
Definition: ccss.h:32
void ast_set_cc_offer_timer(struct ast_cc_config_params *config, unsigned int value)
Set the cc_offer_timer.
Definition: ccss.c:905
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:3438
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:2316
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:974
unsigned int parent_id
Definition: ccss.h:524
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:4199
enum ast_cc_monitor_policies ast_get_cc_monitor_policy(struct ast_cc_config_params *config)
Get the cc_monitor_policy.
Definition: ccss.c:883
int ast_cc_completed(struct ast_channel *chan, const char *const debug,...)
Indicate recall has been acknowledged.
Definition: ccss.c:3842
void ast_set_cc_callback_macro(struct ast_cc_config_params *config, const char *const value)
Set the callback_macro name.
Definition: ccss.c:1004
unsigned int ast_get_ccbs_available_timer(struct ast_cc_config_params *config)
Get the ccbs_available_timer.
Definition: ccss.c:945
void ast_cc_default_config_params(struct ast_cc_config_params *params)
Set the specified CC config params to default values.
Definition: ccss.c:676
int ast_cc_monitor_register(const struct ast_cc_monitor_callbacks *callbacks)
Register a set of monitor callbacks with the core.
Definition: ccss.c:1184
int() ao2_callback_fn(void *obj, void *arg, int flags)
Type of a generic callback function.
Definition: astobj2.h:1230
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:2005
unsigned int ast_get_ccnr_available_timer(struct ast_cc_config_params *config)
Get the ccnr_available_timer.
Definition: ccss.c:915
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:3631
int core_id
Definition: ccss.h:528
void ast_set_cc_callback_sub(struct ast_cc_config_params *config, const char *const value)
Set the callback subroutine name.
Definition: ccss.c:1014
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:3405
static void request_cc(struct cc_core_instance *core_instance)
Definition: ccss.c:3108
Structure with information about an outbound interface.
Definition: ccss.h:818
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:759
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:4176
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:3820
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:804
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:960
void ast_set_cc_recall_timer(struct ast_cc_config_params *config, unsigned int value)
Set the cc_recall_timer.
Definition: ccss.c:935
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:4244
int ast_cc_call_init(struct ast_channel *chan, int *ignore_cc)
Start the CC process on a call.
Definition: ccss.c:2409
struct ast_cc_config_params * config_params
Definition: ccss.h:834
const char * ast_get_cc_callback_macro(struct ast_cc_config_params *config)
Get the name of the callback_macro.
Definition: ccss.c:994
const char * type
Type of agent the callbacks belong to.
Definition: ccss.h:894
int ast_cc_offer(struct ast_channel *caller_chan)
Offer CC to a caller.
Definition: ccss.c:3751
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:681
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:409
unsigned int core_id
Definition: ccss.h:849
int ast_cc_monitor_status_request(int core_id)
Request the status of a caller or callers.
Definition: ccss.c:3986
static void cancel_available_timer(struct cc_core_instance *core_instance)
Definition: ccss.c:3226
char * dialstring
Name that should be used to recall specified interface.
Definition: ccss.h:543
const char * monitor_type
The type of monitor that should be used for this interface.
Definition: ccss.h:830
unsigned int ast_get_cc_offer_timer(struct ast_cc_config_params *config)
Get the cc_offer_timer.
Definition: ccss.c:900
static void suspend(struct cc_core_instance *core_instance)
Definition: ccss.c:3193
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:2482
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:861
struct ast_cc_interface * interface
Definition: ccss.h:514
void ast_set_ccbs_available_timer(struct ast_cc_config_params *config, unsigned int value)
Set the ccbs_available_timer.
Definition: ccss.c:950
void ast_set_cc_max_agents(struct ast_cc_config_params *config, unsigned int value)
Set the cc_max_agents.
Definition: ccss.c:979
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:4232
void ast_ignore_cc(struct ast_channel *chan)
Mark the channel to ignore further CC activity.
Definition: ccss.c:3720
const struct ast_cc_agent_callbacks * callbacks
Definition: ccss.h:854
char device_name[1]
Definition: ccss.h:875
void ast_set_cc_agent_dialstring(struct ast_cc_config_params *config, const char *const value)
Set the cc_agent_dialstring.
Definition: ccss.c:965
unsigned int flags
Flags for agent operation.
Definition: ccss.h:869
int available_timer_id
Definition: ccss.h:547
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:1217
void * private_data
Data that is private to a monitor technology.
Definition: ccss.h:561
Callbacks defined by CC monitors.
Definition: ccss.h:576
enum ast_cc_service_type service_offered
Definition: ccss.h:532
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:3519
int ast_cc_monitor_stop_ringing(int core_id)
Alert a caller to stop ringing.
Definition: ccss.c:4023
static snd_pcm_format_t format
Definition: chan_alsa.c:106
enum ast_cc_agent_policies ast_get_cc_agent_policy(struct ast_cc_config_params *config)
Get the cc_agent_policy.
Definition: ccss.c:866
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:888
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:3798
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:3668
ast_cc_monitor_class
Definition: ccss.h:496