Add Doxygen documentation for API changes from 1.6.0 to 1.6.1
[asterisk/asterisk.git] / include / asterisk / audiohook.h
index 3345c5d..1012822 100644 (file)
@@ -60,6 +60,8 @@ enum ast_audiohook_flags {
        AST_AUDIOHOOK_TRIGGER_SYNC = (1 << 2),  /*!< Audiohook wants to be triggered when both sides have combined audio available */
 };
 
        AST_AUDIOHOOK_TRIGGER_SYNC = (1 << 2),  /*!< Audiohook wants to be triggered when both sides have combined audio available */
 };
 
+#define AST_AUDIOHOOK_SYNC_TOLERANCE 100 /*< Tolerance in milliseconds for audiohooks synchronization */
+
 struct ast_audiohook;
 
 /*! \brief Callback function for manipulate audiohook type
 struct ast_audiohook;
 
 /*! \brief Callback function for manipulate audiohook type
@@ -148,7 +150,22 @@ int ast_audiohook_detach(struct ast_audiohook *audiohook);
  */
 int ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
 
  */
 int ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
 
-/*! 
+/*! \brief Move an audiohook from one channel to a new one
+ *
+ * \todo Currently only the first audiohook of a specific source found will be moved.
+ * We should add the capability to move multiple audiohooks from a single source as well.
+ *
+ * \note It is required that both old_chan and new_chan are locked prior to calling
+ * this function. Besides needing to protect the data within the channels, not locking
+ * these channels can lead to a potential deadlock
+ *
+ * \param old_chan The source of the audiohook to move
+ * \param new_chan The destination to which we want the audiohook to move
+ * \param source The source of the audiohook we want to move
+ */
+void ast_audiohook_move_by_source(struct ast_channel *old_chan, struct ast_channel *new_chan, const char *source);
+
+/*!
  * \brief Detach specified source audiohook from channel
  *
  * \param chan Channel to detach from
  * \brief Detach specified source audiohook from channel
  *
  * \param chan Channel to detach from
@@ -188,9 +205,9 @@ void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
 
 /*!
   \brief Find out how many audiohooks from  a certain source exist on a given channel, regardless of status.
 
 /*!
   \brief Find out how many audiohooks from  a certain source exist on a given channel, regardless of status.
-  \param chan The channel on which to find the spies 
+  \param chan The channel on which to find the spies
   \param source The audiohook's source
   \param source The audiohook's source
-  \param type The type of audiohook 
+  \param type The type of audiohook
   \return Return the number of audiohooks which are from the source specified
 
   Note: Function performs nlocking.
   \return Return the number of audiohooks which are from the source specified
 
   Note: Function performs nlocking.
@@ -218,26 +235,32 @@ int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, cons
  */
 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
 
  */
 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
 
-/*! \brief Adjust the volume on frames read from or written to a channel
+/*!
+ * \brief Adjust the volume on frames read from or written to a channel
  * \param chan Channel to muck with
  * \param direction Direction to set on
  * \param volume Value to adjust the volume by
  * \return Returns 0 on success, -1 on failure
  * \param chan Channel to muck with
  * \param direction Direction to set on
  * \param volume Value to adjust the volume by
  * \return Returns 0 on success, -1 on failure
+ * \since 1.6.1
  */
 int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
 
  */
 int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
 
-/*! \brief Retrieve the volume adjustment value on frames read from or written to a channel
+/*!
+ * \brief Retrieve the volume adjustment value on frames read from or written to a channel
  * \param chan Channel to retrieve volume adjustment from
  * \param direction Direction to retrieve
  * \return Returns adjustment value
  * \param chan Channel to retrieve volume adjustment from
  * \param direction Direction to retrieve
  * \return Returns adjustment value
+ * \since 1.6.1
  */
 int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direction direction);
 
  */
 int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direction direction);
 
-/*! \brief Adjust the volume on frames read from or written to a channel
+/*!
+ * \brief Adjust the volume on frames read from or written to a channel
  * \param chan Channel to muck with
  * \param direction Direction to increase
  * \param volume Value to adjust the adjustment by
  * \return Returns 0 on success, -1 on failure
  * \param chan Channel to muck with
  * \param direction Direction to increase
  * \param volume Value to adjust the adjustment by
  * \return Returns 0 on success, -1 on failure
+ * \since 1.6.1
  */
 int ast_audiohook_volume_adjust(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
 
  */
 int ast_audiohook_volume_adjust(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);