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