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: http://svn.digium.com/svn/asterisk/branches/1.4@200991 f38db490-d61c-443f-a65b-d21fe96a405b

3 files changed, 49 insertions, 9 deletions

diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h
index de81f75c2..92c86fca5 100644
--- a/include/asterisk/channel.h
+++ b/include/asterisk/channel.h
@@ -633,16 +633,27 @@ int ast_setstate(struct ast_channel *chan, enum ast_channel_state);
  */
 struct ast_channel *ast_channel_alloc(int needqueue, int state, const char *cid_num, const char *cid_name, const char *acctcode, const char *exten, const char *context, const int amaflag, const char *name_fmt, ...) __attribute__((format(printf, 9, 10)));
 
-/*! \brief Queue an outgoing frame */
+/*!
+ * \brief Queue one or more frames to a channel's frame queue
+ *
+ * \param chan the channel to queue the frame(s) on
+ * \param f the frame(s) to queue.  Note that the frame(s) will be duplicated
+ *        by this function.  It is the responsibility of the caller to handle
+ *        freeing the memory associated with the frame(s) being passed if
+ *        necessary.
+ *
+ * \retval 0 success
+ * \retval non-zero failure
+ */
 int ast_queue_frame(struct ast_channel *chan, struct ast_frame *f);
 
 /*!
- * \brief Queue an outgoing frame to the head of the frame queue
+ * \brief Queue one or more frames to the head of a channel's frame queue
  *
- * \param chan the channel to queue the frame on
- * \param f the frame to queue.  Note that this frame will be duplicated by
- *        this function.  It is the responsibility of the caller to handle
- *        freeing the memory associated with the frame being passed if
+ * \param chan the channel to queue the frame(s) on
+ * \param f the frame(s) to queue.  Note that the frame(s) will be duplicated
+ *        by this function.  It is the responsibility of the caller to handle
+ *        freeing the memory associated with the frame(s) being passed if
  *        necessary.
  *
  * \retval 0 success
diff --git a/include/asterisk/frame.h b/include/asterisk/frame.h
index bb5026908..f874643c0 100644
--- a/include/asterisk/frame.h
+++ b/include/asterisk/frame.h
@@ -399,9 +399,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);
@@ -415,6 +415,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);
 
diff --git a/include/asterisk/linkedlists.h b/include/asterisk/linkedlists.h
index bd7f6a9b1..b78e7b002 100644
--- a/include/asterisk/linkedlists.h
+++ b/include/asterisk/linkedlists.h
@@ -685,7 +685,7 @@ struct {								\
   \param head This is a pointer to the list head structure
   \param list This is a pointer to the list to be appended.
   \param field This is the name of the field (declared using AST_LIST_ENTRY())
-  used to link entries of this list together.
+  used to link entries of the list together.
 
   Note: The source list (the \a list parameter) will be empty after
   calling this macro (the list entries are \b moved to the target list).
@@ -705,6 +705,30 @@ struct {								\
 #define AST_RWLIST_APPEND_LIST AST_LIST_APPEND_LIST
 
 /*!
+  \brief Inserts a whole list after a specific entry in a list
+  \param head This is a pointer to the list head structure
+  \param list This is a pointer to the list to be inserted.
+  \param elm This is a pointer to the entry after which the new list should
+  be inserted.
+  \param field This is the name of the field (declared using AST_LIST_ENTRY())
+  used to link entries of the lists together.
+
+  Note: The source list (the \a list parameter) will be empty after
+  calling this macro (the list entries are \b moved to the target list).
+ */
+#define AST_LIST_INSERT_LIST_AFTER(head, list, elm, field) do {		\
+	(list)->last->field.next = (elm)->field.next;			\
+	(elm)->field.next = (list)->first;				\
+	if ((head)->last == elm) {					\
+		(head)->last = (list)->last;				\
+	}								\
+	(list)->first = NULL;						\
+	(list)->last = NULL;						\
+} while(0)
+
+#define AST_RWLIST_INSERT_LIST_AFTER AST_LIST_INSERT_LIST_AFTER
+
+/*!
   \brief Removes and returns the head entry from a list.
   \param head This is a pointer to the list head structure
   \param field This is the name of the field (declared using AST_LIST_ENTRY())