Wed Jan 8 2020 09:49:42

Asterisk developer's documentation


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