include/asterisk/stasis_app.h

   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 call stasis_app_ref() when loaded,
  50  * and stasis_app_unref() when unloaded.
  51  */
  52
  53 #include "asterisk/channel.h"
  54 #include "asterisk/json.h"
  55
  56 /*! @{ */
  57
  58 /*!
  59  * \brief Callback for Stasis application handler.
  60  *
  61  * The message given to the handler is a borrowed copy. If you want to keep a
  62  * reference to it, you should use \c ao2_ref() to keep it around.
  63  *
  64  * \param data Data ptr given when registered.
  65  * \param app_name Name of the application being dispatched to.
  66  * \param message Message to handle. (borrowed copy)
  67  */
  68 typedef void (*stasis_app_cb)(void *data, const char *app_name,
  69         struct ast_json *message);
  70
  71 /*!
  72  * \brief Register a new Stasis application.
  73  *
  74  * If an application is already registered with the given name, the old
  75  * application is sent a 'replaced' message and unregistered.
  76  *
  77  * \param app_name Name of this application.
  78  * \param handler Callback for application messages.
  79  * \param data Data blob to pass to the callback. Must be AO2 managed.
  80  * \return 0 for success
  81  * \return -1 for error.
  82  */
  83 int stasis_app_register(const char *app_name, stasis_app_cb handler, void *data);
  84
  85 /*!
  86  * \brief Unregister a Stasis application.
  87  * \param app_name Name of the application to unregister.
  88  */
  89 void stasis_app_unregister(const char *app_name);
  90
  91 /*!
  92  * \brief Send a message to the given Stasis application.
  93  *
  94  * The message given to the handler is a borrowed copy. If you want to keep a
  95  * reference to it, you should use \c ao2_ref() to keep it around.
  96  *
  97  * \param app_name Name of the application to invoke.
  98  * \param message Message to send (borrowed reference)
  99  * \return 0 for success.
 100  * \return -1 for error.
 101  */
 102 int stasis_app_send(const char *app_name, struct ast_json *message);
 103
 104 /*! @} */
 105
 106 /*! @{ */
 107
 108 /*! \brief Handler for controlling a channel that's in a Stasis application */
 109 struct stasis_app_control;
 110
 111 /*!
 112  * \brief Returns the handler for the given channel.
 113  * \param chan Channel to handle.
 114  * \return NULL channel not in Stasis application.
 115  * \return Pointer to \c res_stasis handler.
 116  */
 117 struct stasis_app_control *stasis_app_control_find_by_channel(
 118         const struct ast_channel *chan);
 119
 120 /*!
 121  * \brief Returns the handler for the channel with the given id.
 122  * \param channel_id Uniqueid of the channel.
 123  * \return NULL channel not in Stasis application, or channel does not exist.
 124  * \return Pointer to \c res_stasis handler.
 125  */
 126 struct stasis_app_control *stasis_app_control_find_by_channel_id(
 127         const char *channel_id);
 128
 129 /*!
 130  * \brief Creates a control handler for a channel that isn't in a stasis app.
 131  * \since 12.0.0
 132  *
 133  * \param chan Channel to create controller handle for
 134  *
 135  * \return NULL on failure to create the handle
 136  * \return Pointer to \c res_stasis handler.
 137  */
 138 struct stasis_app_control *stasis_app_control_create(
 139         struct ast_channel *chan);
 140
 141 /*!
 142  * \brief Act on a stasis app control queue until it is empty
 143  * \since 12.0.0
 144  *
 145  * \param chan Channel to handle
 146  * \param control Control object to execute
 147  */
 148 void stasis_app_control_execute_until_exhausted(
 149         struct ast_channel *chan,
 150         struct stasis_app_control *control);
 151
 152 /*!
 153  * \brief Returns the uniqueid of the channel associated with this control
 154  *
 155  * \param control Control object.
 156  * \return Uniqueid of the associate channel.
 157  * \return \c NULL if \a control is \c NULL.
 158  */
 159 const char *stasis_app_control_get_channel_id(
 160         const struct stasis_app_control *control);
 161
 162 /*!
 163  * \brief Dial an endpoint and bridge it to a channel in \c res_stasis
 164  *
 165  * If the channel is no longer in \c res_stasis, this function does nothing.
 166  *
 167  * \param control Control for \c res_stasis
 168  * \param endpoint The endpoint to dial.
 169  * \param timeout The amount of time to wait for answer, before giving up.
 170  *
 171  * \return 0 for success
 172  * \return -1 for error.
 173  */
 174 int stasis_app_control_dial(struct stasis_app_control *control, const char *endpoint, int timeout);
 175
 176 /*!
 177  * \brief Exit \c res_stasis and continue execution in the dialplan.
 178  *
 179  * If the channel is no longer in \c res_stasis, this function does nothing.
 180  *
 181  * \param control Control for \c res_stasis
 182  * \param context An optional context to continue to
 183  * \param extension An optional extension to continue to
 184  * \param priority An optional priority to continue to
 185  *
 186  * \return 0 for success
 187  * \return -1 for error.
 188  */
 189 int stasis_app_control_continue(struct stasis_app_control *control, const char *context, const char *extension, int priority);
 190
 191 /*!
 192  * \brief Mute the channel associated with this control.
 193  *
 194  * \param control Control for \c res_stasis.
 195  * \param direction The direction in which the audio should be muted.
 196  * \param frametype The type of stream that should be muted.
 197  *
 198  * \return 0 for success
 199  * \return -1 for error.
 200  */
 201 int stasis_app_control_mute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
 202
 203 /*!
 204  * \brief Unmute the channel associated with this control.
 205  *
 206  * \param control Control for \c res_stasis.
 207  * \param direction The direction in which the audio should be unmuted.
 208  * \param frametype The type of stream that should be unmuted.
 209  *
 210  * \return 0 for success
 211  * \return -1 for error.
 212  */
 213 int stasis_app_control_unmute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
 214
 215 /*!
 216  * \brief Answer the channel associated with this control.
 217  * \param control Control for \c res_stasis.
 218  * \return 0 for success.
 219  * \return Non-zero for error.
 220  */
 221 int stasis_app_control_answer(struct stasis_app_control *control);
 222
 223 /*!
 224  * \brief Get the value of a variable on the channel associated with this control.
 225  * \param control Control for \c res_stasis.
 226  * \param variable The name of the variable.
 227  * \return The value of the variable.  The returned variable must be freed.
 228  */
 229 char *stasis_app_control_get_channel_var(struct stasis_app_control *control, const char *variable);
 230
 231 /*!
 232  * \brief Set a variable on the channel associated with this control to value.
 233  * \param control Control for \c res_stasis.
 234  * \param variable The name of the variable
 235  * \param value The value to set the variable to
 236  *
 237  * \return 0 for success.
 238  * \return -1 for error.
 239  */
 240 int stasis_app_control_set_channel_var(struct stasis_app_control *control, const char *variable, const char *value);
 241
 242 /*!
 243  * \brief Place the channel associated with the control on hold.
 244  * \param control Control for \c res_stasis.
 245  */
 246 void stasis_app_control_hold(struct stasis_app_control *control);
 247
 248 /*!
 249  * \brief Remove the channel associated with the control from hold.
 250  * \param control Control for \c res_stasis.
 251  */
 252 void stasis_app_control_unhold(struct stasis_app_control *control);
 253
 254 /*!
 255  * \brief Play music on hold to a channel (does not affect hold status)
 256  * \param control Control for \c res_stasis.
 257  * \param moh_class class of music on hold to play (NULL allowed)
 258  */
 259 void stasis_app_control_moh_start(struct stasis_app_control *control, const char *moh_class);
 260
 261 /*!
 262  * \brief Stop playing music on hold to a channel (does not affect hold status)
 263  * \param control Control for \c res_stasis.
 264  */
 265 void stasis_app_control_moh_stop(struct stasis_app_control *control);
 266
 267 /*!
 268  * \brief Returns the most recent snapshot for the associated channel.
 269  *
 270  * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
 271  *
 272  * \param control Control for \c res_stasis.
 273  * \return Most recent snapshot. ao2_cleanup() when done.
 274  * \return \c NULL if channel isn't in cache.
 275  */
 276 struct ast_channel_snapshot *stasis_app_control_get_snapshot(
 277         const struct stasis_app_control *control);
 278
 279 /*!
 280  * \brief Publish a message to the \a control's channel's topic.
 281  *
 282  * \param control Control to publish to
 283  * \param message Message to publish
 284  */
 285 void stasis_app_control_publish(
 286         struct stasis_app_control *control, struct stasis_message *message);
 287
 288 /*!
 289  * \brief Queue a control frame without payload.
 290  *
 291  * \param control Control to publish to.
 292  * \param frame_type type of control frame.
 293  *
 294  * \return zero on success
 295  * \return non-zero on failure
 296  */
 297 int stasis_app_control_queue_control(struct stasis_app_control *control,
 298         enum ast_control_frame_type frame_type);
 299
 300 /*!
 301  * \brief Create a bridge of the specified type.
 302  *
 303  * \param type The type of bridge to be created
 304  *
 305  * \return New bridge.
 306  * \return \c NULL on error.
 307  */
 308 struct ast_bridge *stasis_app_bridge_create(const char *type);
 309
 310 /*!
 311  * \brief Returns the bridge with the given id.
 312  * \param bridge_id Uniqueid of the bridge.
 313  * \return NULL bridge not created by a Stasis application, or bridge does not exist.
 314  * \return Pointer to bridge.
 315  */
 316 struct ast_bridge *stasis_app_bridge_find_by_id(
 317         const char *bridge_id);
 318
 319 /*!
 320  * \brief Add a channel to the bridge.
 321  *
 322  * \param control Control whose channel should be added to the bridge
 323  * \param bridge Pointer to the bridge
 324  */
 325 void stasis_app_control_add_channel_to_bridge(
 326         struct stasis_app_control *control, struct ast_bridge *bridge);
 327
 328 /*!
 329  * \brief Remove a channel from the bridge.
 330  *
 331  * \param control Control whose channel should be removed from the bridge
 332  * \param bridge Pointer to the bridge
 333  *
 334  * \retval non-zero on failure
 335  * \retval zero on success
 336  */
 337 int stasis_app_control_remove_channel_from_bridge(
 338         struct stasis_app_control *control, struct ast_bridge *bridge);
 339
 340 /*!
 341  * \brief Destroy the bridge.
 342  *
 343  * \param bridge_id Uniqueid of bridge to be destroyed
 344  *
 345  * \retval non-zero on failure
 346  * \retval zero on success
 347  */
 348 void stasis_app_bridge_destroy(const char *bridge_id);
 349
 350 /*!
 351  * \brief Increment the res_stasis reference count.
 352  *
 353  * This ensures graceful shutdown happens in the proper order.
 354  */
 355 void stasis_app_ref(void);
 356
 357 /*!
 358  * \brief Decrement the res_stasis reference count.
 359  *
 360  * This ensures graceful shutdown happens in the proper order.
 361  */
 362 void stasis_app_unref(void);
 363
 364 /*! @} */
 365
 366 #endif /* _ASTERISK_STASIS_APP_H */