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