Asterisk - The Open Source Telephony Project GIT-master-0bf3178
stasis_app.h
Go to the documentation of this file.
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 */
67typedef 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 * \retval NULL on error.
75 */
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 * \retval NULL on error.
85 */
86struct 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 */
101int 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 */
117
118/*!
119 * \brief Unregister a Stasis application.
120 * \param app_name Name of the application to unregister.
121 */
122void 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 */
136int stasis_app_send(const char *app_name, struct ast_json *message);
137
138/*! \brief Forward declare app */
139struct 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 */
148const 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 * \retval NULL on error.
158 */
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 * \retval NULL on error.
168 */
169struct ast_json *stasis_app_to_json(const char *app_name);
170
171/*!
172 * \brief Event source information and callbacks.
173 */
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 */
228};
229
230/*!
231 * \brief Register an application event source.
232 *
233 * \param obj the event source to register
234 */
236
237/*!
238 * \brief Register core event sources.
239 */
241
242/*!
243 * \brief Unregister an application event source.
244 *
245 * \param obj the event source to unregister
246 */
248
249/*!
250 * \brief Unregister core event sources.
251 */
253
254/*! \brief Return code for stasis_app_user_event */
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 */
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 */
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 */
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 */
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 */
335 struct ast_channel *chan);
336
337/*! @} */
338
339/*! @{ */
340
341/*! \brief Handler for controlling a channel that's in a Stasis application */
342struct stasis_app_control;
343
344/*! \brief Rule to check to see if an operation is allowed */
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 */
353 const struct stasis_app_control *control);
354 /*! Next item in the list */
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 */
365 struct stasis_app_control *control,
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 */
375 struct stasis_app_control *control,
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 */
385 struct stasis_app_control *control,
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 */
395 struct stasis_app_control *control,
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 */
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 */
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 */
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 */
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 */
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 */
457
458/*!
459 * \brief Returns the uniqueid of the channel associated with this control
460 *
461 * \param control Control object.
462 *
463 * \return Uniqueid of the associate channel.
464 * \retval NULL if \a control is \c NULL.
465 */
467 const struct stasis_app_control *control);
468
469/*!
470 * \brief Apply a bridge role to a channel controlled by a stasis app control
471 *
472 * \param control Control for \c res_stasis
473 * \param role Role to apply
474 *
475 * \return 0 for success
476 * \return -1 for error.
477 */
478int stasis_app_control_add_role(struct stasis_app_control *control, const char *role);
479
480/*!
481 * \brief Clear bridge roles currently applied to a channel controlled by a stasis app control
482 *
483 * \param control Control for \c res_stasis
484 */
486
487/*!
488 * \brief Exit \c res_stasis and continue execution in the dialplan.
489 *
490 * If the channel is no longer in \c res_stasis, this function does nothing.
491 *
492 * \param control Control for \c res_stasis
493 * \param context An optional context to continue to
494 * \param extension An optional extension to continue to
495 * \param priority An optional priority to continue to
496 *
497 * \return 0 for success
498 * \return -1 for error.
499 */
500int stasis_app_control_continue(struct stasis_app_control *control, const char *context, const char *extension, int priority);
501
502/*!
503 * \brief Exit \c res_stasis and move to another Stasis application.
504 *
505 * If the channel is no longer in \c res_stasis, this function does nothing.
506 *
507 * \param control Control for \c res_stasis
508 * \param app_name The name of the application to switch to
509 * \param app_args The list of arguments to pass to the application
510 *
511 * \return 0 for success
512 * \return -1 for error
513 */
514int stasis_app_control_move(struct stasis_app_control *control, const char *app_name, const char *app_args);
515
516/*!
517 * \brief Redirect a channel in \c res_stasis to a particular endpoint
518 *
519 * \param control Control for \c res_stasis
520 * \param endpoint The endpoint transfer string where the channel should be sent to
521 *
522 * \return 0 for success
523 * \return -1 for error
524 */
525int stasis_app_control_redirect(struct stasis_app_control *control, const char *endpoint);
526
527/*!
528 * \brief Indicate ringing to 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 */
536
537/*!
538 * \brief Stop locally generated ringing on the channel associated with this control.
539 *
540 * \param control Control for \c res_stasis.
541 *
542 * \return 0 for success.
543 * \return -1 for error.
544 */
546
547/*!
548 * \brief Send DTMF to the channel associated with this control.
549 *
550 * \param control Control for \c res_stasis.
551 * \param dtmf DTMF string.
552 * \param before Amount of time to wait before sending DTMF digits.
553 * \param between Amount of time between each DTMF digit.
554 * \param duration Amount of time each DTMF digit lasts for.
555 * \param after Amount of time to wait after sending DTMF digits.
556 *
557 * \return 0 for success.
558 * \return -1 for error.
559 */
560int stasis_app_control_dtmf(struct stasis_app_control *control, const char *dtmf, int before, int between, unsigned int duration, int after);
561
562/*!
563 * \brief Mute 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 muted.
567 * \param frametype The type of stream that should be muted.
568 *
569 * \return 0 for success
570 * \return -1 for error.
571 */
572int stasis_app_control_mute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
573
574/*!
575 * \brief Unmute the channel associated with this control.
576 *
577 * \param control Control for \c res_stasis.
578 * \param direction The direction in which the audio should be unmuted.
579 * \param frametype The type of stream that should be unmuted.
580 *
581 * \return 0 for success
582 * \return -1 for error.
583 */
584int stasis_app_control_unmute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
585
586/*!
587 * \brief Answer the channel associated with this control.
588 * \param control Control for \c res_stasis.
589 * \return 0 for success.
590 * \return Non-zero for error.
591 */
593
594/*!
595 * \brief Set a variable on the channel associated with this control to value.
596 * \param control Control for \c res_stasis.
597 * \param variable The name of the variable
598 * \param value The value to set the variable to
599 *
600 * \return 0 for success.
601 * \return -1 for error.
602 */
603int stasis_app_control_set_channel_var(struct stasis_app_control *control, const char *variable, const char *value);
604
605/*!
606 * \brief Place the channel associated with the control on hold.
607 * \param control Control for \c res_stasis.
608 */
609void stasis_app_control_hold(struct stasis_app_control *control);
610
611/*!
612 * \brief Remove the channel associated with the control from hold.
613 * \param control Control for \c res_stasis.
614 */
616
617/*!
618 * \brief Play music on hold to a channel (does not affect hold status)
619 * \param control Control for \c res_stasis.
620 * \param moh_class class of music on hold to play (NULL allowed)
621 */
622void stasis_app_control_moh_start(struct stasis_app_control *control, const char *moh_class);
623
624/*!
625 * \brief Stop playing music on hold to a channel (does not affect hold status)
626 * \param control Control for \c res_stasis.
627 */
629
630/*!
631 * \brief Start playing silence to a channel.
632 * \param control Control for \c res_stasis.
633 */
635
636/*!
637 * \brief Stop playing silence to a channel.
638 * \param control Control for \c res_stasis.
639 */
641
642/*!
643 * \brief Returns the most recent snapshot for the associated channel.
644 *
645 * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
646 *
647 * \param control Control for \c res_stasis.
648 *
649 * \return Most recent snapshot. ao2_cleanup() when done.
650 * \retval NULL if channel isn't in cache.
651 */
653 const struct stasis_app_control *control);
654
655/*!
656 * \brief Publish a message to the \a control's channel's topic.
657 *
658 * \param control Control to publish to
659 * \param message Message to publish
660 */
662 struct stasis_app_control *control, struct stasis_message *message);
663
664/*!
665 * \brief Returns the stasis topic for an app
666 *
667 * \param app Stasis app to get topic of
668 */
670
671/*!
672 * \brief Queue a control frame without payload.
673 *
674 * \param control Control to publish to.
675 * \param frame_type type of control frame.
676 *
677 * \return zero on success
678 * \return non-zero on failure
679 */
682
683/*!
684 * \brief Create a 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 * \retval NULL on error.
692 */
693struct ast_bridge *stasis_app_bridge_create(const char *type, const char *name, const char *id);
694
695/*!
696 * \brief Create an invisible bridge of the specified type.
697 *
698 * \param type The type of bridge to be created
699 * \param name Optional name to give to the bridge
700 * \param id Optional Unique ID to give to the bridge
701 *
702 * \return New bridge.
703 * \retval NULL on error.
704 */
705struct ast_bridge *stasis_app_bridge_create_invisible(const char *type, const char *name, const char *id);
706
707/*!
708 * \brief Returns the bridge with the given id.
709 * \param bridge_id Uniqueid of the bridge.
710 *
711 * \return NULL bridge not created by a Stasis application, or bridge does not exist.
712 * \return Pointer to bridge.
713 */
715 const char *bridge_id);
716
717/*!
718 * \brief Finds or creates an announcer channel in a bridge that can play music on hold.
719 *
720 * \param bridge Bridge we want an MOH channel for
721 *
722 * \return NULL if the music on hold channel fails to be created or join the bridge for any reason.
723 * \return Pointer to the ;1 end of the announcer channel chain.
724 */
726 struct ast_bridge *bridge);
727
728/*!
729 * \brief Breaks down MOH channels playing on the bridge created by stasis_app_bridge_moh_channel
730 *
731 * \param bridge Bridge we want to stop the MOH on
732 *
733 * \return -1 if no moh channel could be found and stopped
734 * \return 0 on success
735 */
737 struct ast_bridge *bridge);
738
739/*!
740 * \brief Finds an existing ARI playback channel in a bridge
741 *
742 * \param bridge Bridge we want to find the playback channel for
743 *
744 * \return NULL if the playback channel can not be found for any reason.
745 * \return Pointer to the ;1 end of the playback channel chain.
746 */
748 struct ast_bridge *bridge);
749
750/*!
751 * \brief Adds a channel to the list of ARI playback channels for bridges.
752 *
753 * \param bridge Bridge we are adding the playback channel for
754 * \param chan Channel being added as a playback channel (must be ;1)
755 * \param control The app control structure for the playback channel
756 *
757 * \retval -1 failed to add channel for any reason
758 * \retval 0 on success
759 */
761 struct ast_channel *chan,
762 struct stasis_app_control *control);
763
764/*!
765 * \brief remove channel from list of ARI playback channels for bridges.
766 *
767 * \param bridge_id The unique ID of the bridge the playback channel is in.
768 * \param control The app control structure for the playback channel
769 */
771 struct stasis_app_control *control);
772
773/*!
774 * \brief Result codes used when adding/removing channels to/from bridges.
775 */
777 /*! The channel is okay to be added/removed */
779 /*! The channel is currently recording */
782
783/*!
784 * \brief Add a channel to the bridge.
785 *
786 * \param control Control whose channel should be added to the bridge
787 * \param bridge Pointer to the bridge
788 *
789 * \return non-zero on failure
790 * \return zero on success
791 */
793 struct stasis_app_control *control, struct ast_bridge *bridge);
794
795/*!
796 * \brief Remove a channel from the bridge.
797 *
798 * \param control Control whose channel should be removed from the bridge
799 * \param bridge Pointer to the bridge
800 *
801 * \return non-zero on failure
802 * \return zero on success
803 */
805 struct stasis_app_control *control, struct ast_bridge *bridge);
806
807/*!
808 * \brief Initialize bridge features into a channel control
809 *
810 * \note Bridge features on a control are destroyed after each bridge session,
811 * so new features need to be initialized before each bridge add.
812 *
813 * \param control Control in which to store the features
814 *
815 * \return non-zero on failure
816 * \return zero on success
817 */
819 struct stasis_app_control *control);
820
821/*!
822 * \brief Set whether DTMF from the channel is absorbed instead of passing through to the bridge
823 *
824 * \param control Control whose channel should have its DTMF absorbed when bridged
825 * \param absorb Whether DTMF should be absorbed (1) instead of passed through (0).
826 */
828 struct stasis_app_control *control, int absorb);
829
830/*!
831 * \brief Set whether audio from the channel is muted instead of passing through to the bridge
832 *
833 * \param control Control whose channel should have its audio muted when bridged
834 * \param mute Whether audio should be muted (1) instead of passed through (0).
835 */
837 struct stasis_app_control *control, int mute);
838
839/*!
840 * \since 18
841 * \brief Set whether COLP frames should be generated when joining the bridge
842 *
843 * \param control Control whose channel should have its COLP frames inhibited when bridged
844 * \param inhibit_colp Whether COLP frames should be generated (0) or not (1).
845 */
847 struct stasis_app_control *control, int inhibit_colp);
848
849/*!
850 * \since 12
851 * \brief Gets the bridge currently associated with a control object.
852 *
853 * \note If the bridge returned by this function is to be held for any
854 * length of time, its refcount should be incremented until the
855 * caller is finished with it.
856 *
857 * \param control Control object for the channel to query.
858 *
859 * \return Associated \ref ast_bridge.
860 * \retval NULL if not associated with a bridge.
861 */
863
864/*!
865 * \brief Destroy the bridge.
866 *
867 * \param bridge_id Uniqueid of bridge to be destroyed
868 */
869void stasis_app_bridge_destroy(const char *bridge_id);
870
871/*!
872 * \brief Get the Stasis message sanitizer for app_stasis applications
873 *
874 * \retval The stasis message sanitizer
875 */
877
878/*!
879 * \brief Indicate that this channel has had a StasisEnd published for it
880 *
881 * \param chan The channel that is exiting Stasis.
882 */
884
885/*!
886 * \brief Has this channel had a StasisEnd published on it?
887 *
888 * \param chan The channel upon which the query rests.
889 *
890 * \retval 0 No
891 * \retval 1 Yes
892 */
894
895/*!
896 * \brief Is this channel internal to Stasis?
897 *
898 * \param chan The channel to check.
899 *
900 * \retval 0 No
901 * \retval 1 Yes
902 */
904
905/*!
906 * \brief Mark this unreal channel and it's other half as being internal to Stasis.
907 *
908 * \param chan The channel to mark.
909 *
910 * \retval zero Success
911 * \retval non-zero Failure
912 */
914
915/*!
916 * \brief Mark this channel as being internal to Stasis.
917 *
918 * \param chan The channel to mark.
919 *
920 * \retval zero Success
921 * \retval non-zero Failure
922 */
924
925/*!
926 * \brief Dial a channel
927 * \param control Control for \c res_stasis.
928 * \param dialstring The dialstring to pass to the channel driver
929 * \param timeout Optional timeout in milliseconds
930 */
932 const char *dialstring, unsigned int timeout);
933
934/*!
935 * \brief Let Stasis app internals shut down
936 *
937 * This is called when res_stasis is unloaded. It ensures that
938 * the Stasis app internals can free any resources they may have
939 * allocated during the time that res_stasis was loaded.
940 */
942
943/*!
944 * \brief Enable/disable request/response and event logging on an application
945 *
946 * \param app The app to debug
947 * \param debug If non-zero, enable debugging. If zero, disable.
948 */
949void stasis_app_set_debug(struct stasis_app *app, int debug);
950
951/*!
952 * \brief Enable/disable request/response and event logging on an application
953 *
954 * \param app_name The app name to debug
955 * \param debug If non-zero, enable debugging. If zero, disable.
956 */
957void stasis_app_set_debug_by_name(const char *app_name, int debug);
958
959/*!
960 * \brief Get debug status of an application
961 *
962 * \param app The app to check
963 * \return The debug flag for the app || the global debug flag
964 */
966
967/*!
968 * \brief Get debug status of an application
969 *
970 * \param app_name The app_name to check
971 * \return The debug flag for the app || the global debug flag
972 */
974
975/*!
976 * \brief Enable/disable request/response and event logging on all applications
977 *
978 * \param debug If non-zero, enable debugging. If zero, disable.
979 */
981
982struct ast_cli_args;
983
984/*!
985 * \brief Dump properties of a \c stasis_app to the CLI
986 *
987 * \param app The application
988 * \param a The CLI arguments
989 */
990void stasis_app_to_cli(const struct stasis_app *app, struct ast_cli_args *a);
991
992/*!
993 * \brief Convert and add the app's event type filter(s) to the given json object.
994 *
995 * \param app The application
996 * \param json The json object to add the filter data to
997 *
998 * \return The given json object
999 */
1000struct ast_json *stasis_app_event_filter_to_json(struct stasis_app *app, struct ast_json *json);
1001
1002/*!
1003 * \brief Set the application's event type filter
1004 *
1005 * \param app The application
1006 * \param filter The allowed and/or disallowed event filter
1007 *
1008 * \return 0 if successfully set
1009 */
1011
1012/*!
1013 * \brief Check if the given event should be filtered.
1014 *
1015 * Attempts first to find the event in the application's disallowed events list.
1016 * If found then the event won't be sent to the remote. If not found in the
1017 * disallowed list then a search is done to see if it can be found in the allowed
1018 * list. If found the event message is sent, otherwise it is not sent.
1019 *
1020 * \param app_name The application name
1021 * \param event The event to check
1022 *
1023 * \return True if allowed, false otherwise
1024 */
1025int stasis_app_event_allowed(const char *app_name, struct ast_json *event);
1026
1027/*! @} */
1028
1029#endif /* _ASTERISK_STASIS_APP_H */
static const char app[]
Definition: app_adsiprog.c:56
enum queue_result id
Definition: app_queue.c:1667
static int priority
static const char type[]
Definition: chan_ooh323.c:109
General Asterisk PBX channel definitions.
frame_type
Definition: codec_builtin.c:44
static const char name[]
Definition: format_mp3.c:68
direction
static int filter(struct ast_channel *chan, const char *cmd, char *parse, char *buf, size_t len)
Definition: func_strings.c:807
ast_frame_type
Frame types.
ast_control_frame_type
Internal control frame subtype field values.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
const char * app_name(struct ast_app *app)
Definition: pbx_app.c:463
static int debug
Global debug status.
Definition: res_xmpp.c:441
void stasis_app_control_mute_in_bridge(struct stasis_app_control *control, int mute)
Set whether audio from the channel is muted instead of passing through to the bridge.
Definition: control.c:1479
void stasis_app_bridge_playback_channel_remove(char *bridge_id, struct stasis_app_control *control)
remove channel from list of ARI playback channels for bridges.
Definition: res_stasis.c:743
struct ast_json * stasis_app_object_to_json(struct stasis_app *app)
Return the JSON representation of a Stasis application.
Definition: res_stasis.c:1869
void stasis_app_set_debug(struct stasis_app *app, int debug)
Enable/disable request/response and event logging on an application.
struct stasis_message_sanitizer * stasis_app_get_sanitizer(void)
Get the Stasis message sanitizer for app_stasis applications.
Definition: res_stasis.c:2267
void stasis_app_control_register_remove_rule(struct stasis_app_control *control, struct stasis_app_control_rule *rule)
Registers a remove channel from bridge rule.
Definition: control.c:233
void stasis_app_control_moh_start(struct stasis_app_control *control, const char *moh_class)
Play music on hold to a channel (does not affect hold status)
Definition: control.c:789
const char * stasis_app_control_get_channel_id(const struct stasis_app_control *control)
Returns the uniqueid of the channel associated with this control.
Definition: control.c:1439
struct stasis_topic * ast_app_get_topic(struct stasis_app *app)
Returns the stasis topic for an app.
struct ast_bridge * stasis_app_bridge_create_invisible(const char *type, const char *name, const char *id)
Create an invisible bridge of the specified type.
Definition: res_stasis.c:859
int stasis_app_control_queue_control(struct stasis_app_control *control, enum ast_control_frame_type frame_type)
Queue a control frame without payload.
Definition: control.c:1454
int stasis_app_channel_is_internal(struct ast_channel *chan)
Is this channel internal to Stasis?
Definition: res_stasis.c:2325
void stasis_app_control_unregister_remove_rule(struct stasis_app_control *control, struct stasis_app_control_rule *rule)
Unregisters a remove channel from bridge rule.
Definition: control.c:240
int stasis_app_event_allowed(const char *app_name, struct ast_json *event)
Check if the given event should be filtered.
int stasis_app_control_unmute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype)
Unmute the channel associated with this control.
Definition: control.c:668
void stasis_app_control_unhold(struct stasis_app_control *control)
Remove the channel associated with the control from hold.
Definition: control.c:770
int stasis_app_send(const char *app_name, struct ast_json *message)
Send a message to the given Stasis application.
Definition: res_stasis.c:1659
int stasis_app_control_add_channel_to_bridge(struct stasis_app_control *control, struct ast_bridge *bridge)
Add a channel to the bridge.
Definition: control.c:1392
void stasis_app_unregister_event_sources(void)
Unregister core event sources.
enum stasis_app_subscribe_res stasis_app_subscribe(const char *app_name, const char **event_source_uris, int event_sources_count, struct ast_json **json)
Subscribes an application to a list of event sources.
Definition: res_stasis.c:2048
void stasis_app_control_silence_start(struct stasis_app_control *control)
Start playing silence to a channel.
Definition: control.c:841
void stasis_app_control_silence_stop(struct stasis_app_control *control)
Stop playing silence to a channel.
Definition: control.c:864
void stasis_app_channel_set_stasis_end_published(struct ast_channel *chan)
Indicate that this channel has had a StasisEnd published for it.
Definition: res_stasis.c:1290
void stasis_app_control_clear_roles(struct stasis_app_control *control)
Clear bridge roles currently applied to a channel controlled by a stasis app control.
Definition: control.c:347
void stasis_app_bridge_destroy(const char *bridge_id)
Destroy the bridge.
Definition: res_stasis.c:864
int stasis_app_control_continue(struct stasis_app_control *control, const char *context, const char *extension, int priority)
Exit res_stasis and continue execution in the dialplan.
Definition: control.c:398
stasis_app_user_event_res
Return code for stasis_app_user_event.
Definition: stasis_app.h:255
@ STASIS_APP_USER_APP_NOT_FOUND
Definition: stasis_app.h:257
@ STASIS_APP_USER_EVENT_SOURCE_NOT_FOUND
Definition: stasis_app.h:258
@ STASIS_APP_USER_EVENT_SOURCE_BAD_SCHEME
Definition: stasis_app.h:259
@ STASIS_APP_USER_USEREVENT_INVALID
Definition: stasis_app.h:260
@ STASIS_APP_USER_OK
Definition: stasis_app.h:256
@ STASIS_APP_USER_INTERNAL_ERROR
Definition: stasis_app.h:261
struct ast_json * stasis_app_to_json(const char *app_name)
Return the JSON representation of a Stasis application.
Definition: res_stasis.c:1879
void stasis_app_set_debug_by_name(const char *app_name, int debug)
Enable/disable request/response and event logging on an application.
int stasis_app_register(const char *app_name, stasis_app_cb handler, void *data)
Register a new Stasis application.
Definition: res_stasis.c:1780
void stasis_app_control_publish(struct stasis_app_control *control, struct stasis_message *message)
Publish a message to the control's channel's topic.
Definition: control.c:1445
int stasis_app_control_redirect(struct stasis_app_control *control, const char *endpoint)
Redirect a channel in res_stasis to a particular endpoint.
Definition: control.c:509
void stasis_app_control_moh_stop(struct stasis_app_control *control)
Stop playing music on hold to a channel (does not affect hold status)
Definition: control.c:807
int stasis_app_control_move(struct stasis_app_control *control, const char *app_name, const char *app_args)
Exit res_stasis and move to another Stasis application.
Definition: control.c:460
int stasis_app_channel_set_internal(struct ast_channel *chan)
Mark this channel as being internal to Stasis.
Definition: res_stasis.c:2314
struct ast_json * stasis_app_event_filter_to_json(struct stasis_app *app, struct ast_json *json)
Convert and add the app's event type filter(s) to the given json object.
struct ast_bridge * stasis_app_bridge_find_by_id(const char *bridge_id)
Returns the bridge with the given id.
Definition: res_stasis.c:774
void stasis_app_register_event_sources(void)
Register core event sources.
struct ast_bridge * stasis_app_bridge_create(const char *type, const char *name, const char *id)
Create a bridge of the specified type.
Definition: res_stasis.c:854
int stasis_app_control_mute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype)
Mute the channel associated with this control.
Definition: control.c:640
void stasis_app_unregister_event_source(struct stasis_app_event_source *obj)
Unregister an application event source.
Definition: res_stasis.c:1826
void stasis_app_control_absorb_dtmf_in_bridge(struct stasis_app_control *control, int absorb)
Set whether DTMF from the channel is absorbed instead of passing through to the bridge.
Definition: control.c:1473
int stasis_app_event_filter_set(struct stasis_app *app, struct ast_json *filter)
Set the application's event type filter.
enum stasis_app_subscribe_res stasis_app_subscribe_channel(const char *app_name, struct ast_channel *chan)
Directly subscribe an application to a channel.
Definition: res_stasis.c:1987
void(* stasis_app_cb)(void *data, const char *app_name, struct ast_json *message)
Callback for Stasis application handler.
Definition: stasis_app.h:67
void stasis_app_control_execute_until_exhausted(struct ast_channel *chan, struct stasis_app_control *control)
Act on a stasis app control queue until it is empty.
Definition: res_stasis.c:1253
struct ast_channel * stasis_app_bridge_moh_channel(struct ast_bridge *bridge)
Finds or creates an announcer channel in a bridge that can play music on hold.
Definition: res_stasis.c:629
enum stasis_app_user_event_res stasis_app_user_event(const char *app_name, const char *event_name, const char **source_uris, int sources_count, struct ast_json *json_variables)
Generate a Userevent for stasis app (echo to AMI)
Definition: res_stasis.c:2098
void stasis_app_set_global_debug(int debug)
Enable/disable request/response and event logging on all applications.
int stasis_app_control_dtmf(struct stasis_app_control *control, const char *dtmf, int before, int between, unsigned int duration, int after)
Send DTMF to the channel associated with this control.
Definition: control.c:574
int stasis_app_get_debug(struct stasis_app *app)
Get debug status of an application.
void stasis_app_control_flush_queue(struct stasis_app_control *control)
Flush the control command queue.
Definition: res_stasis.c:1281
void stasis_app_to_cli(const struct stasis_app *app, struct ast_cli_args *a)
Dump properties of a stasis_app to the CLI.
int stasis_app_control_add_role(struct stasis_app_control *control, const char *role)
Apply a bridge role to a channel controlled by a stasis app control.
Definition: control.c:325
int stasis_app_channel_unreal_set_internal(struct ast_channel *chan)
Mark this unreal channel and it's other half as being internal to Stasis.
Definition: res_stasis.c:2291
void stasis_app_control_inhibit_colp_in_bridge(struct stasis_app_control *control, int inhibit_colp)
Set whether COLP frames should be generated when joining the bridge.
Definition: control.c:1485
int stasis_app_control_remove_channel_from_bridge(struct stasis_app_control *control, struct ast_bridge *bridge)
Remove a channel from the bridge.
Definition: control.c:1429
struct ast_bridge * stasis_app_get_bridge(struct stasis_app_control *control)
Gets the bridge currently associated with a control object.
Definition: control.c:940
int stasis_app_control_bridge_features_init(struct stasis_app_control *control)
Initialize bridge features into a channel control.
Definition: control.c:1460
int stasis_app_bridge_playback_channel_add(struct ast_bridge *bridge, struct ast_channel *chan, struct stasis_app_control *control)
Adds a channel to the list of ARI playback channels for bridges.
Definition: res_stasis.c:705
void stasis_app_unregister(const char *app_name)
Unregister a Stasis application.
Definition: res_stasis.c:1790
enum stasis_app_subscribe_res stasis_app_unsubscribe(const char *app_name, const char **event_source_uris, int event_sources_count, struct ast_json **json)
Unsubscribes an application from a list of event sources.
Definition: res_stasis.c:2089
void stasis_app_control_hold(struct stasis_app_control *control)
Place the channel associated with the control on hold.
Definition: control.c:757
struct stasis_app * stasis_app_get_by_name(const char *name)
Retrieve a handle to a Stasis application by its name.
Definition: res_stasis.c:1697
void stasis_app_control_unregister_add_rule(struct stasis_app_control *control, struct stasis_app_control_rule *rule)
UnRegister an add channel to bridge rule.
Definition: control.c:226
struct stasis_app_control * stasis_app_control_find_by_channel_id(const char *channel_id)
Returns the handler for the channel with the given id.
Definition: res_stasis.c:349
void stasis_app_register_event_source(struct stasis_app_event_source *obj)
Register an application event source.
Definition: res_stasis.c:1819
struct ast_channel * stasis_app_bridge_playback_channel_find(struct ast_bridge *bridge)
Finds an existing ARI playback channel in a bridge.
Definition: res_stasis.c:759
struct ao2_container * stasis_app_get_all(void)
Gets the names of all registered Stasis applications.
Definition: res_stasis.c:1711
int stasis_app_control_is_done(struct stasis_app_control *control)
Check if a control is marked as done.
Definition: res_stasis.c:1276
int stasis_app_control_ring_stop(struct stasis_app_control *control)
Stop locally generated ringing on the channel associated with this control.
Definition: control.c:616
int stasis_app_control_dial(struct stasis_app_control *control, const char *dialstring, unsigned int timeout)
Dial a channel.
Definition: control.c:1675
struct ast_channel_snapshot * stasis_app_control_get_snapshot(const struct stasis_app_control *control)
Returns the most recent snapshot for the associated channel.
Definition: control.c:869
const char * stasis_app_name(const struct stasis_app *app)
Retrieve an application's name.
void stasis_app_control_register_add_rule(struct stasis_app_control *control, struct stasis_app_control_rule *rule)
Registers an add channel to bridge rule.
Definition: control.c:219
stasis_app_control_channel_result
Result codes used when adding/removing channels to/from bridges.
Definition: stasis_app.h:776
@ STASIS_APP_CHANNEL_RECORDING
Definition: stasis_app.h:780
@ STASIS_APP_CHANNEL_OKAY
Definition: stasis_app.h:778
stasis_app_subscribe_res
Return code for stasis_app_[un]subscribe.
Definition: stasis_app.h:282
@ STASIS_ASR_OK
Definition: stasis_app.h:283
@ STASIS_ASR_EVENT_SOURCE_BAD_SCHEME
Definition: stasis_app.h:286
@ STASIS_ASR_INTERNAL_ERROR
Definition: stasis_app.h:287
@ STASIS_ASR_EVENT_SOURCE_NOT_FOUND
Definition: stasis_app.h:285
@ STASIS_ASR_APP_NOT_FOUND
Definition: stasis_app.h:284
int stasis_app_channel_is_stasis_end_published(struct ast_channel *chan)
Has this channel had a StasisEnd published on it?
Definition: res_stasis.c:1302
struct stasis_app_control * stasis_app_control_find_by_channel(const struct ast_channel *chan)
Returns the handler for the given channel.
Definition: res_stasis.c:338
int stasis_app_control_set_channel_var(struct stasis_app_control *control, const char *variable, const char *value)
Set a variable on the channel associated with this control to value.
Definition: control.c:720
int stasis_app_register_all(const char *app_name, stasis_app_cb handler, void *data)
Register a new Stasis application that receives all Asterisk events.
Definition: res_stasis.c:1785
struct stasis_app_control * stasis_app_control_create(struct ast_channel *chan)
Creates a control handler for a channel that isn't in a stasis app.
Definition: res_stasis.c:333
int stasis_app_get_debug_by_name(const char *app_name)
Get debug status of an application.
int stasis_app_control_ring(struct stasis_app_control *control)
Indicate ringing to the channel associated with this control.
Definition: control.c:601
void stasis_app_control_shutdown(void)
Let Stasis app internals shut down.
Definition: control.c:1689
int stasis_app_bridge_moh_stop(struct ast_bridge *bridge)
Breaks down MOH channels playing on the bridge created by stasis_app_bridge_moh_channel.
Definition: res_stasis.c:649
int stasis_app_control_answer(struct stasis_app_control *control)
Answer the channel associated with this control.
Generic container type.
Structure that contains information about a bridge.
Definition: bridge.h:349
Structure representing a snapshot of channel state.
Main Channel structure associated with a channel.
struct ast_bridge * bridge
Abstract JSON element (object, array, string, int, ...).
Definition: astman.c:222
structure to hold extensions
Rule to check to see if an operation is allowed.
Definition: stasis_app.h:345
enum stasis_app_control_channel_result(* check_rule)(const struct stasis_app_control *control)
Checks to see if an operation is allowed on the control.
Definition: stasis_app.h:352
struct stasis_app_control_rule * next
Definition: stasis_app.h:355
Event source information and callbacks.
Definition: stasis_app.h:174
const char * scheme
The scheme to match against on [un]subscribes.
Definition: stasis_app.h:176
int(* unsubscribe)(struct stasis_app *app, const char *id)
Cancel the subscription an app has to an event source.
Definition: stasis_app.h:206
void(* to_json)(const struct stasis_app *app, struct ast_json *json)
Convert event source data to json.
Definition: stasis_app.h:224
struct stasis_app_event_source * next
Definition: stasis_app.h:227
int(* is_subscribed)(struct stasis_app *app, const char *id)
Find an event source by the given id/name.
Definition: stasis_app.h:216
int(* subscribe)(struct stasis_app *app, void *obj)
Subscribe an application to an event source.
Definition: stasis_app.h:196
Structure containing callbacks for Stasis message sanitization.
Definition: stasis.h:200
int value
Definition: syslog.c:37
static void handler(const char *name, int response_code, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
Definition: test_ari.c:59
static struct test_val a