b0829ab7363266155e869e878f3f0eb6fbbad20e
[asterisk/asterisk.git] / include / asterisk / stasis_app.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2012 - 2013, Digium, Inc.
5  *
6  * David M. Lee, II <dlee@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 #ifndef _ASTERISK_STASIS_APP_H
20 #define _ASTERISK_STASIS_APP_H
21
22 /*! \file
23  *
24  * \brief Stasis Application API. See \ref res_stasis "Stasis Application API"
25  * for detailed documentation.
26  *
27  * \author David M. Lee, II <dlee@digium.com>
28  * \since 12
29  *
30  * \page res_stasis Stasis Application API
31  *
32  * This is the API that binds the Stasis dialplan application to external
33  * Stasis applications, such as \c res_stasis_websocket.
34  *
35  * The associated \c res_stasis module registers a dialplan function named \c
36  * Stasis, which uses \c res_stasis to put a channel into the named Stasis
37  * app. As a channel enters and leaves the Stasis diaplan application, the
38  * Stasis app receives a \c 'stasis-start' and \c 'stasis-end' events.
39  *
40  * Stasis apps register themselves using the \ref stasis_app_register and
41  * stasis_app_unregister functions. Messages are sent to an appliction using
42  * \ref stasis_app_send.
43  *
44  * Finally, Stasis apps control channels through the use of the \ref
45  * stasis_app_control object, and the family of \c stasis_app_control_*
46  * functions.
47  *
48  * Since module unload order is based on reference counting, any module that
49  * uses the API defined in this file must list "res_stasis" in the requires
50  * field.
51  */
52
53 #include "asterisk/channel.h"
54
55 /*! @{ */
56
57 /*!
58  * \brief Callback for Stasis application handler.
59  *
60  * The message given to the handler is a borrowed copy. If you want to keep a
61  * reference to it, you should use \c ao2_ref() to keep it around.
62  *
63  * \param data Data ptr given when registered.
64  * \param app_name Name of the application being dispatched to.
65  * \param message Message to handle. (borrowed copy)
66  */
67 typedef void (*stasis_app_cb)(void *data, const char *app_name,
68         struct ast_json *message);
69
70 /*!
71  * \brief Gets the names of all registered Stasis applications.
72  *
73  * \return \c ast_str_container of container names.
74  * \return \c NULL on error.
75  */
76 struct ao2_container *stasis_app_get_all(void);
77
78 /*!
79  * \brief Retrieve a handle to a Stasis application by its name
80  *
81  * \param name The name of the registered Stasis application
82  *
83  * \return \c stasis_app on success.
84  * \return \c NULL on error.
85  */
86 struct stasis_app *stasis_app_get_by_name(const char *name);
87
88 /*!
89  * \brief Register a new Stasis application.
90  *
91  * If an application is already registered with the given name, the old
92  * application is sent a 'replaced' message and unregistered.
93  *
94  * \param app_name Name of this application.
95  * \param handler Callback for application messages.
96  * \param data Data blob to pass to the callback. Must be AO2 managed.
97  *
98  * \return 0 for success
99  * \return -1 for error.
100  */
101 int stasis_app_register(const char *app_name, stasis_app_cb handler, void *data);
102
103 /*!
104  * \brief Register a new Stasis application that receives all Asterisk events.
105  *
106  * If an application is already registered with the given name, the old
107  * application is sent a 'replaced' message and unregistered.
108  *
109  * \param app_name Name of this application.
110  * \param handler Callback for application messages.
111  * \param data Data blob to pass to the callback. Must be AO2 managed.
112  *
113  * \return 0 for success
114  * \return -1 for error.
115  */
116 int stasis_app_register_all(const char *app_name, stasis_app_cb handler, void *data);
117
118 /*!
119  * \brief Unregister a Stasis application.
120  * \param app_name Name of the application to unregister.
121  */
122 void stasis_app_unregister(const char *app_name);
123
124 /*!
125  * \brief Send a message to the given Stasis application.
126  *
127  * The message given to the handler is a borrowed copy. If you want to keep a
128  * reference to it, you should use \c ao2_ref() to keep it around.
129  *
130  * \param app_name Name of the application to invoke.
131  * \param message Message to send (borrowed reference)
132  *
133  * \return 0 for success.
134  * \return -1 for error.
135  */
136 int stasis_app_send(const char *app_name, struct ast_json *message);
137
138 /*! \brief Forward declare app */
139 struct stasis_app;
140
141 /*!
142  * \brief Retrieve an application's name
143  *
144  * \param app An application
145  *
146  * \return The name of the application.
147  */
148 const char *stasis_app_name(const struct stasis_app *app);
149
150 /*!
151  * \brief Return the JSON representation of a Stasis application.
152  *
153  * \param app_name Name of the application.
154  *
155  * \return JSON representation of app with given name.
156  * \return \c NULL on error.
157  */
158 struct ast_json *stasis_app_to_json(const char *app_name);
159
160 /*!
161  * \brief Event source information and callbacks.
162  */
163 struct stasis_app_event_source {
164         /*! \brief The scheme to match against on [un]subscribes */
165         const char *scheme;
166
167         /*!
168          * \brief Find an event source data object by the given id/name.
169          *
170          * \param app Application
171          * \param id A unique identifier to search on
172          *
173          * \return The data object associated with the id/name.
174          */
175         void *(*find)(const struct stasis_app *app, const char *id);
176
177         /*!
178          * \brief Subscribe an application to an event source.
179          *
180          * \param app Application
181          * \param obj an event source data object
182          *
183          * \return 0 on success, failure code otherwise
184          */
185         int (*subscribe)(struct stasis_app *app, void *obj);
186
187         /*!
188          * \brief Cancel the subscription an app has to an event source.
189          *
190          * \param app Application
191          * \param id a previously subscribed object id
192          *
193          * \return 0 on success, failure code otherwise
194          */
195         int (*unsubscribe)(struct stasis_app *app, const char *id);
196
197         /*!
198          * \brief Find an event source by the given id/name.
199          *
200          * \param app Application
201          * \param id A unique identifier to check
202          *
203          * \return true if id is subscribed, false otherwise.
204          */
205         int (*is_subscribed)(struct stasis_app *app, const char *id);
206
207         /*!
208          * \brief Convert event source data to json
209          *
210          * \param app Application
211          * \param id json object to fill
212          */
213         void (*to_json)(const struct stasis_app *app, struct ast_json *json);
214
215         /*! Next item in the list */
216         AST_LIST_ENTRY(stasis_app_event_source) next;
217 };
218
219 /*!
220  * \brief Register an application event source.
221  *
222  * \param obj the event source to register
223  */
224 void stasis_app_register_event_source(struct stasis_app_event_source *obj);
225
226 /*!
227  * \brief Register core event sources.
228  */
229 void stasis_app_register_event_sources(void);
230
231 /*!
232  * \brief Unregister an application event source.
233  *
234  * \param obj the event source to unregister
235  */
236 void stasis_app_unregister_event_source(struct stasis_app_event_source *obj);
237
238 /*!
239  * \brief Unregister core event sources.
240  */
241 void stasis_app_unregister_event_sources(void);
242
243 /*! \brief Return code for stasis_app_user_event */
244 enum stasis_app_user_event_res {
245         STASIS_APP_USER_OK,
246         STASIS_APP_USER_APP_NOT_FOUND,
247         STASIS_APP_USER_EVENT_SOURCE_NOT_FOUND,
248         STASIS_APP_USER_EVENT_SOURCE_BAD_SCHEME,
249         STASIS_APP_USER_USEREVENT_INVALID,
250         STASIS_APP_USER_INTERNAL_ERROR,
251 };
252
253 /*!
254  * \brief Generate a Userevent for stasis app (echo to AMI)
255  *
256  * \param app_name Name of the application to generate event for/to.
257  * \param event_name Name of the Userevent.
258  * \param source_uris URIs for the source objects to attach to event.
259  * \param sources_count Array size of source_uris.
260  * \param json_variables event blob variables.
261  *
262  * \return \ref stasis_app_user_event_res return code.
263  */
264 enum stasis_app_user_event_res stasis_app_user_event(const char *app_name,
265         const char *event_name,
266         const char **source_uris, int sources_count,
267         struct ast_json *json_variables);
268
269
270 /*! \brief Return code for stasis_app_[un]subscribe */
271 enum stasis_app_subscribe_res {
272         STASIS_ASR_OK,
273         STASIS_ASR_APP_NOT_FOUND,
274         STASIS_ASR_EVENT_SOURCE_NOT_FOUND,
275         STASIS_ASR_EVENT_SOURCE_BAD_SCHEME,
276         STASIS_ASR_INTERNAL_ERROR,
277 };
278
279 /*!
280  * \brief Subscribes an application to a list of event sources.
281  *
282  * \param app_name Name of the application to subscribe.
283  * \param event_source_uris URIs for the event sources to subscribe to.
284  * \param event_sources_count Array size of event_source_uris.
285  * \param json Optional output pointer for JSON representation of the app
286  *             after adding the subscription.
287  *
288  * \return \ref stasis_app_subscribe_res return code.
289  *
290  * \note Do not hold any channel locks if subscribing to a channel.
291  */
292 enum stasis_app_subscribe_res stasis_app_subscribe(const char *app_name,
293         const char **event_source_uris, int event_sources_count,
294         struct ast_json **json);
295
296 /*!
297  * \brief Unsubscribes an application from a list of event sources.
298  *
299  * \param app_name Name of the application to subscribe.
300  * \param event_source_uris URIs for the event sources to subscribe to.
301  * \param event_sources_count Array size of event_source_uris.
302  * \param json Optional output pointer for JSON representation of the app
303  *             after adding the subscription.
304  *
305  * \return \ref stasis_app_subscribe_res return code.
306  */
307 enum stasis_app_subscribe_res stasis_app_unsubscribe(const char *app_name,
308         const char **event_source_uris, int event_sources_count,
309         struct ast_json **json);
310
311 /*!
312  * \brief Directly subscribe an application to a channel
313  *
314  * \param app_name Name of the application to subscribe.
315  * \param chan The channel to subscribe to
316  *
317  * \return \ref stasis_app_subscribe_res return code.
318  *
319  * \note This method can be used when you already hold a channel and its
320  *       lock. This bypasses the channel lookup that would normally be
321  *       performed by \ref stasis_app_subscribe.
322  */
323 enum stasis_app_subscribe_res stasis_app_subscribe_channel(const char *app_name,
324         struct ast_channel *chan);
325
326 /*! @} */
327
328 /*! @{ */
329
330 /*! \brief Handler for controlling a channel that's in a Stasis application */
331 struct stasis_app_control;
332
333 /*! \brief Rule to check to see if an operation is allowed */
334 struct stasis_app_control_rule {
335         /*!
336          * \brief Checks to see if an operation is allowed on the control
337          *
338          * \param control Control object to check
339          * \return 0 on success, otherwise a failure code
340          */
341         enum stasis_app_control_channel_result (*check_rule)(
342                 const struct stasis_app_control *control);
343         /*! Next item in the list */
344         AST_LIST_ENTRY(stasis_app_control_rule) next;
345 };
346
347 /*!
348  * \brief Registers an add channel to bridge rule.
349  *
350  * \param control Control object
351  * \param rule The rule to register
352  */
353 void stasis_app_control_register_add_rule(
354         struct stasis_app_control *control,
355         struct stasis_app_control_rule *rule);
356
357 /*!
358  * \brief UnRegister an add channel to bridge rule.
359  *
360  * \param control Control object
361  * \param rule The rule to unregister
362  */
363 void stasis_app_control_unregister_add_rule(
364         struct stasis_app_control *control,
365         struct stasis_app_control_rule *rule);
366
367 /*!
368  * \brief Registers a remove channel from bridge rule.
369  *
370  * \param control Control object
371  * \param rule The rule to register
372  */
373 void stasis_app_control_register_remove_rule(
374         struct stasis_app_control *control,
375         struct stasis_app_control_rule *rule);
376
377 /*!
378  * \brief Unregisters a remove channel from bridge rule.
379  *
380  * \param control Control object
381  * \param rule The rule to unregister
382  */
383 void stasis_app_control_unregister_remove_rule(
384         struct stasis_app_control *control,
385         struct stasis_app_control_rule *rule);
386
387 /*!
388  * \brief Returns the handler for the given channel.
389  * \param chan Channel to handle.
390  *
391  * \return NULL channel not in Stasis application.
392  * \return Pointer to \c res_stasis handler.
393  */
394 struct stasis_app_control *stasis_app_control_find_by_channel(
395         const struct ast_channel *chan);
396
397 /*!
398  * \brief Returns the handler for the channel with the given id.
399  * \param channel_id Uniqueid of the channel.
400  *
401  * \return NULL channel not in Stasis application, or channel does not exist.
402  * \return Pointer to \c res_stasis handler.
403  */
404 struct stasis_app_control *stasis_app_control_find_by_channel_id(
405         const char *channel_id);
406
407 /*!
408  * \brief Creates a control handler for a channel that isn't in a stasis app.
409  * \since 12.0.0
410  *
411  * \param chan Channel to create controller handle for
412  *
413  * \return NULL on failure to create the handle
414  * \return Pointer to \c res_stasis handler.
415  */
416 struct stasis_app_control *stasis_app_control_create(
417         struct ast_channel *chan);
418
419 /*!
420  * \brief Act on a stasis app control queue until it is empty
421  * \since 12.0.0
422  *
423  * \param chan Channel to handle
424  * \param control Control object to execute
425  */
426 void stasis_app_control_execute_until_exhausted(
427         struct ast_channel *chan,
428         struct stasis_app_control *control);
429
430 /*!
431  * \brief Check if a control is marked as done
432  * \since 12.2.0
433  *
434  * \param control Which control object is being evaluated
435  */
436 int stasis_app_control_is_done(
437         struct stasis_app_control *control);
438
439 /*!
440  * \brief Flush the control command queue.
441  * \since 13.9.0
442  *
443  * \param control Control object to flush command queue.
444  *
445  * \return Nothing
446  */
447 void stasis_app_control_flush_queue(struct stasis_app_control *control);
448
449 /*!
450  * \brief Returns the uniqueid of the channel associated with this control
451  *
452  * \param control Control object.
453  *
454  * \return Uniqueid of the associate channel.
455  * \return \c NULL if \a control is \c NULL.
456  */
457 const char *stasis_app_control_get_channel_id(
458         const struct stasis_app_control *control);
459
460 /*!
461  * \brief Apply a bridge role to a channel controlled by a stasis app control
462  *
463  * \param control Control for \c res_stasis
464  * \param role Role to apply
465  *
466  * \return 0 for success
467  * \return -1 for error.
468  */
469 int stasis_app_control_add_role(struct stasis_app_control *control, const char *role);
470
471 /*!
472  * \brief Clear bridge roles currently applied to a channel controlled by a stasis app control
473  *
474  * \param control Control for \c res_stasis
475  */
476 void stasis_app_control_clear_roles(struct stasis_app_control *control);
477
478 /*!
479  * \brief Exit \c res_stasis and continue execution in the dialplan.
480  *
481  * If the channel is no longer in \c res_stasis, this function does nothing.
482  *
483  * \param control Control for \c res_stasis
484  * \param context An optional context to continue to
485  * \param extension An optional extension to continue to
486  * \param priority An optional priority to continue to
487  *
488  * \return 0 for success
489  * \return -1 for error.
490  */
491 int stasis_app_control_continue(struct stasis_app_control *control, const char *context, const char *extension, int priority);
492
493 /*!
494  * \brief Redirect a channel in \c res_stasis to a particular endpoint
495  *
496  * \param control Control for \c res_stasis
497  * \param endpoint The endpoint transfer string where the channel should be sent to
498  *
499  * \return 0 for success
500  * \return -1 for error
501  */
502 int stasis_app_control_redirect(struct stasis_app_control *control, const char *endpoint);
503
504 /*!
505  * \brief Indicate ringing to the channel associated with this control.
506  *
507  * \param control Control for \c res_stasis.
508  *
509  * \return 0 for success.
510  * \return -1 for error.
511  */
512 int stasis_app_control_ring(struct stasis_app_control *control);
513
514 /*!
515  * \brief Stop locally generated ringing on the channel associated with this control.
516  *
517  * \param control Control for \c res_stasis.
518  *
519  * \return 0 for success.
520  * \return -1 for error.
521  */
522 int stasis_app_control_ring_stop(struct stasis_app_control *control);
523
524 /*!
525  * \brief Send DTMF to the channel associated with this control.
526  *
527  * \param control Control for \c res_stasis.
528  * \param dtmf DTMF string.
529  * \param before Amount of time to wait before sending DTMF digits.
530  * \param between Amount of time between each DTMF digit.
531  * \param duration Amount of time each DTMF digit lasts for.
532  * \param after Amount of time to wait after sending DTMF digits.
533  *
534  * \return 0 for success.
535  * \return -1 for error.
536  */
537 int stasis_app_control_dtmf(struct stasis_app_control *control, const char *dtmf, int before, int between, unsigned int duration, int after);
538
539 /*!
540  * \brief Mute the channel associated with this control.
541  *
542  * \param control Control for \c res_stasis.
543  * \param direction The direction in which the audio should be muted.
544  * \param frametype The type of stream that should be muted.
545  *
546  * \return 0 for success
547  * \return -1 for error.
548  */
549 int stasis_app_control_mute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
550
551 /*!
552  * \brief Unmute the channel associated with this control.
553  *
554  * \param control Control for \c res_stasis.
555  * \param direction The direction in which the audio should be unmuted.
556  * \param frametype The type of stream that should be unmuted.
557  *
558  * \return 0 for success
559  * \return -1 for error.
560  */
561 int stasis_app_control_unmute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
562
563 /*!
564  * \brief Answer the channel associated with this control.
565  * \param control Control for \c res_stasis.
566  * \return 0 for success.
567  * \return Non-zero for error.
568  */
569 int stasis_app_control_answer(struct stasis_app_control *control);
570
571 /*!
572  * \brief Set a variable on the channel associated with this control to value.
573  * \param control Control for \c res_stasis.
574  * \param variable The name of the variable
575  * \param value The value to set the variable to
576  *
577  * \return 0 for success.
578  * \return -1 for error.
579  */
580 int stasis_app_control_set_channel_var(struct stasis_app_control *control, const char *variable, const char *value);
581
582 /*!
583  * \brief Place the channel associated with the control on hold.
584  * \param control Control for \c res_stasis.
585  */
586 void stasis_app_control_hold(struct stasis_app_control *control);
587
588 /*!
589  * \brief Remove the channel associated with the control from hold.
590  * \param control Control for \c res_stasis.
591  */
592 void stasis_app_control_unhold(struct stasis_app_control *control);
593
594 /*!
595  * \brief Play music on hold to a channel (does not affect hold status)
596  * \param control Control for \c res_stasis.
597  * \param moh_class class of music on hold to play (NULL allowed)
598  */
599 void stasis_app_control_moh_start(struct stasis_app_control *control, const char *moh_class);
600
601 /*!
602  * \brief Stop playing music on hold to a channel (does not affect hold status)
603  * \param control Control for \c res_stasis.
604  */
605 void stasis_app_control_moh_stop(struct stasis_app_control *control);
606
607 /*!
608  * \brief Start playing silence to a channel.
609  * \param control Control for \c res_stasis.
610  */
611 void stasis_app_control_silence_start(struct stasis_app_control *control);
612
613 /*!
614  * \brief Stop playing silence to a channel.
615  * \param control Control for \c res_stasis.
616  */
617 void stasis_app_control_silence_stop(struct stasis_app_control *control);
618
619 /*!
620  * \brief Returns the most recent snapshot for the associated channel.
621  *
622  * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
623  *
624  * \param control Control for \c res_stasis.
625  *
626  * \return Most recent snapshot. ao2_cleanup() when done.
627  * \return \c NULL if channel isn't in cache.
628  */
629 struct ast_channel_snapshot *stasis_app_control_get_snapshot(
630         const struct stasis_app_control *control);
631
632 /*!
633  * \brief Publish a message to the \a control's channel's topic.
634  *
635  * \param control Control to publish to
636  * \param message Message to publish
637  */
638 void stasis_app_control_publish(
639         struct stasis_app_control *control, struct stasis_message *message);
640
641 /*!
642  * \brief Returns the stasis topic for an app
643  *
644  * \param app Stasis app to get topic of
645  */
646 struct stasis_topic *ast_app_get_topic(struct stasis_app *app);
647
648 /*!
649  * \brief Queue a control frame without payload.
650  *
651  * \param control Control to publish to.
652  * \param frame_type type of control frame.
653  *
654  * \return zero on success
655  * \return non-zero on failure
656  */
657 int stasis_app_control_queue_control(struct stasis_app_control *control,
658         enum ast_control_frame_type frame_type);
659
660 /*!
661  * \brief Create a bridge of the specified type.
662  *
663  * \param type The type of bridge to be created
664  * \param name Optional name to give to the bridge
665  * \param id Optional Unique ID to give to the bridge
666  *
667  * \return New bridge.
668  * \return \c NULL on error.
669  */
670 struct ast_bridge *stasis_app_bridge_create(const char *type, const char *name, const char *id);
671
672 /*!
673  * \brief Create an invisible bridge of the specified type.
674  *
675  * \param type The type of bridge to be created
676  * \param name Optional name to give to the bridge
677  * \param id Optional Unique ID to give to the bridge
678  *
679  * \return New bridge.
680  * \return \c NULL on error.
681  */
682 struct ast_bridge *stasis_app_bridge_create_invisible(const char *type, const char *name, const char *id);
683
684 /*!
685  * \brief Returns the bridge with the given id.
686  * \param bridge_id Uniqueid of the bridge.
687  *
688  * \return NULL bridge not created by a Stasis application, or bridge does not exist.
689  * \return Pointer to bridge.
690  */
691 struct ast_bridge *stasis_app_bridge_find_by_id(
692         const char *bridge_id);
693
694 /*!
695  * \brief Finds or creates an announcer channel in a bridge that can play music on hold.
696  *
697  * \param bridge Bridge we want an MOH channel for
698  *
699  * \return NULL if the music on hold channel fails to be created or join the bridge for any reason.
700  * \return Pointer to the ;1 end of the announcer channel chain.
701  */
702 struct ast_channel *stasis_app_bridge_moh_channel(
703         struct ast_bridge *bridge);
704
705 /*!
706  * \brief Breaks down MOH channels playing on the bridge created by stasis_app_bridge_moh_channel
707  *
708  * \param bridge Bridge we want to stop the MOH on
709  *
710  * \return -1 if no moh channel could be found and stopped
711  * \return 0 on success
712  */
713 int stasis_app_bridge_moh_stop(
714         struct ast_bridge *bridge);
715
716 /*!
717  * \brief Finds an existing ARI playback channel in a bridge
718  *
719  * \param bridge Bridge we want to find the playback channel for
720  *
721  * \return NULL if the playback channel can not be found for any reason.
722  * \return Pointer to the ;1 end of the playback channel chain.
723  */
724 struct ast_channel *stasis_app_bridge_playback_channel_find(
725         struct ast_bridge *bridge);
726
727 /*!
728  * \brief Adds a channel to the list of ARI playback channels for bridges.
729  *
730  * \param bridge Bridge we are adding the playback channel for
731  * \param chan Channel being added as a playback channel (must be ;1)
732  *
733  * \retval -1 failed to add channel for any reason
734  * \retval 0 on success
735  */
736 int stasis_app_bridge_playback_channel_add(struct ast_bridge *bridge,
737         struct ast_channel *chan,
738         struct stasis_app_control *control);
739
740 /*!
741  * \brief remove channel from list of ARI playback channels for bridges.
742  *
743  * \param bridge_id The unique ID of the bridge the playback channel is in.
744  * \param control The app control structure for the playback channel
745  */
746 void stasis_app_bridge_playback_channel_remove(char *bridge_id,
747         struct stasis_app_control *control);
748
749 /*!
750  * \brief Result codes used when adding/removing channels to/from bridges.
751  */
752 enum stasis_app_control_channel_result {
753         /*! The channel is okay to be added/removed */
754         STASIS_APP_CHANNEL_OKAY = 0,
755         /*! The channel is currently recording */
756         STASIS_APP_CHANNEL_RECORDING
757 };
758
759 /*!
760  * \brief Add a channel to the bridge.
761  *
762  * \param control Control whose channel should be added to the bridge
763  * \param bridge Pointer to the bridge
764  *
765  * \return non-zero on failure
766  * \return zero on success
767  */
768 int stasis_app_control_add_channel_to_bridge(
769         struct stasis_app_control *control, struct ast_bridge *bridge);
770
771 /*!
772  * \brief Remove a channel from the bridge.
773  *
774  * \param control Control whose channel should be removed from the bridge
775  * \param bridge Pointer to the bridge
776  *
777  * \return non-zero on failure
778  * \return zero on success
779  */
780 int stasis_app_control_remove_channel_from_bridge(
781         struct stasis_app_control *control, struct ast_bridge *bridge);
782
783 /*!
784  * \brief Initialize bridge features into a channel control
785  *
786  * \note Bridge features on a control are destroyed after each bridge session,
787  *       so new features need to be initialized before each bridge add.
788  *
789  * \param control Control in which to store the features
790  *
791  * \return non-zero on failure
792  * \return zero on success
793  */
794 int stasis_app_control_bridge_features_init(
795         struct stasis_app_control *control);
796
797 /*!
798  * \brief Set whether DTMF from the channel is absorbed instead of passing through to the bridge
799  *
800  * \param control Control whose channel should have its DTMF absorbed when bridged
801  * \param absorb Whether DTMF should be absorbed (1) instead of passed through (0).
802  */
803 void stasis_app_control_absorb_dtmf_in_bridge(
804         struct stasis_app_control *control, int absorb);
805
806 /*!
807  * \brief Set whether audio from the channel is muted instead of passing through to the bridge
808  *
809  * \param control Control whose channel should have its audio muted when bridged
810  * \param mute Whether audio should be muted (1) instead of passed through (0).
811  */
812 void stasis_app_control_mute_in_bridge(
813         struct stasis_app_control *control, int mute);
814
815 /*!
816  * \since 12
817  * \brief Gets the bridge currently associated with a control object.
818  *
819  * \note If the bridge returned by this function is to be held for any
820  *       length of time, its refcount should be incremented until the
821  *       caller is finished with it.
822  *
823  * \param control Control object for the channel to query.
824  *
825  * \return Associated \ref ast_bridge.
826  * \return \c NULL if not associated with a bridge.
827  */
828 struct ast_bridge *stasis_app_get_bridge(struct stasis_app_control *control);
829
830 /*!
831  * \brief Destroy the bridge.
832  *
833  * \param bridge_id Uniqueid of bridge to be destroyed
834  *
835  * \retval non-zero on failure
836  * \retval zero on success
837  */
838 void stasis_app_bridge_destroy(const char *bridge_id);
839
840 /*!
841  * \brief Get the Stasis message sanitizer for app_stasis applications
842  *
843  * \retval The stasis message sanitizer
844  */
845 struct stasis_message_sanitizer *stasis_app_get_sanitizer(void);
846
847 /*!
848  * \brief Indicate that this channel has had a StasisEnd published for it
849  *
850  * \param The channel that is exiting Stasis.
851  */
852 void stasis_app_channel_set_stasis_end_published(struct ast_channel *chan);
853
854 /*!
855  * \brief Has this channel had a StasisEnd published on it?
856  *
857  * \param chan The channel upon which the query rests.
858  *
859  * \retval 0 No
860  * \retval 1 Yes
861  */
862 int stasis_app_channel_is_stasis_end_published(struct ast_channel *chan);
863
864 /*!
865  * \brief Is this channel internal to Stasis?
866  *
867  * \param chan The channel to check.
868  *
869  * \retval 0 No
870  * \retval 1 Yes
871  */
872 int stasis_app_channel_is_internal(struct ast_channel *chan);
873
874 /*!
875  * \brief Mark this unreal channel and it's other half as being internal to Stasis.
876  *
877  * \param chan The channel to mark.
878  *
879  * \retval zero Success
880  * \retval non-zero Failure
881  */
882 int stasis_app_channel_unreal_set_internal(struct ast_channel *chan);
883
884 /*!
885  * \brief Mark this channel as being internal to Stasis.
886  *
887  * \param chan The channel to mark.
888  *
889  * \retval zero Success
890  * \retval non-zero Failure
891  */
892 int stasis_app_channel_set_internal(struct ast_channel *chan);
893
894 /*!
895  * \brief Dial a channel
896  * \param control Control for \c res_stasis.
897  * \param dialstring The dialstring to pass to the channel driver
898  * \param timeout Optional timeout in milliseconds
899  */
900 int stasis_app_control_dial(struct stasis_app_control *control,
901                 const char *dialstring, unsigned int timeout);
902
903 /*!
904  * \brief Let Stasis app internals shut down
905  *
906  * This is called when res_stasis is unloaded. It ensures that
907  * the Stasis app internals can free any resources they may have
908  * allocated during the time that res_stasis was loaded.
909  */
910 void stasis_app_control_shutdown(void);
911
912 /*!
913  * \brief Enable/disable request/response and event logging on an application
914  *
915  * \param app The app to debug
916  * \param debug If non-zero, enable debugging. If zero, disable.
917  */
918 void stasis_app_set_debug(struct stasis_app *app, int debug);
919
920 /*!
921  * \brief Enable/disable request/response and event logging on an application
922  *
923  * \param app_name The app name to debug
924  * \param debug If non-zero, enable debugging. If zero, disable.
925  */
926 void stasis_app_set_debug_by_name(const char *app_name, int debug);
927
928 /*!
929  * \brief Get debug status of an application
930  *
931  * \param app The app to check
932  * \return The debug flag for the app || the global debug flag
933  */
934 int stasis_app_get_debug(struct stasis_app *app);
935
936 /*!
937  * \brief Get debug status of an application
938  *
939  * \param app_name The app_name to check
940  * \return The debug flag for the app || the global debug flag
941  */
942 int stasis_app_get_debug_by_name(const char *app_name);
943
944 /*!
945  * \brief Enable/disable request/response and event logging on all applications
946  *
947  * \param debug If non-zero, enable debugging. If zero, disable.
948  */
949 void stasis_app_set_global_debug(int debug);
950
951 struct ast_cli_args;
952
953 /*!
954  * \brief Dump properties of a \c stasis_app to the CLI
955  *
956  * \param app The application
957  * \param a The CLI arguments
958  */
959 void stasis_app_to_cli(const struct stasis_app *app, struct ast_cli_args *a);
960
961 /*! @} */
962
963 #endif /* _ASTERISK_STASIS_APP_H */