gst/gstmessage.c: Improve docs for DURATION message (usage of duration parameter...

Original commit message from CVS:
* gst/gstmessage.c:
Improve docs for DURATION message (usage of duration parameter)
(#320113)

diff --git a/ChangeLog b/ChangeLog
index 46684d9..7c2ae9a 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2005-11-21  Tim-Philipp Müller  <tim at centricular dot net>
+
+       * gst/gstmessage.c:
+         Improve docs for DURATION message (usage of duration parameter)
+         (#320113)
+
 2005-11-20  Wim Taymans  <wim@fluendo.com>
 
        * check/Makefile.am:

diff --git a/gst/gstmessage.c b/gst/gstmessage.c
index 0c87af0..79140f3 100644 (file)
--- a/gst/gstmessage.c
+++ b/gst/gstmessage.c
@@ -637,7 +637,10 @@ gst_message_new_element (GstObject * src, GstStructure * structure)
  * Create a new duration message. This message is posted by elements that
  * know the duration of a stream in a specific format. This message
  * is received by bins and is used to calculate the total duration of a
- * pipeline.
+ * pipeline. Elements may post a duration message with a duration of
+ * GST_CLOCK_TIME_NONE to indicate that the duration has changed and the 
+ * cached duration should be discarded. The new duration can then be 
+ * retrieved via a query.
  *
  * Returns: The new duration message.
  *
@@ -932,7 +935,10 @@ gst_message_parse_segment_done (GstMessage * message, GstFormat * format,
  * @format: Result location for the format
  * @duration: Result location for the duration
  *
- * Extracts the duration and format from the duration message.
+ * Extracts the duration and format from the duration message. The duration
+ * might be GST_CLOCK_TIME_NONE, which indicates that the duration has
+ * changed. Applications should always use a query to retrieve the duration
+ * of a pipeline.
  *
  * MT safe.
  */