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

diff --git a/ChangeLog b/ChangeLog
index cdfaff7..66b2a4b 100644 (file)
--- a/ChangeLog
+++ b/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:

diff --git a/docs/design/part-buffering.txt b/docs/design/part-buffering.txt
index 7991ca5..adf4503 100644 (file)
--- a/docs/design/part-buffering.txt
+++ b/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
+--------
+
+
 

diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt
index 113df16..2c260bd 100644 (file)
--- a/docs/gst/gstreamer-sections.txt
+++ b/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

diff --git a/gst/gstmessage.c b/gst/gstmessage.c
index 85941d7..8a6dd9a 100644 (file)
--- a/gst/gstmessage.c
+++ b/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.
  *
@@ -397,6 +398,35 @@ gst_message_new_tag (GstObject * src, GstTagList * tag_list)
 }
 
 /**
+ * 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
  * @oldstate: the previous state
@@ -700,6 +730,27 @@ gst_message_parse_tag (GstMessage * message, GstTagList ** tag_list)
 }
 
 /**
+ * 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
  * @oldstate: the previous state, or NULL

diff --git a/gst/gstmessage.h b/gst/gstmessage.h
index e33e257..23e3f2d 100644 (file)
--- a/gst/gstmessage.h
+++ b/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);