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 Gets the names of all registered Stasis applications.
  73  *
  74  * \return \c ast_str_container of container names.
  75  * \return \c NULL on error.
  76  */
  77 struct ao2_container *stasis_app_get_all(void);
  78
  79 /*!
  80  * \brief Register a new Stasis application.
  81  *
  82  * If an application is already registered with the given name, the old
  83  * application is sent a 'replaced' message and unregistered.
  84  *
  85  * \param app_name Name of this application.
  86  * \param handler Callback for application messages.
  87  * \param data Data blob to pass to the callback. Must be AO2 managed.
  88  *
  89  * \return 0 for success
  90  * \return -1 for error.
  91  */
  92 int stasis_app_register(const char *app_name, stasis_app_cb handler, void *data);
  93
  94 /*!
  95  * \brief Unregister a Stasis application.
  96  * \param app_name Name of the application to unregister.
  97  */
  98 void stasis_app_unregister(const char *app_name);
  99
 100 /*!
 101  * \brief Send a message to the given Stasis application.
 102  *
 103  * The message given to the handler is a borrowed copy. If you want to keep a
 104  * reference to it, you should use \c ao2_ref() to keep it around.
 105  *
 106  * \param app_name Name of the application to invoke.
 107  * \param message Message to send (borrowed reference)
 108  *
 109  * \return 0 for success.
 110  * \return -1 for error.
 111  */
 112 int stasis_app_send(const char *app_name, struct ast_json *message);
 113
 114 /*!
 115  * \brief Return the JSON representation of a Stasis application.
 116  *
 117  * \param app_name Name of the application.
 118  *
 119  * \return JSON representation of app with given name.
 120  * \return \c NULL on error.
 121  */
 122 struct ast_json *stasis_app_to_json(const char *app_name);
 123
 124 /*! \brief Return code for stasis_app_[un]subscribe */
 125 enum stasis_app_subscribe_res {
 126         STASIS_ASR_OK,
 127         STASIS_ASR_APP_NOT_FOUND,
 128         STASIS_ASR_EVENT_SOURCE_NOT_FOUND,
 129         STASIS_ASR_EVENT_SOURCE_BAD_SCHEME,
 130         STASIS_ASR_INTERNAL_ERROR,
 131 };
 132
 133 /*!
 134  * \brief Subscribes an application to a list of event sources.
 135  *
 136  * \param app_name Name of the application to subscribe.
 137  * \param event_source_uris URIs for the event sources to subscribe to.
 138  * \param event_sources_count Array size of event_source_uris.
 139  * \param json Optional output pointer for JSON representation of the app
 140  *             after adding the subscription.
 141  *
 142  * \return \ref stasis_app_subscribe_res return code.
 143  *
 144  * \note Do not hold any channel locks if subscribing to a channel.
 145  */
 146 enum stasis_app_subscribe_res stasis_app_subscribe(const char *app_name,
 147         const char **event_source_uris, int event_sources_count,
 148         struct ast_json **json);
 149
 150 /*!
 151  * \brief Unsubscribes an application from a list of event sources.
 152  *
 153  * \param app_name Name of the application to subscribe.
 154  * \param event_source_uris URIs for the event sources to subscribe to.
 155  * \param event_sources_count Array size of event_source_uris.
 156  * \param json Optional output pointer for JSON representation of the app
 157  *             after adding the subscription.
 158  *
 159  * \return \ref stasis_app_subscribe_res return code.
 160  */
 161 enum stasis_app_subscribe_res stasis_app_unsubscribe(const char *app_name,
 162         const char **event_source_uris, int event_sources_count,
 163         struct ast_json **json);
 164
 165 /*! @} */
 166
 167 /*! @{ */
 168
 169 /*! \brief Handler for controlling a channel that's in a Stasis application */
 170 struct stasis_app_control;
 171
 172 /*!
 173  * \brief Returns the handler for the given channel.
 174  * \param chan Channel to handle.
 175  *
 176  * \return NULL channel not in Stasis application.
 177  * \return Pointer to \c res_stasis handler.
 178  */
 179 struct stasis_app_control *stasis_app_control_find_by_channel(
 180         const struct ast_channel *chan);
 181
 182 /*!
 183  * \brief Returns the handler for the channel with the given id.
 184  * \param channel_id Uniqueid of the channel.
 185  *
 186  * \return NULL channel not in Stasis application, or channel does not exist.
 187  * \return Pointer to \c res_stasis handler.
 188  */
 189 struct stasis_app_control *stasis_app_control_find_by_channel_id(
 190         const char *channel_id);
 191
 192 /*!
 193  * \brief Creates a control handler for a channel that isn't in a stasis app.
 194  * \since 12.0.0
 195  *
 196  * \param chan Channel to create controller handle for
 197  *
 198  * \return NULL on failure to create the handle
 199  * \return Pointer to \c res_stasis handler.
 200  */
 201 struct stasis_app_control *stasis_app_control_create(
 202         struct ast_channel *chan);
 203
 204 /*!
 205  * \brief Act on a stasis app control queue until it is empty
 206  * \since 12.0.0
 207  *
 208  * \param chan Channel to handle
 209  * \param control Control object to execute
 210  */
 211 void stasis_app_control_execute_until_exhausted(
 212         struct ast_channel *chan,
 213         struct stasis_app_control *control);
 214
 215 /*!
 216  * \brief Returns the uniqueid of the channel associated with this control
 217  *
 218  * \param control Control object.
 219  *
 220  * \return Uniqueid of the associate channel.
 221  * \return \c NULL if \a control is \c NULL.
 222  */
 223 const char *stasis_app_control_get_channel_id(
 224         const struct stasis_app_control *control);
 225
 226 /*!
 227  * \brief Dial an endpoint and bridge it to a channel in \c res_stasis
 228  *
 229  * If the channel is no longer in \c res_stasis, this function does nothing.
 230  *
 231  * \param control Control for \c res_stasis
 232  * \param endpoint The endpoint to dial.
 233  * \param exten Extension to dial if no endpoint specified.
 234  * \param context Context to use with extension.
 235  * \param timeout The amount of time to wait for answer, before giving up.
 236  *
 237  * \return 0 for success
 238  * \return -1 for error.
 239  */
 240 int stasis_app_control_dial(struct stasis_app_control *control, const char *endpoint, const char *exten,
 241                             const char *context, int timeout);
 242
 243 /*!
 244  * \brief Apply a bridge role to a channel controlled by a stasis app control
 245  *
 246  * \param control Control for \c res_stasis
 247  * \param role Role to apply
 248  *
 249  * \return 0 for success
 250  * \return -1 for error.
 251  */
 252 int stasis_app_control_add_role(struct stasis_app_control *control, const char *role);
 253
 254 /*!
 255  * \brief Clear bridge roles currently applied to a channel controlled by a stasis app control
 256  *
 257  * \param control Control for \c res_stasis
 258  */
 259 void stasis_app_control_clear_roles(struct stasis_app_control *control);
 260
 261 /*!
 262  * \brief Exit \c res_stasis and continue execution in the dialplan.
 263  *
 264  * If the channel is no longer in \c res_stasis, this function does nothing.
 265  *
 266  * \param control Control for \c res_stasis
 267  * \param context An optional context to continue to
 268  * \param extension An optional extension to continue to
 269  * \param priority An optional priority to continue to
 270  *
 271  * \return 0 for success
 272  * \return -1 for error.
 273  */
 274 int stasis_app_control_continue(struct stasis_app_control *control, const char *context, const char *extension, int priority);
 275
 276 /*!
 277  * \brief Indicate ringing to the channel associated with this control.
 278  *
 279  * \param control Control for \c res_stasis.
 280  *
 281  * \return 0 for success.
 282  * \return -1 for error.
 283  */
 284 int stasis_app_control_ring(struct stasis_app_control *control);
 285
 286 /*!
 287  * \brief Stop locally generated ringing on the channel associated with this control.
 288  *
 289  * \param control Control for \c res_stasis.
 290  *
 291  * \return 0 for success.
 292  * \return -1 for error.
 293  */
 294 int stasis_app_control_ring_stop(struct stasis_app_control *control);
 295
 296 /*!
 297  * \brief Send DTMF to the channel associated with this control.
 298  *
 299  * \param control Control for \c res_stasis.
 300  * \param dtmf DTMF string.
 301  * \param before Amount of time to wait before sending DTMF digits.
 302  * \param between Amount of time between each DTMF digit.
 303  * \param duration Amount of time each DTMF digit lasts for.
 304  * \param after Amount of time to wait after sending DTMF digits.
 305  *
 306  * \return 0 for success.
 307  * \return -1 for error.
 308  */
 309 int stasis_app_control_dtmf(struct stasis_app_control *control, const char *dtmf, int before, int between, unsigned int duration, int after);
 310
 311 /*!
 312  * \brief Mute the channel associated with this control.
 313  *
 314  * \param control Control for \c res_stasis.
 315  * \param direction The direction in which the audio should be muted.
 316  * \param frametype The type of stream that should be muted.
 317  *
 318  * \return 0 for success
 319  * \return -1 for error.
 320  */
 321 int stasis_app_control_mute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
 322
 323 /*!
 324  * \brief Unmute the channel associated with this control.
 325  *
 326  * \param control Control for \c res_stasis.
 327  * \param direction The direction in which the audio should be unmuted.
 328  * \param frametype The type of stream that should be unmuted.
 329  *
 330  * \return 0 for success
 331  * \return -1 for error.
 332  */
 333 int stasis_app_control_unmute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
 334
 335 /*!
 336  * \brief Answer the channel associated with this control.
 337  * \param control Control for \c res_stasis.
 338  * \return 0 for success.
 339  * \return Non-zero for error.
 340  */
 341 int stasis_app_control_answer(struct stasis_app_control *control);
 342
 343 /*!
 344  * \brief Get the value of a variable on the channel associated with this control.
 345  * \param control Control for \c res_stasis.
 346  * \param variable The name of the variable.
 347  *
 348  * \return The value of the variable.  The returned variable must be freed.
 349  */
 350 char *stasis_app_control_get_channel_var(struct stasis_app_control *control, const char *variable);
 351
 352 /*!
 353  * \brief Set a variable on the channel associated with this control to value.
 354  * \param control Control for \c res_stasis.
 355  * \param variable The name of the variable
 356  * \param value The value to set the variable to
 357  *
 358  * \return 0 for success.
 359  * \return -1 for error.
 360  */
 361 int stasis_app_control_set_channel_var(struct stasis_app_control *control, const char *variable, const char *value);
 362
 363 /*!
 364  * \brief Place the channel associated with the control on hold.
 365  * \param control Control for \c res_stasis.
 366  */
 367 void stasis_app_control_hold(struct stasis_app_control *control);
 368
 369 /*!
 370  * \brief Remove the channel associated with the control from hold.
 371  * \param control Control for \c res_stasis.
 372  */
 373 void stasis_app_control_unhold(struct stasis_app_control *control);
 374
 375 /*!
 376  * \brief Play music on hold to a channel (does not affect hold status)
 377  * \param control Control for \c res_stasis.
 378  * \param moh_class class of music on hold to play (NULL allowed)
 379  */
 380 void stasis_app_control_moh_start(struct stasis_app_control *control, const char *moh_class);
 381
 382 /*!
 383  * \brief Stop playing music on hold to a channel (does not affect hold status)
 384  * \param control Control for \c res_stasis.
 385  */
 386 void stasis_app_control_moh_stop(struct stasis_app_control *control);
 387
 388 /*!
 389  * \brief Start playing silence to a channel.
 390  * \param control Control for \c res_stasis.
 391  */
 392 void stasis_app_control_silence_start(struct stasis_app_control *control);
 393
 394 /*!
 395  * \brief Stop playing silence to a channel.
 396  * \param control Control for \c res_stasis.
 397  */
 398 void stasis_app_control_silence_stop(struct stasis_app_control *control);
 399
 400 /*!
 401  * \brief Returns the most recent snapshot for the associated channel.
 402  *
 403  * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
 404  *
 405  * \param control Control for \c res_stasis.
 406  *
 407  * \return Most recent snapshot. ao2_cleanup() when done.
 408  * \return \c NULL if channel isn't in cache.
 409  */
 410 struct ast_channel_snapshot *stasis_app_control_get_snapshot(
 411         const struct stasis_app_control *control);
 412
 413 /*!
 414  * \brief Publish a message to the \a control's channel's topic.
 415  *
 416  * \param control Control to publish to
 417  * \param message Message to publish
 418  */
 419 void stasis_app_control_publish(
 420         struct stasis_app_control *control, struct stasis_message *message);
 421
 422 /*!
 423  * \brief Queue a control frame without payload.
 424  *
 425  * \param control Control to publish to.
 426  * \param frame_type type of control frame.
 427  *
 428  * \return zero on success
 429  * \return non-zero on failure
 430  */
 431 int stasis_app_control_queue_control(struct stasis_app_control *control,
 432         enum ast_control_frame_type frame_type);
 433
 434 /*!
 435  * \brief Create a bridge of the specified type.
 436  *
 437  * \param type The type of bridge to be created
 438  *
 439  * \return New bridge.
 440  * \return \c NULL on error.
 441  */
 442 struct ast_bridge *stasis_app_bridge_create(const char *type);
 443
 444 /*!
 445  * \brief Returns the bridge with the given id.
 446  * \param bridge_id Uniqueid of the bridge.
 447  *
 448  * \return NULL bridge not created by a Stasis application, or bridge does not exist.
 449  * \return Pointer to bridge.
 450  */
 451 struct ast_bridge *stasis_app_bridge_find_by_id(
 452         const char *bridge_id);
 453
 454 /*!
 455  * \brief Finds or creates an announcer channel in a bridge that can play music on hold.
 456  *
 457  * \param bridge Bridge we want an MOH channel for
 458  *
 459  * \return NULL if the music on hold channel fails to be created or join the bridge for any reason.
 460  * \return Pointer to the ;1 end of the announcer channel chain.
 461  */
 462 struct ast_channel *stasis_app_bridge_moh_channel(
 463         struct ast_bridge *bridge);
 464
 465 /*!
 466  * \brief Breaks down MOH channels playing on the bridge created by stasis_app_bridge_moh_channel
 467  *
 468  * \param bridge Bridge we want to stop the MOH on
 469  *
 470  * \return -1 if no moh channel could be found and stopped
 471  * \return 0 on success
 472  */
 473 int stasis_app_bridge_moh_stop(
 474         struct ast_bridge *bridge);
 475
 476 /*!
 477  * \brief Add a channel to the bridge.
 478  *
 479  * \param control Control whose channel should be added to the bridge
 480  * \param bridge Pointer to the bridge
 481  *
 482  * \return non-zero on failure
 483  * \return zero on success
 484  */
 485 int stasis_app_control_add_channel_to_bridge(
 486         struct stasis_app_control *control, struct ast_bridge *bridge);
 487
 488 /*!
 489  * \brief Remove a channel from the bridge.
 490  *
 491  * \param control Control whose channel should be removed from the bridge
 492  * \param bridge Pointer to the bridge
 493  *
 494  * \return non-zero on failure
 495  * \return zero on success
 496  */
 497 int stasis_app_control_remove_channel_from_bridge(
 498         struct stasis_app_control *control, struct ast_bridge *bridge);
 499
 500 /*!
 501  * \since 12
 502  * \brief Gets the bridge currently associated with a control object.
 503  *
 504  * \param control Control object for the channel to query.
 505  *
 506  * \return Associated \ref ast_bridge.
 507  * \return \c NULL if not associated with a bridge.
 508  */
 509 struct ast_bridge *stasis_app_get_bridge(struct stasis_app_control *control);
 510
 511 /*!
 512  * \brief Destroy the bridge.
 513  *
 514  * \param bridge_id Uniqueid of bridge to be destroyed
 515  *
 516  * \retval non-zero on failure
 517  * \retval zero on success
 518  */
 519 void stasis_app_bridge_destroy(const char *bridge_id);
 520
 521 /*!
 522  * \brief Increment the res_stasis reference count.
 523  *
 524  * This ensures graceful shutdown happens in the proper order.
 525  */
 526 void stasis_app_ref(void);
 527
 528 /*!
 529  * \brief Decrement the res_stasis reference count.
 530  *
 531  * This ensures graceful shutdown happens in the proper order.
 532  */
 533 void stasis_app_unref(void);
 534
 535 /*! @} */
 536
 537 #endif /* _ASTERISK_STASIS_APP_H */