Asterisk - The Open Source Telephony Project  GIT-master-a24979a
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  */
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  * \retval 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  * \retval 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  */
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  * \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  */
169 struct 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 */
342 struct 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,
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  */
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  */
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  */
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  */
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  */
478 int 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  */
500 int 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  */
514 int 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  */
525 int 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  */
535 int stasis_app_control_ring(struct stasis_app_control *control);
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  */
560 int 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  */
572 int 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  */
584 int 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  */
592 int stasis_app_control_answer(struct stasis_app_control *control);
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  */
603 int 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  */
609 void 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  */
615 void stasis_app_control_unhold(struct stasis_app_control *control);
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  */
622 void 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  */
628 void stasis_app_control_moh_stop(struct stasis_app_control *control);
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  */
693 struct 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  */
705 struct 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  */
770 void stasis_app_bridge_playback_channel_remove(char *bridge_id,
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 */
781 };
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  */
862 struct ast_bridge *stasis_app_get_bridge(struct stasis_app_control *control);
863 
864 /*!
865  * \brief Destroy the bridge.
866  *
867  * \param bridge_id Uniqueid of bridge to be destroyed
868  */
869 void 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  */
931 int stasis_app_control_dial(struct stasis_app_control *control,
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  */
941 void stasis_app_control_shutdown(void);
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  */
949 void 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  */
957 void 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  */
965 int stasis_app_get_debug(struct stasis_app *app);
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  */
973 int stasis_app_get_debug_by_name(const char *app_name);
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 
982 struct 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  */
990 void 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  */
1000 struct 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  */
1025 int 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:1640
static int priority
static int mute
Definition: chan_alsa.c:148
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:120
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:734
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:1470
struct ast_bridge * stasis_app_get_bridge(struct stasis_app_control *control)
Gets the bridge currently associated with a control object.
Definition: control.c:931
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
void stasis_app_set_debug(struct stasis_app *app, int debug)
Enable/disable request/response and event logging on an application.
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:231
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:856
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:780
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:1445
struct stasis_topic * ast_app_get_topic(struct stasis_app *app)
Returns the stasis topic for an app.
int stasis_app_channel_is_internal(struct ast_channel *chan)
Is this channel internal to Stasis?
Definition: res_stasis.c:2322
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:238
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:659
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
void stasis_app_control_unhold(struct stasis_app_control *control)
Remove the channel associated with the control from hold.
Definition: control.c:761
int stasis_app_send(const char *app_name, struct ast_json *message)
Send a message to the given Stasis application.
Definition: res_stasis.c:1656
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:860
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:1383
void stasis_app_unregister_event_sources(void)
Unregister core event sources.
struct ast_json * stasis_app_object_to_json(struct stasis_app *app)
Return the JSON representation of a Stasis application.
Definition: res_stasis.c:1866
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:2045
void stasis_app_control_silence_start(struct stasis_app_control *control)
Start playing silence to a channel.
Definition: control.c:832
void stasis_app_control_silence_stop(struct stasis_app_control *control)
Stop playing silence to a channel.
Definition: control.c:855
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:1694
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:1287
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:338
void stasis_app_bridge_destroy(const char *bridge_id)
Destroy the bridge.
Definition: res_stasis.c:861
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:389
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
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:1777
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:1436
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:500
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:798
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:451
int stasis_app_channel_set_internal(struct ast_channel *chan)
Mark this channel as being internal to Stasis.
Definition: res_stasis.c:2311
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
void stasis_app_register_event_sources(void)
Register core event sources.
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:631
void stasis_app_unregister_event_source(struct stasis_app_event_source *obj)
Unregister an application event source.
Definition: res_stasis.c:1823
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:1464
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:1984
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:1250
struct stasis_message_sanitizer * stasis_app_get_sanitizer(void)
Get the Stasis message sanitizer for app_stasis applications.
Definition: res_stasis.c:2264
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:1430
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:2095
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:565
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:1278
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.
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:316
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:2288
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:1476
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_remove_channel_from_bridge(struct stasis_app_control *control, struct ast_bridge *bridge)
Remove a channel from the bridge.
Definition: control.c:1420
int stasis_app_control_bridge_features_init(struct stasis_app_control *control)
Initialize bridge features into a channel control.
Definition: control.c:1451
const char * stasis_app_name(const struct stasis_app *app)
Retrieve an application's name.
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:851
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:1787
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:2086
void stasis_app_control_hold(struct stasis_app_control *control)
Place the channel associated with the control on hold.
Definition: control.c:748
struct ao2_container * stasis_app_get_all(void)
Gets the names of all registered Stasis applications.
Definition: res_stasis.c:1708
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:224
void stasis_app_register_event_source(struct stasis_app_event_source *obj)
Register an application event source.
Definition: res_stasis.c:1816
int stasis_app_control_is_done(struct stasis_app_control *control)
Check if a control is marked as done.
Definition: res_stasis.c:1273
struct ast_json * stasis_app_to_json(const char *app_name)
Return the JSON representation of a Stasis application.
Definition: res_stasis.c:1876
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:607
int stasis_app_control_dial(struct stasis_app_control *control, const char *dialstring, unsigned int timeout)
Dial a channel.
Definition: control.c:1666
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
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_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:217
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:1299
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_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:711
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:1782
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:592
void stasis_app_control_shutdown(void)
Let Stasis app internals shut down.
Definition: control.c:1680
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