ARI: allow other operations to happen while bridged
[asterisk/asterisk.git] / include / asterisk / stasis_app.h
index 00d8f70..d0ea010 100644 (file)
 #include "asterisk/channel.h"
 #include "asterisk/json.h"
 
-struct ast_channel_snapshot;
-
-/*! @{ */
-
-/*!
- * \brief Control a channel using \c stasis_app.
- *
- * This function blocks until the channel hangs up, or
- * stasis_app_control_continue() is called on the channel's \ref
- * stasis_app_control struct.
- *
- * \param chan Channel to control with Stasis.
- * \param app_name Application controlling the channel.
- * \param argc Number of arguments for the application.
- * \param argv Arguments for the application.
- */
-int stasis_app_exec(struct ast_channel *chan, const char *app_name, int argc,
-       char *argv[]);
-
-/*! @} */
-
 /*! @{ */
 
 /*!
@@ -87,7 +66,7 @@ int stasis_app_exec(struct ast_channel *chan, const char *app_name, int argc,
  * \param message Message to handle. (borrowed copy)
  */
 typedef void (*stasis_app_cb)(void *data, const char *app_name,
-                             struct ast_json *message);
+       struct ast_json *message);
 
 /*!
  * \brief Register a new Stasis application.
@@ -148,32 +127,240 @@ struct stasis_app_control *stasis_app_control_find_by_channel_id(
        const char *channel_id);
 
 /*!
+ * \brief Creates a control handler for a channel that isn't in a stasis app.
+ * \since 12.0.0
+ *
+ * \param chan Channel to create controller handle for
+ *
+ * \return NULL on failure to create the handle
+ * \return Pointer to \c res_stasis handler.
+ */
+struct stasis_app_control *stasis_app_control_create(
+       struct ast_channel *chan);
+
+/*!
+ * \brief Act on a stasis app control queue until it is empty
+ * \since 12.0.0
+ *
+ * \param chan Channel to handle
+ * \param control Control object to execute
+ */
+void stasis_app_control_execute_until_exhausted(
+       struct ast_channel *chan,
+       struct stasis_app_control *control);
+
+/*!
+ * \brief Returns the uniqueid of the channel associated with this control
+ *
+ * \param control Control object.
+ * \return Uniqueid of the associate channel.
+ * \return \c NULL if \a control is \c NULL.
+ */
+const char *stasis_app_control_get_channel_id(
+       const struct stasis_app_control *control);
+
+/*!
+ * \brief Dial an endpoint and bridge it to a channel in \c res_stasis
+ *
+ * If the channel is no longer in \c res_stasis, this function does nothing.
+ *
+ * \param control Control for \c res_stasis
+ * \param endpoint The endpoint to dial.
+ * \param timeout The amount of time to wait for answer, before giving up.
+ *
+ * \return 0 for success
+ * \return -1 for error.
+ */
+int stasis_app_control_dial(struct stasis_app_control *control, const char *endpoint, int timeout);
+
+/*!
+ * \brief Apply a bridge role to a channel controlled by a stasis app control
+ *
+ * \param control Control for \c res_stasis
+ * \param role Role to apply
+ *
+ * \return 0 for success
+ * \return -1 for error.
+ */
+int stasis_app_control_add_role(struct stasis_app_control *control, const char *role);
+
+/*!
+ * \brief Clear bridge roles currently applied to a channel controlled by a stasis app control
+ *
+ * \param control Control for \c res_stasis
+ */
+void stasis_app_control_clear_roles(struct stasis_app_control *control);
+
+/*!
  * \brief Exit \c res_stasis and continue execution in the dialplan.
  *
  * If the channel is no longer in \c res_stasis, this function does nothing.
  *
  * \param control Control for \c res_stasis
+ * \param context An optional context to continue to
+ * \param extension An optional extension to continue to
+ * \param priority An optional priority to continue to
+ *
+ * \return 0 for success
+ * \return -1 for error.
+ */
+int stasis_app_control_continue(struct stasis_app_control *control, const char *context, const char *extension, int priority);
+
+/*!
+ * \brief Mute the channel associated with this control.
+ *
+ * \param control Control for \c res_stasis.
+ * \param direction The direction in which the audio should be muted.
+ * \param frametype The type of stream that should be muted.
+ *
+ * \return 0 for success
+ * \return -1 for error.
  */
-void stasis_app_control_continue(struct stasis_app_control *control);
+int stasis_app_control_mute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
+
+/*!
+ * \brief Unmute the channel associated with this control.
+ *
+ * \param control Control for \c res_stasis.
+ * \param direction The direction in which the audio should be unmuted.
+ * \param frametype The type of stream that should be unmuted.
+ *
+ * \return 0 for success
+ * \return -1 for error.
+ */
+int stasis_app_control_unmute(struct stasis_app_control *control, unsigned int direction, enum ast_frame_type frametype);
 
 /*!
  * \brief Answer the channel associated with this control.
  * \param control Control for \c res_stasis.
  * \return 0 for success.
- * \return -1 for error.
+ * \return Non-zero for error.
  */
 int stasis_app_control_answer(struct stasis_app_control *control);
 
-/*! @} */
+/*!
+ * \brief Get the value of a variable on the channel associated with this control.
+ * \param control Control for \c res_stasis.
+ * \param variable The name of the variable.
+ * \return The value of the variable.  The returned variable must be freed.
+ */
+char *stasis_app_control_get_channel_var(struct stasis_app_control *control, const char *variable);
 
-/*! @{ */
+/*!
+ * \brief Set a variable on the channel associated with this control to value.
+ * \param control Control for \c res_stasis.
+ * \param variable The name of the variable
+ * \param value The value to set the variable to
+ *
+ * \return 0 for success.
+ * \return -1 for error.
+ */
+int stasis_app_control_set_channel_var(struct stasis_app_control *control, const char *variable, const char *value);
+
+/*!
+ * \brief Place the channel associated with the control on hold.
+ * \param control Control for \c res_stasis.
+ */
+void stasis_app_control_hold(struct stasis_app_control *control);
+
+/*!
+ * \brief Remove the channel associated with the control from hold.
+ * \param control Control for \c res_stasis.
+ */
+void stasis_app_control_unhold(struct stasis_app_control *control);
+
+/*!
+ * \brief Play music on hold to a channel (does not affect hold status)
+ * \param control Control for \c res_stasis.
+ * \param moh_class class of music on hold to play (NULL allowed)
+ */
+void stasis_app_control_moh_start(struct stasis_app_control *control, const char *moh_class);
+
+/*!
+ * \brief Stop playing music on hold to a channel (does not affect hold status)
+ * \param control Control for \c res_stasis.
+ */
+void stasis_app_control_moh_stop(struct stasis_app_control *control);
 
 /*!
- * \brief Build a JSON object from a \ref ast_channel_snapshot.
- * \return JSON object representing channel snapshot.
- * \return \c NULL on error
+ * \brief Returns the most recent snapshot for the associated channel.
+ *
+ * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
+ *
+ * \param control Control for \c res_stasis.
+ * \return Most recent snapshot. ao2_cleanup() when done.
+ * \return \c NULL if channel isn't in cache.
+ */
+struct ast_channel_snapshot *stasis_app_control_get_snapshot(
+       const struct stasis_app_control *control);
+
+/*!
+ * \brief Publish a message to the \a control's channel's topic.
+ *
+ * \param control Control to publish to
+ * \param message Message to publish
+ */
+void stasis_app_control_publish(
+       struct stasis_app_control *control, struct stasis_message *message);
+
+/*!
+ * \brief Queue a control frame without payload.
+ *
+ * \param control Control to publish to.
+ * \param frame_type type of control frame.
+ *
+ * \return zero on success
+ * \return non-zero on failure
+ */
+int stasis_app_control_queue_control(struct stasis_app_control *control,
+       enum ast_control_frame_type frame_type);
+
+/*!
+ * \brief Create a bridge of the specified type.
+ *
+ * \param type The type of bridge to be created
+ *
+ * \return New bridge.
+ * \return \c NULL on error.
+ */
+struct ast_bridge *stasis_app_bridge_create(const char *type);
+
+/*!
+ * \brief Returns the bridge with the given id.
+ * \param bridge_id Uniqueid of the bridge.
+ * \return NULL bridge not created by a Stasis application, or bridge does not exist.
+ * \return Pointer to bridge.
+ */
+struct ast_bridge *stasis_app_bridge_find_by_id(
+       const char *bridge_id);
+
+/*!
+ * \brief Add a channel to the bridge.
+ *
+ * \param control Control whose channel should be added to the bridge
+ * \param bridge Pointer to the bridge
+ */
+void stasis_app_control_add_channel_to_bridge(
+       struct stasis_app_control *control, struct ast_bridge *bridge);
+
+/*!
+ * \brief Remove a channel from the bridge.
+ *
+ * \param control Control whose channel should be removed from the bridge
+ * \param bridge Pointer to the bridge
+ */
+void stasis_app_control_remove_channel_from_bridge(
+       struct stasis_app_control *control, struct ast_bridge *bridge);
+
+/*!
+ * \brief Destroy the bridge.
+ *
+ * \param bridge_id Uniqueid of bridge to be destroyed
+ *
+ * \retval non-zero on failure
+ * \retval zero on success
  */
-struct ast_json *ast_channel_snapshot_to_json(const struct ast_channel_snapshot *snapshot);
+void stasis_app_bridge_destroy(const char *bridge_id);
 
 /*!
  * \brief Increment the res_stasis reference count.