stasis_app.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2012 - 2013, Digium, Inc.
00005  *
00006  * David M. Lee, II <dlee@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 #ifndef _ASTERISK_STASIS_APP_H
00020 #define _ASTERISK_STASIS_APP_H
00021 
00022 /*! \file
00023  *
00024  * \brief Stasis Application API. See \ref res_stasis "Stasis Application API"
00025  * for detailed documentation.
00026  *
00027  * \author David M. Lee, II <dlee@digium.com>
00028  * \since 12
00029  *
00030  * \page res_stasis Stasis Application API
00031  *
00032  * This is the API that binds the Stasis dialplan application to external
00033  * Stasis applications, such as \c res_stasis_websocket.
00034  *
00035  * The associated \c res_stasis module registers a dialplan function named \c
00036  * Stasis, which uses \c res_stasis to put a channel into the named Stasis
00037  * app. As a channel enters and leaves the Stasis diaplan application, the
00038  * Stasis app receives a \c 'stasis-start' and \c 'stasis-end' events.
00039  *
00040  * Stasis apps register themselves using the \ref stasis_app_register and
00041  * stasis_app_unregister functions. Messages are sent to an appliction using
00042  * \ref stasis_app_send.
00043  *
00044  * Finally, Stasis apps control channels through the use of the \ref
00045  * stasis_app_control object, and the family of \c stasis_app_control_*
00046  * functions.
00047  *
00048  * Since module unload order is based on reference counting, any module that
00049  * uses the API defined in this file must call stasis_app_ref() when loaded,
00050  * and stasis_app_unref() when unloaded.
00051  */
00052 
00053 #include "asterisk/channel.h"
00054 #include "asterisk/json.h"
00055 
00056 /*! @{ */
00057 
00058 /*!
00059  * \brief Callback for Stasis application handler.
00060  *
00061  * The message given to the handler is a borrowed copy. If you want to keep a
00062  * reference to it, you should use \c ao2_ref() to keep it around.
00063  *
00064  * \param data Data ptr given when registered.
00065  * \param app_name Name of the application being dispatched to.
00066  * \param message Message to handle. (borrowed copy)
00067  */
00068 typedef void (*stasis_app_cb)(void *data, const char *app_name,
00069    struct ast_json *message);
00070 
00071 /*!
00072  * \brief Gets the names of all registered Stasis applications.
00073  *
00074  * \return \c ast_str_container of container names.
00075  * \return \c NULL on error.
00076  */
00077 struct ao2_container *stasis_app_get_all(void);
00078 
00079 /*!
00080  * \brief Register a new Stasis application.
00081  *
00082  * If an application is already registered with the given name, the old
00083  * application is sent a 'replaced' message and unregistered.
00084  *
00085  * \param app_name Name of this application.
00086  * \param handler Callback for application messages.
00087  * \param data Data blob to pass to the callback. Must be AO2 managed.
00088  *
00089  * \return 0 for success
00090  * \return -1 for error.
00091  */
00092 int stasis_app_register(const char *app_name, stasis_app_cb handler, void *data);
00093 
00094 /*!
00095  * \brief Unregister a Stasis application.
00096  * \param app_name Name of the application to unregister.
00097  */
00098 void stasis_app_unregister(const char *app_name);
00099 
00100 /*!
00101  * \brief Send a message to the given Stasis application.
00102  *
00103  * The message given to the handler is a borrowed copy. If you want to keep a
00104  * reference to it, you should use \c ao2_ref() to keep it around.
00105  *
00106  * \param app_name Name of the application to invoke.
00107  * \param message Message to send (borrowed reference)
00108  *
00109  * \return 0 for success.
00110  * \return -1 for error.
00111  */
00112 int stasis_app_send(const char *app_name, struct ast_json *message);
00113 
00114 /*! \brief Forward declare app */
00115 struct stasis_app;
00116 
00117 /*!
00118  * \brief Retrieve an application's name
00119  *
00120  * \param app An application
00121  *
00122  * \return The name of the application.
00123  */
00124 const char *stasis_app_name(const struct stasis_app *app);
00125 
00126 /*!
00127  * \brief Return the JSON representation of a Stasis application.
00128  *
00129  * \param app_name Name of the application.
00130  *
00131  * \return JSON representation of app with given name.
00132  * \return \c NULL on error.
00133  */
00134 struct ast_json *stasis_app_to_json(const char *app_name);
00135 
00136 /*!
00137  * \brief Event source information and callbacks.
00138  */
00139 struct stasis_app_event_source {
00140    /*! \brief The scheme to match against on [un]subscribes */
00141    const char *scheme;
00142 
00143    /*!
00144     * \brief Find an event source data object by the given id/name.
00145     *
00146     * \param app Application
00147     * \param id A unique identifier to search on
00148     *
00149     * \return The data object associated with the id/name.
00150     */
00151    void *(*find)(const struct stasis_app *app, const char *id);
00152 
00153    /*!
00154     * \brief Subscribe an application to an event source.
00155     *
00156     * \param app Application
00157     * \param obj an event source data object
00158     *
00159     * \return 0 on success, failure code otherwise
00160     */
00161    int (*subscribe)(struct stasis_app *app, void *obj);
00162 
00163    /*!
00164     * \brief Cancel the subscription an app has to an event source.
00165     *
00166     * \param app Application
00167     * \param id a previously subscribed object id
00168     *
00169     * \return 0 on success, failure code otherwise
00170     */
00171    int (*unsubscribe)(struct stasis_app *app, const char *id);
00172 
00173    /*!
00174     * \brief Find an event source by the given id/name.
00175     *
00176     * \param app Application
00177     * \param id A unique identifier to check
00178     *
00179     * \return true if id is subscribed, false otherwise.
00180     */
00181    int (*is_subscribed)(struct stasis_app *app, const char *id);
00182 
00183    /*!
00184     * \brief Convert event source data to json
00185     *
00186     * \param app Application
00187     * \param id json object to fill
00188     */
00189    void (*to_json)(const struct stasis_app *app, struct ast_json *json);
00190 
00191    /*! Next item in the list */
00192    AST_LIST_ENTRY(stasis_app_event_source) next;
00193 };
00194 
00195 /*!
00196  * \brief Register an application event source.
00197  *
00198  * \param obj the event source to register
00199  */
00200 void stasis_app_register_event_source(struct stasis_app_event_source *obj);
00201 
00202 /*!
00203  * \brief Register core event sources.
00204  */
00205 void stasis_app_register_event_sources(void);
00206 
00207 /*!
00208  * \brief Checks to see if the given object is a core event source
00209  *
00210  * \note core event sources are currently only endpoint, bridge, and channel.
00211  *
00212  * \param obj event source object to check
00213  *
00214  * \return non-zero if core event source, otherwise 0 (false)
00215 
00216  */
00217 int stasis_app_is_core_event_source(struct stasis_app_event_source *obj);
00218 
00219 /*!
00220  * \brief Unregister an application event source.
00221  *
00222  * \param obj the event source to unregister
00223  */
00224 void stasis_app_unregister_event_source(struct stasis_app_event_source *obj);
00225 
00226 /*!
00227  * \brief Unregister core event sources.
00228  */
00229 void stasis_app_unregister_event_sources(void);
00230 
00231 /*! \brief Return code for stasis_app_user_event */
00232 enum stasis_app_user_event_res {
00233    STASIS_APP_USER_OK,
00234    STASIS_APP_USER_APP_NOT_FOUND,
00235    STASIS_APP_USER_EVENT_SOURCE_NOT_FOUND,
00236    STASIS_APP_USER_EVENT_SOURCE_BAD_SCHEME,
00237    STASIS_APP_USER_USEREVENT_INVALID,
00238    STASIS_APP_USER_INTERNAL_ERROR,
00239 };
00240 
00241 /*!
00242  * \brief Generate a Userevent for stasis app (echo to AMI)
00243  *
00244  * \param app_name Name of the application to generate event for/to.
00245  * \param event_name Name of the Userevent.
00246  * \param source_uris URIs for the source objects to attach to event.
00247  * \param sources_count Array size of source_uris.
00248  * \param json_variables event blob variables.
00249  *
00250  * \return \ref stasis_app_user_event_res return code.
00251  */
00252 enum stasis_app_user_event_res stasis_app_user_event(const char *app_name,
00253    const char *event_name,
00254    const char **source_uris, int sources_count,
00255    struct ast_json *json_variables);
00256 
00257 
00258 /*! \brief Return code for stasis_app_[un]subscribe */
00259 enum stasis_app_subscribe_res {
00260    STASIS_ASR_OK,
00261    STASIS_ASR_APP_NOT_FOUND,
00262    STASIS_ASR_EVENT_SOURCE_NOT_FOUND,
00263    STASIS_ASR_EVENT_SOURCE_BAD_SCHEME,
00264    STASIS_ASR_INTERNAL_ERROR,
00265 };
00266 
00267 /*!
00268  * \brief Subscribes an application to a list of event sources.
00269  *
00270  * \param app_name Name of the application to subscribe.
00271  * \param event_source_uris URIs for the event sources to subscribe to.
00272  * \param event_sources_count Array size of event_source_uris.
00273  * \param json Optional output pointer for JSON representation of the app
00274  *             after adding the subscription.
00275  *
00276  * \return \ref stasis_app_subscribe_res return code.
00277  *
00278  * \note Do not hold any channel locks if subscribing to a channel.
00279  */
00280 enum stasis_app_subscribe_res stasis_app_subscribe(const char *app_name,
00281    const char **event_source_uris, int event_sources_count,
00282    struct ast_json **json);
00283 
00284 /*!
00285  * \brief Unsubscribes an application from a list of event sources.
00286  *
00287  * \param app_name Name of the application to subscribe.
00288  * \param event_source_uris URIs for the event sources to subscribe to.
00289  * \param event_sources_count Array size of event_source_uris.
00290  * \param json Optional output pointer for JSON representation of the app
00291  *             after adding the subscription.
00292  *
00293  * \return \ref stasis_app_subscribe_res return code.
00294  */
00295 enum stasis_app_subscribe_res stasis_app_unsubscribe(const char *app_name,
00296    const char **event_source_uris, int event_sources_count,
00297    struct ast_json **json);
00298 
00299 /*!
00300  * \brief Directly subscribe an application to a channel
00301  *
00302  * \param app_name Name of the application to subscribe.
00303  * \param chan The channel to subscribe to
00304  *
00305  * \return \ref stasis_app_subscribe_res return code.
00306  *
00307  * \note This method can be used when you already hold a channel and its
00308  *       lock. This bypasses the channel lookup that would normally be
00309  *       performed by \ref stasis_app_subscribe.
00310  */
00311 enum stasis_app_subscribe_res stasis_app_subscribe_channel(const char *app_name,
00312    struct ast_channel *chan);
00313 
00314 /*! @} */
00315 
00316 /*! @{ */
00317 
00318 /*! \brief Handler for controlling a channel that's in a Stasis application */
00319 struct stasis_app_control;
00320 
00321 /*! \brief Rule to check to see if an operation is allowed */
00322 struct stasis_app_control_rule {
00323    /*!
00324     * \brief Checks to see if an operation is allowed on the control
00325     *
00326     * \param control Control object to check
00327     * \return 0 on success, otherwise a failure code
00328     */
00329    enum stasis_app_control_channel_result (*check_rule)(
00330       const struct stasis_app_control *control);
00331    /*! Next item in the list */
00332    AST_LIST_ENTRY(stasis_app_control_rule) next;
00333 };
00334 
00335 /*!
00336  * \brief Registers an add channel to bridge rule.
00337  *
00338  * \param control Control object
00339  * \param rule The rule to register
00340  */
00341 void stasis_app_control_register_add_rule(
00342    struct stasis_app_control *control,
00343    struct stasis_app_control_rule *rule);
00344 
00345 /*!
00346  * \brief UnRegister an add channel to bridge rule.
00347  *
00348  * \param control Control object
00349  * \param rule The rule to unregister
00350  */
00351 void stasis_app_control_unregister_add_rule(
00352    struct stasis_app_control *control,
00353    struct stasis_app_control_rule *rule);
00354 
00355 /*!
00356  * \brief Registers a remove channel from bridge rule.
00357  *
00358  * \param control Control object
00359  * \param rule The rule to register
00360  */
00361 void stasis_app_control_register_remove_rule(
00362    struct stasis_app_control *control,
00363    struct stasis_app_control_rule *rule);
00364 
00365 /*!
00366  * \brief Unregisters a remove channel from bridge rule.
00367  *
00368  * \param control Control object
00369  * \param rule The rule to unregister
00370  */
00371 void stasis_app_control_unregister_remove_rule(
00372    struct stasis_app_control *control,
00373    struct stasis_app_control_rule *rule);
00374 
00375 /*!
00376  * \brief Returns the handler for the given channel.
00377  * \param chan Channel to handle.
00378  *
00379  * \return NULL channel not in Stasis application.
00380  * \return Pointer to \c res_stasis handler.
00381  */
00382 struct stasis_app_control *stasis_app_control_find_by_channel(
00383    const struct ast_channel *chan);
00384 
00385 /*!
00386  * \brief Returns the handler for the channel with the given id.
00387  * \param channel_id Uniqueid of the channel.
00388  *
00389  * \return NULL channel not in Stasis application, or channel does not exist.
00390  * \return Pointer to \c res_stasis handler.
00391  */
00392 struct stasis_app_control *stasis_app_control_find_by_channel_id(
00393    const char *channel_id);
00394 
00395 /*!
00396  * \brief Creates a control handler for a channel that isn't in a stasis app.
00397  * \since 12.0.0
00398  *
00399  * \param chan Channel to create controller handle for
00400  *
00401  * \return NULL on failure to create the handle
00402  * \return Pointer to \c res_stasis handler.
00403  */
00404 struct stasis_app_control *stasis_app_control_create(
00405    struct ast_channel *chan);
00406 
00407 /*!
00408  * \brief Act on a stasis app control queue until it is empty
00409  * \since 12.0.0
00410  *
00411  * \param chan Channel to handle
00412  * \param control Control object to execute
00413  */
00414 void stasis_app_control_execute_until_exhausted(
00415    struct ast_channel *chan,
00416    struct stasis_app_control *control);
00417 
00418 /*!
00419  * \brief Check if a control is marked as done
00420  * \since 12.2.0
00421  *
00422  * \param control Which control object is being evaluated
00423  */
00424 int stasis_app_control_is_done(
00425    struct stasis_app_control *control);
00426 
00427 /*!
00428  * \brief Returns the uniqueid of the channel associated with this control
00429  *
00430  * \param control Control object.
00431  *
00432  * \return Uniqueid of the associate channel.
00433  * \return \c NULL if \a control is \c NULL.
00434  */
00435 const char *stasis_app_control_get_channel_id(
00436    const struct stasis_app_control *control);
00437 
00438 /*!
00439  * \brief Dial an endpoint and bridge it to a channel in \c res_stasis
00440  *
00441  * If the channel is no longer in \c res_stasis, this function does nothing.
00442  *
00443  * \param control Control for \c res_stasis
00444  * \param endpoint The endpoint to dial.
00445  * \param exten Extension to dial if no endpoint specified.
00446  * \param context Context to use with extension.
00447  * \param timeout The amount of time to wait for answer, before giving up.
00448  *
00449  * \return 0 for success
00450  * \return -1 for error.
00451  */
00452 int stasis_app_control_dial(struct stasis_app_control *control, const char *endpoint, const char *exten,
00453                             const char *context, int timeout);
00454 
00455 /*!
00456  * \brief Apply a bridge role to a channel controlled by a stasis app control
00457  *
00458  * \param control Control for \c res_stasis
00459  * \param role Role to apply
00460  *
00461  * \return 0 for success
00462  * \return -1 for error.
00463  */
00464 int stasis_app_control_add_role(struct stasis_app_control *control, const char *role);
00465 
00466 /*!
00467  * \brief Clear bridge roles currently applied to a channel controlled by a stasis app control
00468  *
00469  * \param control Control for \c res_stasis
00470  */
00471 void stasis_app_control_clear_roles(struct stasis_app_control *control);
00472 
00473 /*!
00474  * \brief Exit \c res_stasis and continue execution in the dialplan.
00475  *
00476  * If the channel is no longer in \c res_stasis, this function does nothing.
00477  *
00478  * \param control Control for \c res_stasis
00479  * \param context An optional context to continue to
00480  * \param extension An optional extension to continue to
00481  * \param priority An optional priority to continue to
00482  *
00483  * \return 0 for success
00484  * \return -1 for error.
00485  */
00486 int stasis_app_control_continue(struct stasis_app_control *control, const char *context, const char *extension, int priority);
00487 
00488 /*!
00489  * \brief Redirect a channel in \c res_stasis to a particular endpoint
00490  *
00491  * \param control Control for \c res_stasis
00492  * \param endpoint The endpoint transfer string where the channel should be sent to
00493  *
00494  * \return 0 for success
00495  * \return -1 for error
00496  */
00497 int stasis_app_control_redirect(struct stasis_app_control *control, const char *endpoint);
00498 
00499 /*!
00500  * \brief Indicate ringing to the channel associated with this control.
00501  *
00502  * \param control Control for \c res_stasis.
00503  *
00504  * \return 0 for success.
00505  * \return -1 for error.
00506  */
00507 int stasis_app_control_ring(struct stasis_app_control *control);
00508 
00509 /*!
00510  * \brief Stop locally generated ringing on the channel associated with this control.
00511  *
00512  * \param control Control for \c res_stasis.
00513  *
00514  * \return 0 for success.
00515  * \return -1 for error.
00516  */
00517 int stasis_app_control_ring_stop(struct stasis_app_control *control);
00518 
00519 /*!
00520  * \brief Send DTMF to the channel associated with this control.
00521  *
00522  * \param control Control for \c res_stasis.
00523  * \param dtmf DTMF string.
00524  * \param before Amount of time to wait before sending DTMF digits.
00525  * \param between Amount of time between each DTMF digit.
00526  * \param duration Amount of time each DTMF digit lasts for.
00527  * \param after Amount of time to wait after sending DTMF digits.
00528  *
00529  * \return 0 for success.
00530  * \return -1 for error.
00531  */
00532 int stasis_app_control_dtmf(struct stasis_app_control *control, const char *dtmf, int before, int between, unsigned int duration, int after);
00533 
00534 /*!
00535  * \brief Mute the channel associated with this control.
00536  *
00537  * \param control Control for \c res_stasis.
00538  * \param direction The direction in which the audio should be muted.
00539  * \param frametype The type of stream that should be muted.
00540  *
00541  * \return 0 for success
00542  * \return -1 for error.
00543  */
00544 int stasis_app_control_mute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
00545 
00546 /*!
00547  * \brief Unmute the channel associated with this control.
00548  *
00549  * \param control Control for \c res_stasis.
00550  * \param direction The direction in which the audio should be unmuted.
00551  * \param frametype The type of stream that should be unmuted.
00552  *
00553  * \return 0 for success
00554  * \return -1 for error.
00555  */
00556 int stasis_app_control_unmute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
00557 
00558 /*!
00559  * \brief Answer the channel associated with this control.
00560  * \param control Control for \c res_stasis.
00561  * \return 0 for success.
00562  * \return Non-zero for error.
00563  */
00564 int stasis_app_control_answer(struct stasis_app_control *control);
00565 
00566 /*!
00567  * \brief Set a variable on the channel associated with this control to value.
00568  * \param control Control for \c res_stasis.
00569  * \param variable The name of the variable
00570  * \param value The value to set the variable to
00571  *
00572  * \return 0 for success.
00573  * \return -1 for error.
00574  */
00575 int stasis_app_control_set_channel_var(struct stasis_app_control *control, const char *variable, const char *value);
00576 
00577 /*!
00578  * \brief Place the channel associated with the control on hold.
00579  * \param control Control for \c res_stasis.
00580  */
00581 void stasis_app_control_hold(struct stasis_app_control *control);
00582 
00583 /*!
00584  * \brief Remove the channel associated with the control from hold.
00585  * \param control Control for \c res_stasis.
00586  */
00587 void stasis_app_control_unhold(struct stasis_app_control *control);
00588 
00589 /*!
00590  * \brief Play music on hold to a channel (does not affect hold status)
00591  * \param control Control for \c res_stasis.
00592  * \param moh_class class of music on hold to play (NULL allowed)
00593  */
00594 void stasis_app_control_moh_start(struct stasis_app_control *control, const char *moh_class);
00595 
00596 /*!
00597  * \brief Stop playing music on hold to a channel (does not affect hold status)
00598  * \param control Control for \c res_stasis.
00599  */
00600 void stasis_app_control_moh_stop(struct stasis_app_control *control);
00601 
00602 /*!
00603  * \brief Start playing silence to a channel.
00604  * \param control Control for \c res_stasis.
00605  */
00606 void stasis_app_control_silence_start(struct stasis_app_control *control);
00607 
00608 /*!
00609  * \brief Stop playing silence to a channel.
00610  * \param control Control for \c res_stasis.
00611  */
00612 void stasis_app_control_silence_stop(struct stasis_app_control *control);
00613 
00614 /*!
00615  * \brief Returns the most recent snapshot for the associated channel.
00616  *
00617  * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
00618  *
00619  * \param control Control for \c res_stasis.
00620  *
00621  * \return Most recent snapshot. ao2_cleanup() when done.
00622  * \return \c NULL if channel isn't in cache.
00623  */
00624 struct ast_channel_snapshot *stasis_app_control_get_snapshot(
00625    const struct stasis_app_control *control);
00626 
00627 /*!
00628  * \brief Publish a message to the \a control's channel's topic.
00629  *
00630  * \param control Control to publish to
00631  * \param message Message to publish
00632  */
00633 void stasis_app_control_publish(
00634    struct stasis_app_control *control, struct stasis_message *message);
00635 
00636 /*!
00637  * \brief Returns the stasis topic for an app
00638  *
00639  * \param app Stasis app to get topic of
00640  */
00641 struct stasis_topic *ast_app_get_topic(struct stasis_app *app);
00642 
00643 /*!
00644  * \brief Queue a control frame without payload.
00645  *
00646  * \param control Control to publish to.
00647  * \param frame_type type of control frame.
00648  *
00649  * \return zero on success
00650  * \return non-zero on failure
00651  */
00652 int stasis_app_control_queue_control(struct stasis_app_control *control,
00653    enum ast_control_frame_type frame_type);
00654 
00655 /*!
00656  * \brief Create a bridge of the specified type.
00657  *
00658  * \param type The type of bridge to be created
00659  * \param name Optional name to give to the bridge
00660  * \param id Optional Unique ID to give to the bridge
00661  *
00662  * \return New bridge.
00663  * \return \c NULL on error.
00664  */
00665 struct ast_bridge *stasis_app_bridge_create(const char *type, const char *name, const char *id);
00666 
00667 /*!
00668  * \brief Returns the bridge with the given id.
00669  * \param bridge_id Uniqueid of the bridge.
00670  *
00671  * \return NULL bridge not created by a Stasis application, or bridge does not exist.
00672  * \return Pointer to bridge.
00673  */
00674 struct ast_bridge *stasis_app_bridge_find_by_id(
00675    const char *bridge_id);
00676 
00677 /*!
00678  * \brief Finds or creates an announcer channel in a bridge that can play music on hold.
00679  *
00680  * \param bridge Bridge we want an MOH channel for
00681  *
00682  * \return NULL if the music on hold channel fails to be created or join the bridge for any reason.
00683  * \return Pointer to the ;1 end of the announcer channel chain.
00684  */
00685 struct ast_channel *stasis_app_bridge_moh_channel(
00686    struct ast_bridge *bridge);
00687 
00688 /*!
00689  * \brief Breaks down MOH channels playing on the bridge created by stasis_app_bridge_moh_channel
00690  *
00691  * \param bridge Bridge we want to stop the MOH on
00692  *
00693  * \return -1 if no moh channel could be found and stopped
00694  * \return 0 on success
00695  */
00696 int stasis_app_bridge_moh_stop(
00697    struct ast_bridge *bridge);
00698 
00699 /*!
00700  * \brief Finds an existing ARI playback channel in a bridge
00701  *
00702  * \param bridge Bridge we want to find the playback channel for
00703  *
00704  * \return NULL if the playback channel can not be found for any reason.
00705  * \return Pointer to the ;1 end of the playback channel chain.
00706  */
00707 struct ast_channel *stasis_app_bridge_playback_channel_find(
00708    struct ast_bridge *bridge);
00709 
00710 /*!
00711  * \brief Adds a channel to the list of ARI playback channels for bridges.
00712  *
00713  * \param bridge Bridge we are adding the playback channel for
00714  * \param chan Channel being added as a playback channel (must be ;1)
00715  *
00716  * \retval -1 failed to add channel for any reason
00717  * \retval 0 on success
00718  */
00719 int stasis_app_bridge_playback_channel_add(struct ast_bridge *bridge,
00720    struct ast_channel *chan,
00721    struct stasis_app_control *control);
00722 
00723 /*!
00724  * \brief Result codes used when adding/removing channels to/from bridges.
00725  */
00726 enum stasis_app_control_channel_result {
00727    /*! The channel is okay to be added/removed */
00728    STASIS_APP_CHANNEL_OKAY = 0,
00729    /*! The channel is currently recording */
00730    STASIS_APP_CHANNEL_RECORDING
00731 };
00732 
00733 /*!
00734  * \brief Add a channel to the bridge.
00735  *
00736  * \param control Control whose channel should be added to the bridge
00737  * \param bridge Pointer to the bridge
00738  *
00739  * \return non-zero on failure
00740  * \return zero on success
00741  */
00742 int stasis_app_control_add_channel_to_bridge(
00743    struct stasis_app_control *control, struct ast_bridge *bridge);
00744 
00745 /*!
00746  * \brief Remove a channel from the bridge.
00747  *
00748  * \param control Control whose channel should be removed from the bridge
00749  * \param bridge Pointer to the bridge
00750  *
00751  * \return non-zero on failure
00752  * \return zero on success
00753  */
00754 int stasis_app_control_remove_channel_from_bridge(
00755    struct stasis_app_control *control, struct ast_bridge *bridge);
00756 
00757 /*!
00758  * \since 12
00759  * \brief Gets the bridge currently associated with a control object.
00760  *
00761  * \note If the bridge returned by this function is to be held for any
00762  *       length of time, its refcount should be incremented until the
00763  *       caller is finished with it.
00764  *
00765  * \param control Control object for the channel to query.
00766  *
00767  * \return Associated \ref ast_bridge.
00768  * \return \c NULL if not associated with a bridge.
00769  */
00770 struct ast_bridge *stasis_app_get_bridge(struct stasis_app_control *control);
00771 
00772 /*!
00773  * \brief Destroy the bridge.
00774  *
00775  * \param bridge_id Uniqueid of bridge to be destroyed
00776  *
00777  * \retval non-zero on failure
00778  * \retval zero on success
00779  */
00780 void stasis_app_bridge_destroy(const char *bridge_id);
00781 
00782 /*!
00783  * \brief Increment the res_stasis reference count.
00784  *
00785  * This ensures graceful shutdown happens in the proper order.
00786  */
00787 void stasis_app_ref(void);
00788 
00789 /*!
00790  * \brief Decrement the res_stasis reference count.
00791  *
00792  * This ensures graceful shutdown happens in the proper order.
00793  */
00794 void stasis_app_unref(void);
00795 
00796 /*!
00797  * \brief Get the Stasis message sanitizer for app_stasis applications
00798  *
00799  * \retval The stasis message sanitizer
00800  */
00801 struct stasis_message_sanitizer *stasis_app_get_sanitizer(void);
00802 
00803 /*!
00804  * \brief Indicate that this channel has had a StasisEnd published for it
00805  *
00806  * \param The channel that is exiting Stasis.
00807  */
00808 void stasis_app_channel_set_stasis_end_published(struct ast_channel *chan);
00809 
00810 /*!
00811  * \brief Has this channel had a StasisEnd published on it?
00812  *
00813  * \param chan The channel upon which the query rests.
00814  *
00815  * \retval 0 No
00816  * \retval 1 Yes
00817  */
00818 int stasis_app_channel_is_stasis_end_published(struct ast_channel *chan);
00819 
00820 /*!
00821  * \brief Is this channel internal to Stasis?
00822  *
00823  * \param chan The channel to check.
00824  *
00825  * \retval 0 No
00826  * \retval 1 Yes
00827  */
00828 int stasis_app_channel_is_internal(struct ast_channel *chan);
00829 
00830 /*!
00831  * \brief Mark this unreal channel and it's other half as being internal to Stasis.
00832  *
00833  * \param chan The channel to mark.
00834  *
00835  * \retval zero Success
00836  * \retval non-zero Failure
00837  */
00838 int stasis_app_channel_unreal_set_internal(struct ast_channel *chan);
00839 
00840 /*!
00841  * \brief Mark this channel as being internal to Stasis.
00842  *
00843  * \param chan The channel to mark.
00844  *
00845  * \retval zero Success
00846  * \retval non-zero Failure
00847  */
00848 int stasis_app_channel_set_internal(struct ast_channel *chan);
00849 
00850 /*! @} */
00851 
00852 #endif /* _ASTERISK_STASIS_APP_H */

Generated on Thu Apr 16 06:27:56 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6