From: Sebastian Dröge <sebastian.droege@collabora.co.uk>
Date: Fri, 10 Jul 2009 09:24:05 +0000 (+0200)
Subject: gio: Add documentation for the new "not-mounted" and "file-exists" messages
X-Git-Tag: RELEASE-0.10.24~59
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=d5154874cb1f884b9da4556640c2f951b0dc5fd6;p=platform%2Fupstream%2Fgst-plugins-base.git

gio: Add documentation for the new "not-mounted" and "file-exists" messages
---

diff --git a/ext/gio/gstgiosink.c b/ext/gio/gstgiosink.c
index 57d102494..a76b4b104 100644
--- a/ext/gio/gstgiosink.c
+++ b/ext/gio/gstgiosink.c
@@ -27,6 +27,18 @@
  * by an URI. This location can be specified using any protocol supported by
  * the GIO library or it's VFS backends. Common protocols are 'file', 'ftp',
  * or 'smb'.
+ *
+ * If the URI or #GFile already exists giosink will post a message of
+ * type %GST_MESSAGE_ELEMENT with name "file-exists" on the bus. The message
+ * also contains the #GFile and the corresponding URI.
+ * Applications can use the "file-exists" message to notify the user about
+ * the problem and to set a different target location or to remove the
+ * existing file. Note that right after the "file-exists" message a normal
+ * error message is posted on the bus which should be ignored if "file-exists"
+ * is handled by the application, for example by calling
+ * gst_bus_set_flushing(bus, TRUE) after the "file-exists" message was
+ * received and gst_bus_set_flushing(bus, FALSE) after the problem is
+ * resolved.
  * 
  * <refsect2>
  * <title>Example pipelines</title>
diff --git a/ext/gio/gstgiosrc.c b/ext/gio/gstgiosrc.c
index ce944be6b..5fd810e73 100644
--- a/ext/gio/gstgiosrc.c
+++ b/ext/gio/gstgiosrc.c
@@ -28,6 +28,18 @@
  * the GIO library or it's VFS backends. Common protocols are 'file', 'http',
  * 'ftp', or 'smb'.
  *
+ * If an URI or #GFile is not mounted giosrc will post a message of type
+ * %GST_MESSAGE_ELEMENT with name "not-mounted" on the bus. The message
+ * also contains the #GFile and the corresponding URI.
+ * Applications can use the "not-mounted" message to mount the #GFile
+ * by calling g_file_mount_enclosing_volume() and then restart the
+ * pipeline after the mounting has succeeded. Note that right after the
+ * "not-mounted" message a normal error message is posted on the bus which
+ * should be ignored if "not-mounted" is handled by the application, for
+ * example by calling gst_bus_set_flushing(bus, TRUE) after the "not-mounted"
+ * message was received and gst_bus_set_flushing(bus, FALSE) after the
+ * mounting was successful.
+ *
  * <refsect2>
  * <title>Example launch lines</title>
  * |[