Asterisk - The Open Source Telephony Project  18.5.0
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 <[email protected]>
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 <[email protected]>
28  * \since 12
29  *
30  * \page res_stasis Stasis Application API
31  *
32  * This is the API that binds the Stasis dialplan application to external
33  * Stasis applications, such as \c res_stasis_websocket.
34  *
35  * The associated \c res_stasis module registers a dialplan function named \c
36  * Stasis, which uses \c res_stasis to put a channel into the named Stasis
37  * app. As a channel enters and leaves the Stasis diaplan application, the
38  * Stasis app receives a \c 'stasis-start' and \c 'stasis-end' events.
39  *
40  * Stasis apps register themselves using the \ref stasis_app_register and
41  * stasis_app_unregister functions. Messages are sent to an appliction using
42  * \ref stasis_app_send.
43  *
44  * Finally, Stasis apps control channels through the use of the \ref
45  * stasis_app_control object, and the family of \c stasis_app_control_*
46  * functions.
47  *
48  * Since module unload order is based on reference counting, any module that
49  * uses the API defined in this file must list "res_stasis" in the requires
50  * field.
51  */
52 
53 #include "asterisk/channel.h"
54 
55 /*! @{ */
56 
57 /*!
58  * \brief Callback for Stasis application handler.
59  *
60  * The message given to the handler is a borrowed copy. If you want to keep a
61  * reference to it, you should use \c ao2_ref() to keep it around.
62  *
63  * \param data Data ptr given when registered.
64  * \param app_name Name of the application being dispatched to.
65  * \param message Message to handle. (borrowed copy)
66  */
67 typedef void (*stasis_app_cb)(void *data, const char *app_name,
68  struct ast_json *message);
69 
70 /*!
71  * \brief Gets the names of all registered Stasis applications.
72  *
73  * \return \c ast_str_container of container names.
74  * \return \c NULL on error.
75  */
76 struct ao2_container *stasis_app_get_all(void);
77 
78 /*!
79  * \brief Retrieve a handle to a Stasis application by its name
80  *
81  * \param name The name of the registered Stasis application
82  *
83  * \return \c stasis_app on success.
84  * \return \c NULL on error.
85  */
86 struct stasis_app *stasis_app_get_by_name(const char *name);
87 
88 /*!
89  * \brief Register a new Stasis application.
90  *
91  * If an application is already registered with the given name, the old
92  * application is sent a 'replaced' message and unregistered.
93  *
94  * \param app_name Name of this application.
95  * \param handler Callback for application messages.
96  * \param data Data blob to pass to the callback. Must be AO2 managed.
97  *
98  * \return 0 for success
99  * \return -1 for error.
100  */
101 int stasis_app_register(const char *app_name, stasis_app_cb handler, void *data);
102 
103 /*!
104  * \brief Register a new Stasis application that receives all Asterisk events.
105  *
106  * If an application is already registered with the given name, the old
107  * application is sent a 'replaced' message and unregistered.
108  *
109  * \param app_name Name of this application.
110  * \param handler Callback for application messages.
111  * \param data Data blob to pass to the callback. Must be AO2 managed.
112  *
113  * \return 0 for success
114  * \return -1 for error.
115  */
117 
118 /*!
119  * \brief Unregister a Stasis application.
120  * \param app_name Name of the application to unregister.
121  */
122 void stasis_app_unregister(const char *app_name);
123 
124 /*!
125  * \brief Send a message to the given Stasis application.
126  *
127  * The message given to the handler is a borrowed copy. If you want to keep a
128  * reference to it, you should use \c ao2_ref() to keep it around.
129  *
130  * \param app_name Name of the application to invoke.
131  * \param message Message to send (borrowed reference)
132  *
133  * \return 0 for success.
134  * \return -1 for error.
135  */
136 int stasis_app_send(const char *app_name, struct ast_json *message);
137 
138 /*! \brief Forward declare app */
139 struct stasis_app;
140 
141 /*!
142  * \brief Retrieve an application's name
143  *
144  * \param app An application
145  *
146  * \return The name of the application.
147  */
148 const char *stasis_app_name(const struct stasis_app *app);
149 
150 /*!
151  * \brief Return the JSON representation of a Stasis application.
152  * \since 16.3.0
153  *
154  * \param app The application.
155  *
156  * \return JSON representation of app with given name.
157  * \return \c NULL on error.
158  */
160 
161 /*!
162  * \brief Return the JSON representation of a Stasis application.
163  *
164  * \param app_name Name of the application.
165  *
166  * \return JSON representation of app with given name.
167  * \return \c NULL on error.
168  */
169 struct ast_json *stasis_app_to_json(const char *app_name);
170 
171 /*!
172  * \brief Event source information and callbacks.
173  */
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  *
456  * \return Nothing
457  */
459 
460 /*!
461  * \brief Returns the uniqueid of the channel associated with this control
462  *
463  * \param control Control object.
464  *
465  * \return Uniqueid of the associate channel.
466  * \return \c NULL if \a control is \c NULL.
467  */
469  const struct stasis_app_control *control);
470 
471 /*!
472  * \brief Apply a bridge role to a channel controlled by a stasis app control
473  *
474  * \param control Control for \c res_stasis
475  * \param role Role to apply
476  *
477  * \return 0 for success
478  * \return -1 for error.
479  */
480 int stasis_app_control_add_role(struct stasis_app_control *control, const char *role);
481 
482 /*!
483  * \brief Clear bridge roles currently applied to a channel controlled by a stasis app control
484  *
485  * \param control Control for \c res_stasis
486  */
488 
489 /*!
490  * \brief Exit \c res_stasis and continue execution in the dialplan.
491  *
492  * If the channel is no longer in \c res_stasis, this function does nothing.
493  *
494  * \param control Control for \c res_stasis
495  * \param context An optional context to continue to
496  * \param extension An optional extension to continue to
497  * \param priority An optional priority to continue to
498  *
499  * \return 0 for success
500  * \return -1 for error.
501  */
502 int stasis_app_control_continue(struct stasis_app_control *control, const char *context, const char *extension, int priority);
503 
504 /*!
505  * \brief Exit \c res_stasis and move to another Stasis application.
506  *
507  * If the channel is no longer in \c res_stasis, this function does nothing.
508  *
509  * \param control Control for \c res_stasis
510  * \param app_name The name of the application to switch to
511  * \param app_args The list of arguments to pass to the application
512  *
513  * \return 0 for success
514  * \return -1 for error
515  */
516 int stasis_app_control_move(struct stasis_app_control *control, const char *app_name, const char *app_args);
517 
518 /*!
519  * \brief Redirect a channel in \c res_stasis to a particular endpoint
520  *
521  * \param control Control for \c res_stasis
522  * \param endpoint The endpoint transfer string where the channel should be sent to
523  *
524  * \return 0 for success
525  * \return -1 for error
526  */
527 int stasis_app_control_redirect(struct stasis_app_control *control, const char *endpoint);
528 
529 /*!
530  * \brief Indicate ringing to the channel associated with this control.
531  *
532  * \param control Control for \c res_stasis.
533  *
534  * \return 0 for success.
535  * \return -1 for error.
536  */
537 int stasis_app_control_ring(struct stasis_app_control *control);
538 
539 /*!
540  * \brief Stop locally generated ringing on the channel associated with this control.
541  *
542  * \param control Control for \c res_stasis.
543  *
544  * \return 0 for success.
545  * \return -1 for error.
546  */
548 
549 /*!
550  * \brief Send DTMF to the channel associated with this control.
551  *
552  * \param control Control for \c res_stasis.
553  * \param dtmf DTMF string.
554  * \param before Amount of time to wait before sending DTMF digits.
555  * \param between Amount of time between each DTMF digit.
556  * \param duration Amount of time each DTMF digit lasts for.
557  * \param after Amount of time to wait after sending DTMF digits.
558  *
559  * \return 0 for success.
560  * \return -1 for error.
561  */
562 int stasis_app_control_dtmf(struct stasis_app_control *control, const char *dtmf, int before, int between, unsigned int duration, int after);
563 
564 /*!
565  * \brief Mute the channel associated with this control.
566  *
567  * \param control Control for \c res_stasis.
568  * \param direction The direction in which the audio should be muted.
569  * \param frametype The type of stream that should be muted.
570  *
571  * \return 0 for success
572  * \return -1 for error.
573  */
574 int stasis_app_control_mute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
575 
576 /*!
577  * \brief Unmute the channel associated with this control.
578  *
579  * \param control Control for \c res_stasis.
580  * \param direction The direction in which the audio should be unmuted.
581  * \param frametype The type of stream that should be unmuted.
582  *
583  * \return 0 for success
584  * \return -1 for error.
585  */
586 int stasis_app_control_unmute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
587 
588 /*!
589  * \brief Answer the channel associated with this control.
590  * \param control Control for \c res_stasis.
591  * \return 0 for success.
592  * \return Non-zero for error.
593  */
594 int stasis_app_control_answer(struct stasis_app_control *control);
595 
596 /*!
597  * \brief Set a variable on the channel associated with this control to value.
598  * \param control Control for \c res_stasis.
599  * \param variable The name of the variable
600  * \param value The value to set the variable to
601  *
602  * \return 0 for success.
603  * \return -1 for error.
604  */
605 int stasis_app_control_set_channel_var(struct stasis_app_control *control, const char *variable, const char *value);
606 
607 /*!
608  * \brief Place the channel associated with the control on hold.
609  * \param control Control for \c res_stasis.
610  */
611 void stasis_app_control_hold(struct stasis_app_control *control);
612 
613 /*!
614  * \brief Remove the channel associated with the control from hold.
615  * \param control Control for \c res_stasis.
616  */
617 void stasis_app_control_unhold(struct stasis_app_control *control);
618 
619 /*!
620  * \brief Play music on hold to a channel (does not affect hold status)
621  * \param control Control for \c res_stasis.
622  * \param moh_class class of music on hold to play (NULL allowed)
623  */
624 void stasis_app_control_moh_start(struct stasis_app_control *control, const char *moh_class);
625 
626 /*!
627  * \brief Stop playing music on hold to a channel (does not affect hold status)
628  * \param control Control for \c res_stasis.
629  */
630 void stasis_app_control_moh_stop(struct stasis_app_control *control);
631 
632 /*!
633  * \brief Start playing silence to a channel.
634  * \param control Control for \c res_stasis.
635  */
637 
638 /*!
639  * \brief Stop playing silence to a channel.
640  * \param control Control for \c res_stasis.
641  */
643 
644 /*!
645  * \brief Returns the most recent snapshot for the associated channel.
646  *
647  * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
648  *
649  * \param control Control for \c res_stasis.
650  *
651  * \return Most recent snapshot. ao2_cleanup() when done.
652  * \return \c NULL if channel isn't in cache.
653  */
655  const struct stasis_app_control *control);
656 
657 /*!
658  * \brief Publish a message to the \a control's channel's topic.
659  *
660  * \param control Control to publish to
661  * \param message Message to publish
662  */
664  struct stasis_app_control *control, struct stasis_message *message);
665 
666 /*!
667  * \brief Returns the stasis topic for an app
668  *
669  * \param app Stasis app to get topic of
670  */
672 
673 /*!
674  * \brief Queue a control frame without payload.
675  *
676  * \param control Control to publish to.
677  * \param frame_type type of control frame.
678  *
679  * \return zero on success
680  * \return non-zero on failure
681  */
684 
685 /*!
686  * \brief Create a bridge of the specified type.
687  *
688  * \param type The type of bridge to be created
689  * \param name Optional name to give to the bridge
690  * \param id Optional Unique ID to give to the bridge
691  *
692  * \return New bridge.
693  * \return \c NULL on error.
694  */
695 struct ast_bridge *stasis_app_bridge_create(const char *type, const char *name, const char *id);
696 
697 /*!
698  * \brief Create an invisible bridge of the specified type.
699  *
700  * \param type The type of bridge to be created
701  * \param name Optional name to give to the bridge
702  * \param id Optional Unique ID to give to the bridge
703  *
704  * \return New bridge.
705  * \return \c NULL on error.
706  */
707 struct ast_bridge *stasis_app_bridge_create_invisible(const char *type, const char *name, const char *id);
708 
709 /*!
710  * \brief Returns the bridge with the given id.
711  * \param bridge_id Uniqueid of the bridge.
712  *
713  * \return NULL bridge not created by a Stasis application, or bridge does not exist.
714  * \return Pointer to bridge.
715  */
717  const char *bridge_id);
718 
719 /*!
720  * \brief Finds or creates an announcer channel in a bridge that can play music on hold.
721  *
722  * \param bridge Bridge we want an MOH channel for
723  *
724  * \return NULL if the music on hold channel fails to be created or join the bridge for any reason.
725  * \return Pointer to the ;1 end of the announcer channel chain.
726  */
728  struct ast_bridge *bridge);
729 
730 /*!
731  * \brief Breaks down MOH channels playing on the bridge created by stasis_app_bridge_moh_channel
732  *
733  * \param bridge Bridge we want to stop the MOH on
734  *
735  * \return -1 if no moh channel could be found and stopped
736  * \return 0 on success
737  */
739  struct ast_bridge *bridge);
740 
741 /*!
742  * \brief Finds an existing ARI playback channel in a bridge
743  *
744  * \param bridge Bridge we want to find the playback channel for
745  *
746  * \return NULL if the playback channel can not be found for any reason.
747  * \return Pointer to the ;1 end of the playback channel chain.
748  */
750  struct ast_bridge *bridge);
751 
752 /*!
753  * \brief Adds a channel to the list of ARI playback channels for bridges.
754  *
755  * \param bridge Bridge we are adding the playback channel for
756  * \param chan Channel being added as a playback channel (must be ;1)
757  *
758  * \retval -1 failed to add channel for any reason
759  * \retval 0 on success
760  */
762  struct ast_channel *chan,
763  struct stasis_app_control *control);
764 
765 /*!
766  * \brief remove channel from list of ARI playback channels for bridges.
767  *
768  * \param bridge_id The unique ID of the bridge the playback channel is in.
769  * \param control The app control structure for the playback channel
770  */
771 void stasis_app_bridge_playback_channel_remove(char *bridge_id,
772  struct stasis_app_control *control);
773 
774 /*!
775  * \brief Result codes used when adding/removing channels to/from bridges.
776  */
778  /*! The channel is okay to be added/removed */
780  /*! The channel is currently recording */
782 };
783 
784 /*!
785  * \brief Add a channel to the bridge.
786  *
787  * \param control Control whose channel should be added to the bridge
788  * \param bridge Pointer to the bridge
789  *
790  * \return non-zero on failure
791  * \return zero on success
792  */
794  struct stasis_app_control *control, struct ast_bridge *bridge);
795 
796 /*!
797  * \brief Remove a channel from the bridge.
798  *
799  * \param control Control whose channel should be removed from the bridge
800  * \param bridge Pointer to the bridge
801  *
802  * \return non-zero on failure
803  * \return zero on success
804  */
806  struct stasis_app_control *control, struct ast_bridge *bridge);
807 
808 /*!
809  * \brief Initialize bridge features into a channel control
810  *
811  * \note Bridge features on a control are destroyed after each bridge session,
812  * so new features need to be initialized before each bridge add.
813  *
814  * \param control Control in which to store the features
815  *
816  * \return non-zero on failure
817  * \return zero on success
818  */
820  struct stasis_app_control *control);
821 
822 /*!
823  * \brief Set whether DTMF from the channel is absorbed instead of passing through to the bridge
824  *
825  * \param control Control whose channel should have its DTMF absorbed when bridged
826  * \param absorb Whether DTMF should be absorbed (1) instead of passed through (0).
827  */
829  struct stasis_app_control *control, int absorb);
830 
831 /*!
832  * \brief Set whether audio from the channel is muted instead of passing through to the bridge
833  *
834  * \param control Control whose channel should have its audio muted when bridged
835  * \param mute Whether audio should be muted (1) instead of passed through (0).
836  */
838  struct stasis_app_control *control, int mute);
839 
840 /*!
841  * \since 18
842  * \brief Set whether COLP frames should be generated when joining the bridge
843  *
844  * \param control Control whose channel should have its COLP frames inhibited when bridged
845  * \param mute Whether COLP frames should be generated (0) or not (1).
846  */
848  struct stasis_app_control *control, int inhibit_colp);
849 
850 /*!
851  * \since 12
852  * \brief Gets the bridge currently associated with a control object.
853  *
854  * \note If the bridge returned by this function is to be held for any
855  * length of time, its refcount should be incremented until the
856  * caller is finished with it.
857  *
858  * \param control Control object for the channel to query.
859  *
860  * \return Associated \ref ast_bridge.
861  * \return \c NULL if not associated with a bridge.
862  */
863 struct ast_bridge *stasis_app_get_bridge(struct stasis_app_control *control);
864 
865 /*!
866  * \brief Destroy the bridge.
867  *
868  * \param bridge_id Uniqueid of bridge to be destroyed
869  *
870  * \retval non-zero on failure
871  * \retval zero on success
872  */
873 void stasis_app_bridge_destroy(const char *bridge_id);
874 
875 /*!
876  * \brief Get the Stasis message sanitizer for app_stasis applications
877  *
878  * \retval The stasis message sanitizer
879  */
881 
882 /*!
883  * \brief Indicate that this channel has had a StasisEnd published for it
884  *
885  * \param The channel that is exiting Stasis.
886  */
888 
889 /*!
890  * \brief Has this channel had a StasisEnd published on it?
891  *
892  * \param chan The channel upon which the query rests.
893  *
894  * \retval 0 No
895  * \retval 1 Yes
896  */
898 
899 /*!
900  * \brief Is this channel internal to Stasis?
901  *
902  * \param chan The channel to check.
903  *
904  * \retval 0 No
905  * \retval 1 Yes
906  */
908 
909 /*!
910  * \brief Mark this unreal channel and it's other half as being internal to Stasis.
911  *
912  * \param chan The channel to mark.
913  *
914  * \retval zero Success
915  * \retval non-zero Failure
916  */
918 
919 /*!
920  * \brief Mark this channel as being internal to Stasis.
921  *
922  * \param chan The channel to mark.
923  *
924  * \retval zero Success
925  * \retval non-zero Failure
926  */
928 
929 /*!
930  * \brief Dial a channel
931  * \param control Control for \c res_stasis.
932  * \param dialstring The dialstring to pass to the channel driver
933  * \param timeout Optional timeout in milliseconds
934  */
935 int stasis_app_control_dial(struct stasis_app_control *control,
936  const char *dialstring, unsigned int timeout);
937 
938 /*!
939  * \brief Let Stasis app internals shut down
940  *
941  * This is called when res_stasis is unloaded. It ensures that
942  * the Stasis app internals can free any resources they may have
943  * allocated during the time that res_stasis was loaded.
944  */
945 void stasis_app_control_shutdown(void);
946 
947 /*!
948  * \brief Enable/disable request/response and event logging on an application
949  *
950  * \param app The app to debug
951  * \param debug If non-zero, enable debugging. If zero, disable.
952  */
953 void stasis_app_set_debug(struct stasis_app *app, int debug);
954 
955 /*!
956  * \brief Enable/disable request/response and event logging on an application
957  *
958  * \param app_name The app name to debug
959  * \param debug If non-zero, enable debugging. If zero, disable.
960  */
961 void stasis_app_set_debug_by_name(const char *app_name, int debug);
962 
963 /*!
964  * \brief Get debug status of an application
965  *
966  * \param app The app to check
967  * \return The debug flag for the app || the global debug flag
968  */
969 int stasis_app_get_debug(struct stasis_app *app);
970 
971 /*!
972  * \brief Get debug status of an application
973  *
974  * \param app_name The app_name to check
975  * \return The debug flag for the app || the global debug flag
976  */
977 int stasis_app_get_debug_by_name(const char *app_name);
978 
979 /*!
980  * \brief Enable/disable request/response and event logging on all applications
981  *
982  * \param debug If non-zero, enable debugging. If zero, disable.
983  */
985 
986 struct ast_cli_args;
987 
988 /*!
989  * \brief Dump properties of a \c stasis_app to the CLI
990  *
991  * \param app The application
992  * \param a The CLI arguments
993  */
994 void stasis_app_to_cli(const struct stasis_app *app, struct ast_cli_args *a);
995 
996 /*!
997  * \brief Convert and add the app's event type filter(s) to the given json object.
998  *
999  * \param app The application
1000  * \param json The json object to add the filter data to
1001  *
1002  * \return The given json object
1003  */
1004 struct ast_json *stasis_app_event_filter_to_json(struct stasis_app *app, struct ast_json *json);
1005 
1006 /*!
1007  * \brief Set the application's event type filter
1008  *
1009  * \param app The application
1010  * \param filter The allowed and/or disallowed event filter
1011  *
1012  * \return 0 if successfully set
1013  */
1015 
1016 /*!
1017  * \brief Check if the given event should be filtered.
1018  *
1019  * Attempts first to find the event in the application's disallowed events list.
1020  * If found then the event won't be sent to the remote. If not found in the
1021  * disallowed list then a search is done to see if it can be found in the allowed
1022  * list. If found the event message is sent, otherwise it is not sent.
1023  *
1024  * \param app_name The application name
1025  * \param event The event to check
1026  *
1027  * \return True if allowed, false otherwise
1028  */
1029 int stasis_app_event_allowed(const char *app_name, struct ast_json *event);
1030 
1031 /*! @} */
1032 
1033 #endif /* _ASTERISK_STASIS_APP_H */
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_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
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
static const char type[]
Definition: chan_ooh323.c:109
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_control_publish(struct stasis_app_control *control, struct stasis_message *message)
Publish a message to the control&#39;s channel&#39;s topic.
Definition: control.c:1436
int stasis_app_event_filter_set(struct stasis_app *app, struct ast_json *filter)
Set the application&#39;s event type filter.
Main Channel structure associated with a channel.
struct stasis_topic * ast_app_get_topic(struct stasis_app *app)
Returns the stasis topic for an app.
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_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_control_bridge_features_init(struct stasis_app_control *control)
Initialize bridge features into a channel control.
Definition: control.c:1451
int stasis_app_control_is_done(struct stasis_app_control *control)
Check if a control is marked as done.
Definition: res_stasis.c:1273
void stasis_app_register_event_sources(void)
Register core event sources.
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
void stasis_app_set_debug_by_name(const char *app_name, int debug)
Enable/disable request/response and event logging on an application.
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
const char * scheme
The scheme to match against on [un]subscribes.
Definition: stasis_app.h:176
struct stasis_app_control * stasis_app_control_create(struct ast_channel *chan)
Creates a control handler for a channel that isn&#39;t in a stasis app.
Definition: res_stasis.c:333
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
static int debug
Global debug status.
Definition: res_xmpp.c:435
static int timeout
Definition: cdr_mysql.c:86
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
Structure representing a snapshot of channel state.
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_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_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
void stasis_app_control_hold(struct stasis_app_control *control)
Place the channel associated with the control on hold.
Definition: control.c:748
void stasis_app_control_silence_stop(struct stasis_app_control *control)
Stop playing silence to a channel.
Definition: control.c:855
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
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
Definition: astman.c:222
int stasis_app_event_allowed(const char *app_name, struct ast_json *event)
Check if the given event should be filtered.
ast_control_frame_type
Internal control frame subtype field values.
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
int value
Definition: syslog.c:37
static int priority
Structure containing callbacks for Stasis message sanitization.
Definition: stasis.h:200
int stasis_app_channel_unreal_set_internal(struct ast_channel *chan)
Mark this unreal channel and it&#39;s other half as being internal to Stasis.
Definition: res_stasis.c:2288
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
static int mute
Definition: chan_alsa.c:144
int stasis_app_get_debug_by_name(const char *app_name)
Get debug status of an application.
void(* to_json)(const struct stasis_app *app, struct ast_json *json)
Convert event source data to json.
Definition: stasis_app.h:224
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
int stasis_app_channel_set_internal(struct ast_channel *chan)
Mark this channel as being internal to Stasis.
Definition: res_stasis.c:2311
void stasis_app_unregister(const char *app_name)
Unregister a Stasis application.
Definition: res_stasis.c:1787
int(* unsubscribe)(struct stasis_app *app, const char *id)
Cancel the subscription an app has to an event source.
Definition: stasis_app.h:206
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
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
General Asterisk PBX channel definitions.
stasis_app_control_channel_result
Result codes used when adding/removing channels to/from bridges.
Definition: stasis_app.h:777
Event source information and callbacks.
Definition: stasis_app.h:174
void stasis_app_control_shutdown(void)
Let Stasis app internals shut down.
Definition: control.c:1680
const char * stasis_app_name(const struct stasis_app *app)
Retrieve an application&#39;s name.
structure to hold extensions
int stasis_app_control_dial(struct stasis_app_control *control, const char *dialstring, unsigned int timeout)
Dial a channel.
Definition: control.c:1666
Rule to check to see if an operation is allowed.
Definition: stasis_app.h:345
struct ast_json * stasis_app_event_filter_to_json(struct stasis_app *app, struct ast_json *json)
Convert and add the app&#39;s event type filter(s) to the given json object.
void stasis_app_control_flush_queue(struct stasis_app_control *control)
Flush the control command queue.
Definition: res_stasis.c:1278
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
int stasis_app_get_debug(struct stasis_app *app)
Get debug status of an application.
ast_frame_type
Frame types.
void stasis_app_unregister_event_source(struct stasis_app_event_source *obj)
Unregister an application event source.
Definition: res_stasis.c:1823
Structure that contains information about a bridge.
Definition: bridge.h:357
struct stasis_message_sanitizer * stasis_app_get_sanitizer(void)
Get the Stasis message sanitizer for app_stasis applications.
Definition: res_stasis.c:2264
int stasis_app_control_ring(struct stasis_app_control *control)
Indicate ringing to the channel associated with this control.
Definition: control.c:592
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
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_redirect(struct stasis_app_control *control, const char *endpoint)
Redirect a channel in res_stasis to a particular endpoint.
Definition: control.c:500
frame_type
Definition: codec_builtin.c:44
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
const char * app_name(struct ast_app *app)
Definition: pbx_app.c:463
void stasis_app_bridge_destroy(const char *bridge_id)
Destroy the bridge.
Definition: res_stasis.c:861
void stasis_app_set_global_debug(int debug)
Enable/disable request/response and event logging on all applications.
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_register(const char *app_name, stasis_app_cb handler, void *data)
Register a new Stasis application.
Definition: res_stasis.c:1777
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
void stasis_app_control_unhold(struct stasis_app_control *control)
Remove the channel associated with the control from hold.
Definition: control.c:761
static const char name[]
Definition: cdr_mysql.c:74
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
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
struct ao2_container * stasis_app_get_all(void)
Gets the names of all registered Stasis applications.
Definition: res_stasis.c:1708
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_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_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
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
stasis_app_subscribe_res
Return code for stasis_app_[un]subscribe.
Definition: stasis_app.h:282
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_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
void(* stasis_app_cb)(void *data, const char *app_name, struct ast_json *message)
Callback for Stasis application handler.
Definition: stasis_app.h:67
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_is_internal(struct ast_channel *chan)
Is this channel internal to Stasis?
Definition: res_stasis.c:2322
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
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
stasis_app_user_event_res
Return code for stasis_app_user_event.
Definition: stasis_app.h:255
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
int stasis_app_control_answer(struct stasis_app_control *control)
Answer the channel associated with this control.
struct stasis_app_event_source * next
Definition: stasis_app.h:227
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
void stasis_app_set_debug(struct stasis_app *app, int debug)
Enable/disable request/response and event logging on an application.
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
Abstract JSON element (object, array, string, int, ...).
void stasis_app_control_silence_start(struct stasis_app_control *control)
Start playing silence to a channel.
Definition: control.c:832
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
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
enum queue_result id
Definition: app_queue.c:1507
Generic container type.
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:116
static int filter(struct ast_channel *chan, const char *cmd, char *parse, char *buf, size_t len)
Definition: func_strings.c:709
void stasis_app_unregister_event_sources(void)
Unregister core event sources.
int(* is_subscribed)(struct stasis_app *app, const char *id)
Find an event source by the given id/name.
Definition: stasis_app.h:216
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
direction
static const char app[]
Definition: app_mysql.c:62
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
struct ast_json * stasis_app_to_json(const char *app_name)
Return the JSON representation of a Stasis application.
Definition: res_stasis.c:1876
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
int(* subscribe)(struct stasis_app *app, void *obj)
Subscribe an application to an event source.
Definition: stasis_app.h:196
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
void stasis_app_register_event_source(struct stasis_app_event_source *obj)
Register an application event source.
Definition: res_stasis.c:1816
struct stasis_app_control_rule * next
Definition: stasis_app.h:355
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
static struct test_val a
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