Migrate a large number of AMI events over to Stasis-Core
[asterisk/asterisk.git] / include / asterisk / stasis_channels.h
index 53dcc24..7c214d5 100644 (file)
@@ -54,6 +54,7 @@ struct ast_channel_snapshot {
                AST_STRING_FIELD(caller_number);        /*!< Caller ID Number */
                AST_STRING_FIELD(connected_name);       /*!< Connected Line Name */
                AST_STRING_FIELD(connected_number);     /*!< Connected Line Number */
+               AST_STRING_FIELD(language);             /*!< The default spoken language for the channel */
        );
 
        struct timeval creationtime;    /*!< The time of channel creation */
@@ -70,8 +71,7 @@ struct ast_channel_snapshot {
  * \since 12
  * \brief Blob of data associated with a channel.
  *
- * The \c blob is actually a JSON object of structured data. It has a "type" field
- * which contains the type string describing this blob.
+ * This blob is actually shared amongst several \ref stasis_message_type's.
  */
 struct ast_channel_blob {
        /*! Channel blob is associated with (or NULL for global/all channels) */
@@ -112,60 +112,93 @@ struct stasis_message_type *ast_channel_snapshot_type(void);
 
 /*!
  * \since 12
- * \brief Message type for \ref ast_channel_blob messages.
+ * \brief Generate a snapshot of the channel state. This is an ao2 object, so
+ * ao2_cleanup() to deallocate.
  *
- * \retval Message type for \ref ast_channel_blob messages.
+ * \param chan The channel from which to generate a snapshot
+ *
+ * \retval pointer on success (must be ast_freed)
+ * \retval NULL on error
  */
-struct stasis_message_type *ast_channel_blob_type(void);
+struct ast_channel_snapshot *ast_channel_snapshot_create(
+       struct ast_channel *chan);
 
 /*!
  * \since 12
- * \brief Generate a snapshot of the channel state. This is an ao2 object, so
- * ao2_cleanup() to deallocate.
+ * \brief Obtain the latest \ref ast_channel_snapshot from the \ref stasis cache. This is
+ * an ao2 object, so use \ref ao2_cleanup() to deallocate.
  *
- * \param chan The channel from which to generate a snapshot
+ * \param unique_id The channel's unique ID
  *
- * \retval pointer on success (must be ast_freed)
+ * \retval A \ref ast_channel_snapshot on success
  * \retval NULL on error
  */
-struct ast_channel_snapshot *ast_channel_snapshot_create(struct ast_channel *chan);
+struct ast_channel_snapshot *ast_channel_snapshot_get_latest(const char *uniqueid);
 
 /*!
  * \since 12
  * \brief Creates a \ref ast_channel_blob message.
  *
- * The \a blob JSON object requires a \c "type" field describing the blob. It
- * should also be treated as immutable and not modified after it is put into the
- * message.
+ * The given \a blob should be treated as immutable and not modified after it is
+ * put into the message.
+ *
+ * \param chan Channel blob is associated with, or \c NULL for global/all channels.
+ * \param type Message type for this blob.
+ * \param blob JSON object representing the data, or \c NULL for no data. If
+ *             \c NULL, ast_json_null() is put into the object.
  *
- * \param chan Channel blob is associated with, or NULL for global/all channels.
- * \param blob JSON object representing the data.
  * \return \ref ast_channel_blob message.
  * \return \c NULL on error
  */
 struct stasis_message *ast_channel_blob_create(struct ast_channel *chan,
-                                              struct ast_json *blob);
+       struct stasis_message_type *type, struct ast_json *blob);
 
 /*!
  * \since 12
- * \brief Extracts the type field from a \ref ast_channel_blob.
- * Returned \c char* is still owned by \a obj
- * \param obj Channel blob object.
- * \return Type field value from the blob.
- * \return \c NULL on error.
+ * \brief Creates a \ref ast_channel_blob message using the current cached
+ * \ref ast_channel_snapshot for the passed in \ref ast_channel
+ *
+ * The given \a blob should be treated as immutable and not modified after it is
+ * put into the message.
+ *
+ * \param chan Channel blob is associated with, or \c NULL for global/all channels.
+ * \param type Message type for this blob.
+ * \param blob JSON object representing the data, or \c NULL for no data. If
+ *             \c NULL, ast_json_null() is put into the object.
+ *
+ * \param chan Channel blob is associated with
+ * \param blob JSON object representing the data.
+ * \return \ref ast_channel_blob message.
+ * \return \c NULL on error
  */
-const char *ast_channel_blob_json_type(struct ast_channel_blob *obj);
+struct stasis_message *ast_channel_cached_blob_create(struct ast_channel *chan,
+       struct stasis_message_type *type, struct ast_json *blob);
 
 /*!
  * \since 12
- * \brief Create a \ref ast_multi_channel_blob suitable for a \ref stasis_message
+ * \brief Create a \ref ast_channel_blob message, pulling channel state from
+ *        the cache.
  *
- * \note Similar to a \ref ast_channel_blob, the \ref ast_multi_channel_blob requires
- * a \a blob JSON object containing a \c "type" field describing the blob. It
- * should also be treated as immutable and not modified after it is put into the
- * message.
+ * \param uniqueid Uniqueid of the channel.
+ * \param type Message type for this blob.
+ * \param blob JSON object representing the data, or \c NULL for no data. If
+ *             \c NULL, ast_json_null() is put into the object.
  *
- * \param blob The JSON blob that defines the type of this \ref ast_multi_channel_blob
+ * \return \ref ast_channel_blob message.
+ * \return \c NULL on error
+ */
+struct stasis_message *ast_channel_blob_create_from_cache(
+       const char *uniqueid, struct stasis_message_type *type,
+       struct ast_json *blob);
+
+/*!
+ * \since 12
+ * \brief Create a \ref ast_multi_channel_blob suitable for a \ref stasis_message.
+ *
+ * The given \a blob should be treated as immutable and not modified after it is
+ * put into the message.
+ *
+ * \param blob The JSON blob that defines the data of this \ref ast_multi_channel_blob
  *
  * \return \ref ast_multi_channel_blob object
  * \return \c NULL on error
@@ -189,8 +222,7 @@ struct ast_multi_channel_blob *ast_multi_channel_blob_create(struct ast_json *bl
  * \retval NULL on error or not found for the role specified
  */
 struct ast_channel_snapshot *ast_multi_channel_blob_get_channel(
-                                              struct ast_multi_channel_blob *obj,
-                                              const char *role);
+       struct ast_multi_channel_blob *obj, const char *role);
 
 /*!
  * \since 12
@@ -212,8 +244,7 @@ struct ast_channel_snapshot *ast_multi_channel_blob_get_channel(
  * \retval NULL on error or not found for the role specified
  */
 struct ao2_container *ast_multi_channel_blob_get_channels(
-                                              struct ast_multi_channel_blob *obj,
-                                              const char *role);
+       struct ast_multi_channel_blob *obj, const char *role);
 
 /*!
  * \since 12
@@ -228,17 +259,6 @@ struct ast_json *ast_multi_channel_blob_get_json(struct ast_multi_channel_blob *
 
 /*!
  * \since 12
- * \brief Extracts the type field from a \ref ast_multi_channel_blob.
- * Returned \c char* is still owned by \a obj
- *
- * \param obj Channel blob object.
- * \return Type field value from the blob.
- * \return \c NULL on error.
- */
-const char *ast_multi_channel_blob_get_type(struct ast_multi_channel_blob *obj);
-
-/*!
- * \since 12
  * \brief Add a \ref ast_channel_snapshot to a \ref ast_multi_channel_blob object
  *
  * \note This will increase the reference count by 1 for the channel snapshot. It is
@@ -250,8 +270,15 @@ const char *ast_multi_channel_blob_get_type(struct ast_multi_channel_blob *obj);
  * \ref ast_multi_channel_blob object
  */
 void ast_multi_channel_blob_add_channel(struct ast_multi_channel_blob *obj,
-                                              const char *role,
-                                              struct ast_channel_snapshot *snapshot);
+       const char *role, struct ast_channel_snapshot *snapshot);
+
+/*!
+ * \since 12
+ * \brief Publish a \ref ast_channel_snapshot for a channel.
+ *
+ * \param chan Channel to publish.
+ */
+void ast_channel_publish_snapshot(struct ast_channel *chan);
 
 /*!
  * \since 12
@@ -274,6 +301,110 @@ struct stasis_message_type *ast_channel_dial_type(void);
 
 /*!
  * \since 12
+ * \brief Message type for when a variable is set on a channel.
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_varset_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for when a custom user event is sent on a channel.
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_user_event_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for when a hangup is requested on a channel.
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_hangup_request_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for when DTMF begins on a channel.
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_dtmf_begin_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for when DTMF ends on a channel.
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_dtmf_end_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for when a channel starts spying on another channel
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_chanspy_start_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for when a channel stops spying on another channel
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_chanspy_stop_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for a fax operation
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_fax_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for hangup handler related actions
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_hangup_handler_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for starting monitor on a channel
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_monitor_start_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for stopping monitor on a channel
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_monitor_stop_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for starting music on hold on a channel
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_moh_start_type(void);
+
+/*!
+ * \since 12
+ * \brief Message type for stopping music on hold on a channel
+ *
+ * \retval A stasis message type
+ */
+struct stasis_message_type *ast_channel_moh_stop_type(void);
+
+/*!
+ * \since 12
  * \brief Publish in the \ref ast_channel_topic or \ref ast_channel_topic_all
  * topics a stasis message for the channels involved in a dial operation.
  *
@@ -289,6 +420,15 @@ void ast_channel_publish_dial(struct ast_channel *caller,
                const char *dialstring,
                const char *dialstatus);
 
+/*!
+ * \since 12
+ * \brief Publish in the \ref ast_channel_topic a \ref ast_channel_snapshot
+ * message indicating a change in channel state
+ *
+ * \param chan The channel whose state has changed
+ */
+void ast_publish_channel_state(struct ast_channel *chan);
+
 /*! @} */
 
 /*!
@@ -299,6 +439,34 @@ void ast_channel_publish_dial(struct ast_channel *caller,
 struct ast_json *ast_channel_snapshot_to_json(const struct ast_channel_snapshot *snapshot);
 
 /*!
+ * \brief Compares the context, exten and priority of two snapshots.
+ * \since 12
+ *
+ * \param old_snapshot Old snapshot
+ * \param new_snapshot New snapshot
+ *
+ * \return True (non-zero) if context, exten or priority are identical.
+ * \return False (zero) if context, exten and priority changed.
+ */
+int ast_channel_snapshot_cep_equal(
+       const struct ast_channel_snapshot *old_snapshot,
+       const struct ast_channel_snapshot *new_snapshot);
+
+/*!
+ * \brief Compares the callerid info of two snapshots.
+ * \since 12
+ *
+ * \param old_snapshot Old snapshot
+ * \param new_snapshot New snapshot
+ *
+ * \return True (non-zero) if callerid are identical.
+ * \return False (zero) if callerid changed.
+ */
+int ast_channel_snapshot_caller_id_equal(
+       const struct ast_channel_snapshot *old_snapshot,
+       const struct ast_channel_snapshot *new_snapshot);
+
+/*!
  * \brief Dispose of the stasis channel topics and message types
  */
 void ast_stasis_channels_shutdown(void);