Added methods to create and parse BUFFERING messages.

Original commit message from CVS:
* docs/design/part-buffering.txt:
* docs/gst/gstreamer-sections.txt:
* gst/gstmessage.c: (gst_message_new_buffering),
(gst_message_parse_buffering):
* gst/gstmessage.h:
Added methods to create and parse BUFFERING messages.
Added preliminary docs about buffering.
API: gst_message_new_buffering
API: gst_message_parse_buffering

ChangeLog

@@ -1,3 +1,15 @@
+2006-09-15  Wim Taymans  <wim@fluendo.com>
+
+	* docs/design/part-buffering.txt:
+	* docs/gst/gstreamer-sections.txt:
+	* gst/gstmessage.c: (gst_message_new_buffering),
+	(gst_message_parse_buffering):
+	* gst/gstmessage.h:
+	Added methods to create and parse BUFFERING messages.
+	Added preliminary docs about buffering.
+	API: gst_message_new_buffering
+	API: gst_message_parse_buffering
+
 2006-09-06  Wim Taymans  <wim@fluendo.com>
 
 	* gst/gstbin.c:

docs/design/part-buffering.txt

@@ -4,4 +4,17 @@ Buffering
 This document outlines the buffering policy used in the GStreamer
 core that can be used by plugins and applications.
 
+The purpose of buffering is to accumulate enough data in a pipeline so that
+playback can occur smoothly and without interruptions. It is typically done when
+reading from a (slow) and non-live network source.
+
+While data is buffered, the pipeline should remain in the PAUSED state. It is
+also possible that more data should be buffered while the pipeline is PLAYING,
+in which case the pipeline should be PAUSED until the buffering finished.
+
+
+Messages
+--------
+
+
 

docs/gst/gstreamer-sections.txt

@@ -996,6 +996,7 @@ gst_message_new_segment_done
 gst_message_new_segment_start
 gst_message_new_state_changed
 gst_message_new_tag
+gst_message_new_buffering
 gst_message_new_warning
 gst_message_new_duration
 gst_message_new_state_dirty
@@ -1007,6 +1008,7 @@ gst_message_parse_segment_done
 gst_message_parse_segment_start
 gst_message_parse_state_changed
 gst_message_parse_tag
+gst_message_parse_buffering
 gst_message_parse_warning
 gst_message_parse_duration
 gst_message_ref

gst/gstmessage.c

@@ -328,7 +328,8 @@ gst_message_new_eos (GstObject * src)
  *
  * Create a new error message. The message will copy @error and
  * @debug. This message is posted by element when a fatal event
- * occured. The pipeline will probably (partially) stop.
+ * occured. The pipeline will probably (partially) stop. The application
+ * receiving this message should stop the pipeline.
  *
  * Returns: The new error message.
  *
@@ -396,6 +397,35 @@ gst_message_new_tag (GstObject * src, GstTagList * tag_list)
   return message;
 }
 
+/**
+ * gst_message_new_buffering:
+ * @src: The object originating the message.
+ * @percent: The buffering percent
+ *
+ * Create a new buffering message. This message can be posted by an element that
+ * needs to buffer data before it can continue processing. @percent should be a
+ * value between 0 and 100. A value of 100 means that the buffering completed.
+ *
+ * Returns: The new buffering message.
+ *
+ * Since: 0.10.11
+ *
+ * MT safe.
+ */
+GstMessage *
+gst_message_new_buffering (GstObject * src, gint percent)
+{
+  GstMessage *message;
+
+  g_return_val_if_fail (percent >= 0 && percent <= 100, NULL);
+
+  message = gst_message_new_custom (GST_MESSAGE_BUFFERING, src,
+      gst_structure_new ("GstMessageBuffering",
+          "buffer-percent", G_TYPE_INT, percent, NULL));
+
+  return message;
+}
+
 /**
  * gst_message_new_state_changed:
  * @src: the object originating the message
@@ -699,6 +729,27 @@ gst_message_parse_tag (GstMessage * message, GstTagList ** tag_list)
   *tag_list = (GstTagList *) gst_structure_copy (message->structure);
 }
 
+/**
+ * gst_message_parse_buffering:
+ * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
+ * @percent: Return location for the percent.
+ *
+ * Extracts the buffering percent from the GstMessage. 
+ *
+ * Since: 0.10.11
+ *
+ * MT safe.
+ */
+void
+gst_message_parse_buffering (GstMessage * message, gint * percent)
+{
+  g_return_if_fail (GST_IS_MESSAGE (message));
+  g_return_if_fail (GST_MESSAGE_TYPE (message) == GST_MESSAGE_BUFFERING);
+
+  if (percent)
+    gst_structure_get_int (message->structure, "buffer-percent", percent);
+}
+
 /**
  * gst_message_parse_state_changed:
  * @message: a valid #GstMessage of type GST_MESSAGE_STATE_CHANGED

gst/gstmessage.h

@@ -84,7 +84,7 @@ typedef enum
   GST_MESSAGE_SEGMENT_START     = (1 << 16),
   GST_MESSAGE_SEGMENT_DONE      = (1 << 17),
   GST_MESSAGE_DURATION          = (1 << 18),
-  GST_MESSAGE_ANY               = 0x7fffffff 
+  GST_MESSAGE_ANY               = ~0
 } GstMessageType;
 
 #include <gst/gstminiobject.h>
@@ -247,6 +247,7 @@ GstMessage *	gst_message_new_eos		(GstObject * src);
 GstMessage *	gst_message_new_error		(GstObject * src, GError * error, gchar * debug);
 GstMessage *	gst_message_new_warning		(GstObject * src, GError * error, gchar * debug);
 GstMessage *	gst_message_new_tag		(GstObject * src, GstTagList * tag_list);
+GstMessage *	gst_message_new_buffering	(GstObject * src, gint percent);
 GstMessage *	gst_message_new_state_changed	(GstObject * src, GstState oldstate,
                                                  GstState newstate, GstState pending);
 GstMessage *	gst_message_new_state_dirty	(GstObject * src);
@@ -265,6 +266,7 @@ GstMessage *	gst_message_new_custom		(GstMessageType type,
 void		gst_message_parse_error		(GstMessage *message, GError **gerror, gchar **debug);
 void		gst_message_parse_warning	(GstMessage *message, GError **gerror, gchar **debug);
 void		gst_message_parse_tag		(GstMessage *message, GstTagList **tag_list);
+void 		gst_message_parse_buffering	(GstMessage *message, gint *percent);
 void		gst_message_parse_state_changed	(GstMessage *message, GstState *oldstate,
                                                  GstState *newstate, GstState *pending);
 void		gst_message_parse_clock_provide (GstMessage *message, GstClock **clock, gboolean *ready);