res/stasis/app.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 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_RES_STASIS_APP_H
00020 #define _ASTERISK_RES_STASIS_APP_H
00021 
00022 /*! \file
00023  *
00024  * \brief Internal API for the Stasis application controller.
00025  *
00026  * \author David M. Lee, II <dlee@digium.com>
00027  * \since 12
00028  */
00029 
00030 #include "asterisk/channel.h"
00031 #include "asterisk/stasis.h"
00032 #include "asterisk/stasis_app.h"
00033 
00034 /*!
00035  * \brief Opaque pointer to \c res_stasis app structure.
00036  */
00037 struct stasis_app;
00038 
00039 /*!
00040  * \brief Create a res_stasis application.
00041  *
00042  * \param name Name of the application.
00043  * \param handler Callback for messages sent to the application.
00044  * \param data Data pointer provided to the callback.
00045  * \return New \c res_stasis application.
00046  * \return \c NULL on error.
00047  */
00048 struct stasis_app *app_create(const char *name, stasis_app_cb handler, void *data);
00049 
00050 /*!
00051  * \brief Tears down an application.
00052  *
00053  * It should be finished before calling this.
00054  *
00055  * \param app Application to unsubscribe.
00056  */
00057 void app_shutdown(struct stasis_app *app);
00058 
00059 /*!
00060  * \brief Deactivates an application.
00061  *
00062  * Any channels currently in the application remain active (since the app might
00063  * come back), but new channels are rejected.
00064  *
00065  * \param app Application to deactivate.
00066  */
00067 void app_deactivate(struct stasis_app *app);
00068 
00069 /*!
00070  * \brief Checks whether an app is active.
00071  *
00072  * \param app Application to check.
00073  * \return True (non-zero) if app is active.
00074  * \return False (zero) if app has been deactivated.
00075  */
00076 int app_is_active(struct stasis_app *app);
00077 
00078 /*!
00079  * \brief Checks whether a deactivated app has no channels.
00080  *
00081  * \param app Application to check.
00082  * \param True (non-zero) if app is deactivated, and has no associated channels.
00083  * \param False (zero) otherwise.
00084  */
00085 int app_is_finished(struct stasis_app *app);
00086 
00087 /*!
00088  * \brief Update the handler and data for a \c res_stasis application.
00089  *
00090  * If app has been deactivated, this will reactivate it.
00091  *
00092  * \param app Application to update.
00093  * \param handler New application callback.
00094  * \param data New data pointer for the callback.
00095  */
00096 void app_update(struct stasis_app *app, stasis_app_cb handler, void *data);
00097 
00098 /*!
00099  * \brief Return an application's name.
00100  *
00101  * \param app Application.
00102  * \return Name of the application.
00103  * \return \c NULL is \a app is \c NULL.
00104  */
00105 const char *app_name(const struct stasis_app *app);
00106 
00107 /*!
00108  * \brief Send a message to an application.
00109  *
00110  * \param app Application.
00111  * \param message Message to send.
00112  */
00113 void app_send(struct stasis_app *app, struct ast_json *message);
00114 
00115 struct app_forwards;
00116 
00117 struct ast_json *app_to_json(const struct stasis_app *app);
00118 
00119 /*!
00120  * \brief Subscribes an application to a channel.
00121  *
00122  * \param app Application.
00123  * \param chan Channel to subscribe to.
00124  * \return 0 on success.
00125  * \return Non-zero on error.
00126  */
00127 int app_subscribe_channel(struct stasis_app *app, struct ast_channel *chan);
00128 
00129 /*!
00130  * \brief Cancel the subscription an app has for a channel.
00131  *
00132  * \param app Subscribing application.
00133  * \param chan Channel to unsubscribe from.
00134  * \return 0 on success.
00135  * \return Non-zero on error.
00136  */
00137 int app_unsubscribe_channel(struct stasis_app *app, struct ast_channel *chan);
00138 
00139 /*!
00140  * \brief Cancel the subscription an app has for a channel.
00141  *
00142  * \param app Subscribing application.
00143  * \param channel_id Id of channel to unsubscribe from.
00144  * \return 0 on success.
00145  * \return Non-zero on error.
00146  */
00147 int app_unsubscribe_channel_id(struct stasis_app *app, const char *channel_id);
00148 
00149 /*!
00150  * \brief Test if an app is subscribed to a channel.
00151  *
00152  * \param app Subscribing application.
00153  * \param channel_id Id of channel to check.
00154  * \return True (non-zero) if channel is subscribed to \a app.
00155  * \return False (zero) if channel is not subscribed.
00156  */
00157 int app_is_subscribed_channel_id(struct stasis_app *app, const char *channel_id);
00158 
00159 /*!
00160  * \brief Add a bridge subscription to an existing channel subscription.
00161  *
00162  * \param app Application.
00163  * \param bridge Bridge to subscribe to.
00164  * \return 0 on success.
00165  * \return Non-zero on error.
00166  */
00167 int app_subscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge);
00168 
00169 /*!
00170  * \brief Cancel the bridge subscription for an application.
00171  *
00172  * \param forwards Return from app_subscribe_channel().
00173  * \param bridge Bridge to subscribe to.
00174  * \return 0 on success.
00175  * \return Non-zero on error.
00176  */
00177 int app_unsubscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge);
00178 
00179 /*!
00180  * \brief Cancel the subscription an app has for a bridge.
00181  *
00182  * \param app Subscribing application.
00183  * \param bridge_id Id of bridge to unsubscribe from.
00184  * \return 0 on success.
00185  * \return Non-zero on error.
00186  */
00187 int app_unsubscribe_bridge_id(struct stasis_app *app, const char *bridge_id);
00188 
00189 /*!
00190  * \brief Test if an app is subscribed to a bridge.
00191  *
00192  * \param app Subscribing application.
00193  * \param bridge_id Id of bridge to check.
00194  * \return True (non-zero) if bridge is subscribed to \a app.
00195  * \return False (zero) if bridge is not subscribed.
00196  */
00197 int app_is_subscribed_bridge_id(struct stasis_app *app, const char *bridge_id);
00198 
00199 /*!
00200  * \brief Subscribes an application to a endpoint.
00201  *
00202  * \param app Application.
00203  * \param chan Endpoint to subscribe to.
00204  * \return 0 on success.
00205  * \return Non-zero on error.
00206  */
00207 int app_subscribe_endpoint(struct stasis_app *app, struct ast_endpoint *endpoint);
00208 
00209 /*!
00210  * \brief Cancel the subscription an app has for a endpoint.
00211  *
00212  * \param app Subscribing application.
00213  * \param endpoint_id Id of endpoint to unsubscribe from.
00214  * \return 0 on success.
00215  * \return Non-zero on error.
00216  */
00217 int app_unsubscribe_endpoint_id(struct stasis_app *app, const char *endpoint_id);
00218 
00219 /*!
00220  * \brief Test if an app is subscribed to a endpoint.
00221  *
00222  * \param app Subscribing application.
00223  * \param endpoint_id Id of endpoint to check.
00224  * \return True (non-zero) if endpoint is subscribed to \a app.
00225  * \return False (zero) if endpoint is not subscribed.
00226  */
00227 int app_is_subscribed_endpoint_id(struct stasis_app *app, const char *endpoint_id);
00228 
00229 /*!
00230  * \brief Set the snapshot of the channel that this channel will replace
00231  *
00232  * \param channel The channel on which this will be set
00233  * \param replace_snapshot The snapshot of the channel that is being replaced
00234  *
00235  * \retval zero success
00236  * \retval non-zero failure
00237  */
00238 int app_set_replace_channel_snapshot(struct ast_channel *chan, struct ast_channel_snapshot *replace_snapshot);
00239 
00240 /*!
00241  * \brief Set the app that the replacement channel will be controlled by
00242  *
00243  * \param channel The channel on which this will be set
00244  * \param replace_app The app that will be controlling this channel
00245  *
00246  * \retval zero success
00247  * \retval non-zero failure
00248  */
00249 int app_set_replace_channel_app(struct ast_channel *chan, const char *replace_app);
00250 
00251 /*!
00252  * \brief Get the app that the replacement channel will be controlled by
00253  *
00254  * \param channel The channel on which this will be set
00255  *
00256  * \retval NULL on error
00257  * \return the name of the controlling app (must be ast_free()d)
00258  */
00259 char *app_get_replace_channel_app(struct ast_channel *chan);
00260 
00261 /*!
00262  * \brief Send StasisEnd message to the listening app
00263  *
00264  * \param app The app that owns the channel
00265  * \param chan The channel for which the message is being sent
00266  *
00267  * \retval zero on success
00268  * \return non-zero on failure
00269  */
00270 int app_send_end_msg(struct stasis_app *app, struct ast_channel *chan);
00271 
00272 #endif /* _ASTERISK_RES_STASIS_APP_H */

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