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 57d10249422c705fee29ce371a1d2bd8be9aedef..a76b4b104351b835e32b214044b0ab5f69ac03c7 100644 (file)
--- 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 ce944be6b76d8fd1f5a9eb1a65314a621d08d5d7..5fd810e73e526f6f9c1ebff24ed64d39001e57de 100644 (file)
--- 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>
  * |[