Merged revisions 260049 via svnmerge from

https://origsvn.digium.com/svn/asterisk/branches/1.4

........
  r260049 | dvossel | 2010-04-29 10:31:02 -0500 (Thu, 29 Apr 2010) | 14 lines
  
  Fixes crash in audiohook_write_list
  
  The middle_frame in the audiohook_write_list function was
  being freed if a audiohook manipulator returned a failure.
  This is incorrect logic.  This patch resolves this and
  adds detailed descriptions of how this function should work
  and why manipulator failures must be ignored.
  
  (closes issue #17052)
  Reported by: dvossel
  Tested by: dvossel

  (closes issue #16196)
  Reported by: atis
  
  Review: https://reviewboard.asterisk.org/r/623/
........


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@260050 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 10 insertions, 3 deletions

diff --git a/include/asterisk/audiohook.h b/include/asterisk/audiohook.h
index b1e77f8a8..6d773bf90 100644
--- a/include/asterisk/audiohook.h
+++ b/include/asterisk/audiohook.h
@@ -75,9 +75,16 @@ struct ast_audiohook;
  * \param chan Channel
  * \param frame Frame of audio to manipulate
  * \param direction Direction frame came from
- * \return Returns 0 on success, -1 on failure
- * \note An audiohook does not have any reference to a private data structure for manipulate types. It is up to the manipulate callback to store this data
- *       via it's own method. An example would be datastores.
+ * \return Returns 0 on success, -1 on failure.
+ * \note An audiohook does not have any reference to a private data structure for manipulate
+ *       types. It is up to the manipulate callback to store this data via it's own method.
+ *       An example would be datastores.
+ * \note The input frame should never be freed or corrupted during a manipulate callback.
+ *       If the callback has the potential to corrupt the frame's data during manipulation,
+ *       local data should be used for the manipulation and only copied to the frame on
+ *       success.
+ * \note A failure return value indicates that the frame was not manipulated and that
+ *       is being returned in its original state.
  */
 typedef int (*ast_audiohook_manipulate_callback)(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction);