Merged revisions 200991 via svnmerge from

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

........
  r200991 | kpfleming | 2009-06-16 12:05:38 -0500 (Tue, 16 Jun 2009) | 11 lines
  
  Improve support for media paths that can generate multiple frames at once.
  
  There are various media paths in Asterisk (codec translators and UDPTL, primarily)
  that can generate more than one frame to be generated when the application calling
  them expects only a single frame. This patch addresses a number of those cases,
  at least the primary ones to solve the known problems. In addition it removes the
  broken TRACE_FRAMES support, fixes a number of bugs in various frame-related API
  functions, and cleans up various code paths affected by these changes.
  
  https://reviewboard.asterisk.org/r/175/
........


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

include/asterisk/frame.h

@@ -449,9 +449,9 @@ struct ast_frame *ast_fralloc(char *source, int len);
 #endif
 
 /*!  
- * \brief Frees a frame 
+ * \brief Frees a frame or list of frames
  * 
- * \param fr Frame to free
+ * \param fr Frame to free, or head of list to free
  * \param cache Whether to consider this frame for frame caching
  */
 void ast_frame_free(struct ast_frame *fr, int cache);
@@ -465,6 +465,11 @@ void ast_frame_free(struct ast_frame *fr, int cache);
  * data malloc'd.  If you need to store frames, say for queueing, then
  * you should call this function.
  * \return Returns a frame on success, NULL on error
+ * \note This function may modify the frame passed to it, so you must
+ * not assume the frame will be intact after the isolated frame has
+ * been produced. In other words, calling this function on a frame
+ * should be the last operation you do with that frame before freeing
+ * it (or exiting the block, if the frame is on the stack.)
  */
 struct ast_frame *ast_frisolate(struct ast_frame *fr);