3497bf437af5348daa2bd85664036ab4a45eeb01
[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 Flush the control command queue.
444  * \since 13.9.0
445  *
446  * \param control Control object to flush command queue.
447  *
448  * \return Nothing
449  */
450 void stasis_app_control_flush_queue(struct stasis_app_control *control);
451
452 /*!
453  * \brief Returns the uniqueid of the channel associated with this control
454  *
455  * \param control Control object.
456  *
457  * \return Uniqueid of the associate channel.
458  * \return \c NULL if \a control is \c NULL.
459  */
460 const char *stasis_app_control_get_channel_id(
461         const struct stasis_app_control *control);
462
463 /*!
464  * \brief Apply a bridge role to a channel controlled by a stasis app control
465  *
466  * \param control Control for \c res_stasis
467  * \param role Role to apply
468  *
469  * \return 0 for success
470  * \return -1 for error.
471  */
472 int stasis_app_control_add_role(struct stasis_app_control *control, const char *role);
473
474 /*!
475  * \brief Clear bridge roles currently applied to a channel controlled by a stasis app control
476  *
477  * \param control Control for \c res_stasis
478  */
479 void stasis_app_control_clear_roles(struct stasis_app_control *control);
480
481 /*!
482  * \brief Exit \c res_stasis and continue execution in the dialplan.
483  *
484  * If the channel is no longer in \c res_stasis, this function does nothing.
485  *
486  * \param control Control for \c res_stasis
487  * \param context An optional context to continue to
488  * \param extension An optional extension to continue to
489  * \param priority An optional priority to continue to
490  *
491  * \return 0 for success
492  * \return -1 for error.
493  */
494 int stasis_app_control_continue(struct stasis_app_control *control, const char *context, const char *extension, int priority);
495
496 /*!
497  * \brief Redirect a channel in \c res_stasis to a particular endpoint
498  *
499  * \param control Control for \c res_stasis
500  * \param endpoint The endpoint transfer string where the channel should be sent to
501  *
502  * \return 0 for success
503  * \return -1 for error
504  */
505 int stasis_app_control_redirect(struct stasis_app_control *control, const char *endpoint);
506
507 /*!
508  * \brief Indicate ringing to the channel associated with this control.
509  *
510  * \param control Control for \c res_stasis.
511  *
512  * \return 0 for success.
513  * \return -1 for error.
514  */
515 int stasis_app_control_ring(struct stasis_app_control *control);
516
517 /*!
518  * \brief Stop locally generated ringing on the channel associated with this control.
519  *
520  * \param control Control for \c res_stasis.
521  *
522  * \return 0 for success.
523  * \return -1 for error.
524  */
525 int stasis_app_control_ring_stop(struct stasis_app_control *control);
526
527 /*!
528  * \brief Send DTMF to the channel associated with this control.
529  *
530  * \param control Control for \c res_stasis.
531  * \param dtmf DTMF string.
532  * \param before Amount of time to wait before sending DTMF digits.
533  * \param between Amount of time between each DTMF digit.
534  * \param duration Amount of time each DTMF digit lasts for.
535  * \param after Amount of time to wait after sending DTMF digits.
536  *
537  * \return 0 for success.
538  * \return -1 for error.
539  */
540 int stasis_app_control_dtmf(struct stasis_app_control *control, const char *dtmf, int before, int between, unsigned int duration, int after);
541
542 /*!
543  * \brief Mute the channel associated with this control.
544  *
545  * \param control Control for \c res_stasis.
546  * \param direction The direction in which the audio should be muted.
547  * \param frametype The type of stream that should be muted.
548  *
549  * \return 0 for success
550  * \return -1 for error.
551  */
552 int stasis_app_control_mute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
553
554 /*!
555  * \brief Unmute the channel associated with this control.
556  *
557  * \param control Control for \c res_stasis.
558  * \param direction The direction in which the audio should be unmuted.
559  * \param frametype The type of stream that should be unmuted.
560  *
561  * \return 0 for success
562  * \return -1 for error.
563  */
564 int stasis_app_control_unmute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
565
566 /*!
567  * \brief Answer the channel associated with this control.
568  * \param control Control for \c res_stasis.
569  * \return 0 for success.
570  * \return Non-zero for error.
571  */
572 int stasis_app_control_answer(struct stasis_app_control *control);
573
574 /*!
575  * \brief Set a variable on the channel associated with this control to value.
576  * \param control Control for \c res_stasis.
577  * \param variable The name of the variable
578  * \param value The value to set the variable to
579  *
580  * \return 0 for success.
581  * \return -1 for error.
582  */
583 int stasis_app_control_set_channel_var(struct stasis_app_control *control, const char *variable, const char *value);
584
585 /*!
586  * \brief Place the channel associated with the control on hold.
587  * \param control Control for \c res_stasis.
588  */
589 void stasis_app_control_hold(struct stasis_app_control *control);
590
591 /*!
592  * \brief Remove the channel associated with the control from hold.
593  * \param control Control for \c res_stasis.
594  */
595 void stasis_app_control_unhold(struct stasis_app_control *control);
596
597 /*!
598  * \brief Play music on hold to a channel (does not affect hold status)
599  * \param control Control for \c res_stasis.
600  * \param moh_class class of music on hold to play (NULL allowed)
601  */
602 void stasis_app_control_moh_start(struct stasis_app_control *control, const char *moh_class);
603
604 /*!
605  * \brief Stop playing music on hold to a channel (does not affect hold status)
606  * \param control Control for \c res_stasis.
607  */
608 void stasis_app_control_moh_stop(struct stasis_app_control *control);
609
610 /*!
611  * \brief Start playing silence to a channel.
612  * \param control Control for \c res_stasis.
613  */
614 void stasis_app_control_silence_start(struct stasis_app_control *control);
615
616 /*!
617  * \brief Stop playing silence to a channel.
618  * \param control Control for \c res_stasis.
619  */
620 void stasis_app_control_silence_stop(struct stasis_app_control *control);
621
622 /*!
623  * \brief Returns the most recent snapshot for the associated channel.
624  *
625  * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
626  *
627  * \param control Control for \c res_stasis.
628  *
629  * \return Most recent snapshot. ao2_cleanup() when done.
630  * \return \c NULL if channel isn't in cache.
631  */
632 struct ast_channel_snapshot *stasis_app_control_get_snapshot(
633         const struct stasis_app_control *control);
634
635 /*!
636  * \brief Publish a message to the \a control's channel's topic.
637  *
638  * \param control Control to publish to
639  * \param message Message to publish
640  */
641 void stasis_app_control_publish(
642         struct stasis_app_control *control, struct stasis_message *message);
643
644 /*!
645  * \brief Returns the stasis topic for an app
646  *
647  * \param app Stasis app to get topic of
648  */
649 struct stasis_topic *ast_app_get_topic(struct stasis_app *app);
650
651 /*!
652  * \brief Queue a control frame without payload.
653  *
654  * \param control Control to publish to.
655  * \param frame_type type of control frame.
656  *
657  * \return zero on success
658  * \return non-zero on failure
659  */
660 int stasis_app_control_queue_control(struct stasis_app_control *control,
661         enum ast_control_frame_type frame_type);
662
663 /*!
664  * \brief Create a bridge of the specified type.
665  *
666  * \param type The type of bridge to be created
667  * \param name Optional name to give to the bridge
668  * \param id Optional Unique ID to give to the bridge
669  *
670  * \return New bridge.
671  * \return \c NULL on error.
672  */
673 struct ast_bridge *stasis_app_bridge_create(const char *type, const char *name, const char *id);
674
675 /*!
676  * \brief Create an invisible bridge of the specified type.
677  *
678  * \param type The type of bridge to be created
679  * \param name Optional name to give to the bridge
680  * \param id Optional Unique ID to give to the bridge
681  *
682  * \return New bridge.
683  * \return \c NULL on error.
684  */
685 struct ast_bridge *stasis_app_bridge_create_invisible(const char *type, const char *name, const char *id);
686
687 /*!
688  * \brief Returns the bridge with the given id.
689  * \param bridge_id Uniqueid of the bridge.
690  *
691  * \return NULL bridge not created by a Stasis application, or bridge does not exist.
692  * \return Pointer to bridge.
693  */
694 struct ast_bridge *stasis_app_bridge_find_by_id(
695         const char *bridge_id);
696
697 /*!
698  * \brief Finds or creates an announcer channel in a bridge that can play music on hold.
699  *
700  * \param bridge Bridge we want an MOH channel for
701  *
702  * \return NULL if the music on hold channel fails to be created or join the bridge for any reason.
703  * \return Pointer to the ;1 end of the announcer channel chain.
704  */
705 struct ast_channel *stasis_app_bridge_moh_channel(
706         struct ast_bridge *bridge);
707
708 /*!
709  * \brief Breaks down MOH channels playing on the bridge created by stasis_app_bridge_moh_channel
710  *
711  * \param bridge Bridge we want to stop the MOH on
712  *
713  * \return -1 if no moh channel could be found and stopped
714  * \return 0 on success
715  */
716 int stasis_app_bridge_moh_stop(
717         struct ast_bridge *bridge);
718
719 /*!
720  * \brief Finds an existing ARI playback channel in a bridge
721  *
722  * \param bridge Bridge we want to find the playback channel for
723  *
724  * \return NULL if the playback channel can not be found for any reason.
725  * \return Pointer to the ;1 end of the playback channel chain.
726  */
727 struct ast_channel *stasis_app_bridge_playback_channel_find(
728         struct ast_bridge *bridge);
729
730 /*!
731  * \brief Adds a channel to the list of ARI playback channels for bridges.
732  *
733  * \param bridge Bridge we are adding the playback channel for
734  * \param chan Channel being added as a playback channel (must be ;1)
735  *
736  * \retval -1 failed to add channel for any reason
737  * \retval 0 on success
738  */
739 int stasis_app_bridge_playback_channel_add(struct ast_bridge *bridge,
740         struct ast_channel *chan,
741         struct stasis_app_control *control);
742
743 /*!
744  * \brief remove channel from list of ARI playback channels for bridges.
745  *
746  * \param bridge_id The unique ID of the bridge the playback channel is in.
747  * \param control The app control structure for the playback channel
748  */
749 void stasis_app_bridge_playback_channel_remove(char *bridge_id,
750         struct stasis_app_control *control);
751
752 /*!
753  * \brief Result codes used when adding/removing channels to/from bridges.
754  */
755 enum stasis_app_control_channel_result {
756         /*! The channel is okay to be added/removed */
757         STASIS_APP_CHANNEL_OKAY = 0,
758         /*! The channel is currently recording */
759         STASIS_APP_CHANNEL_RECORDING
760 };
761
762 /*!
763  * \brief Add a channel to the bridge.
764  *
765  * \param control Control whose channel should be added to the bridge
766  * \param bridge Pointer to the bridge
767  *
768  * \return non-zero on failure
769  * \return zero on success
770  */
771 int stasis_app_control_add_channel_to_bridge(
772         struct stasis_app_control *control, struct ast_bridge *bridge);
773
774 /*!
775  * \brief Remove a channel from the bridge.
776  *
777  * \param control Control whose channel should be removed from the bridge
778  * \param bridge Pointer to the bridge
779  *
780  * \return non-zero on failure
781  * \return zero on success
782  */
783 int stasis_app_control_remove_channel_from_bridge(
784         struct stasis_app_control *control, struct ast_bridge *bridge);
785
786 /*!
787  * \since 12
788  * \brief Gets the bridge currently associated with a control object.
789  *
790  * \note If the bridge returned by this function is to be held for any
791  *       length of time, its refcount should be incremented until the
792  *       caller is finished with it.
793  *
794  * \param control Control object for the channel to query.
795  *
796  * \return Associated \ref ast_bridge.
797  * \return \c NULL if not associated with a bridge.
798  */
799 struct ast_bridge *stasis_app_get_bridge(struct stasis_app_control *control);
800
801 /*!
802  * \brief Destroy the bridge.
803  *
804  * \param bridge_id Uniqueid of bridge to be destroyed
805  *
806  * \retval non-zero on failure
807  * \retval zero on success
808  */
809 void stasis_app_bridge_destroy(const char *bridge_id);
810
811 /*!
812  * \brief Increment the res_stasis reference count.
813  *
814  * This ensures graceful shutdown happens in the proper order.
815  */
816 void stasis_app_ref(void);
817
818 /*!
819  * \brief Decrement the res_stasis reference count.
820  *
821  * This ensures graceful shutdown happens in the proper order.
822  */
823 void stasis_app_unref(void);
824
825 /*!
826  * \brief Get the Stasis message sanitizer for app_stasis applications
827  *
828  * \retval The stasis message sanitizer
829  */
830 struct stasis_message_sanitizer *stasis_app_get_sanitizer(void);
831
832 /*!
833  * \brief Indicate that this channel has had a StasisEnd published for it
834  *
835  * \param The channel that is exiting Stasis.
836  */
837 void stasis_app_channel_set_stasis_end_published(struct ast_channel *chan);
838
839 /*!
840  * \brief Has this channel had a StasisEnd published on it?
841  *
842  * \param chan The channel upon which the query rests.
843  *
844  * \retval 0 No
845  * \retval 1 Yes
846  */
847 int stasis_app_channel_is_stasis_end_published(struct ast_channel *chan);
848
849 /*!
850  * \brief Is this channel internal to Stasis?
851  *
852  * \param chan The channel to check.
853  *
854  * \retval 0 No
855  * \retval 1 Yes
856  */
857 int stasis_app_channel_is_internal(struct ast_channel *chan);
858
859 /*!
860  * \brief Mark this unreal channel and it's other half as being internal to Stasis.
861  *
862  * \param chan The channel to mark.
863  *
864  * \retval zero Success
865  * \retval non-zero Failure
866  */
867 int stasis_app_channel_unreal_set_internal(struct ast_channel *chan);
868
869 /*!
870  * \brief Mark this channel as being internal to Stasis.
871  *
872  * \param chan The channel to mark.
873  *
874  * \retval zero Success
875  * \retval non-zero Failure
876  */
877 int stasis_app_channel_set_internal(struct ast_channel *chan);
878
879 /*!
880  * \brief Dial a channel
881  * \param control Control for \c res_stasis.
882  * \param dialstring The dialstring to pass to the channel driver
883  * \param timeout Optional timeout in milliseconds
884  */
885 int stasis_app_control_dial(struct stasis_app_control *control,
886                 const char *dialstring, unsigned int timeout);
887
888 /*!
889  * \brief Let Stasis app internals shut down
890  *
891  * This is called when res_stasis is unloaded. It ensures that
892  * the Stasis app internals can free any resources they may have
893  * allocated during the time that res_stasis was loaded.
894  */
895 void stasis_app_control_shutdown(void);
896 /*! @} */
897
898 #endif /* _ASTERISK_STASIS_APP_H */