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