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