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