Add new method g_volume_get_activation_root(). This is needed for easily

2008-07-06  David Zeuthen  <davidz@redhat.com>

	* gio.symbols:
	* gvolume.[ch]: Add new method g_volume_get_activation_root(). This
	is needed for easily handling adoption of foreign volumes by
	out-of-process volume monitors (#541793)

svn path=/trunk/; revision=7169

diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index 52a1482040fb55825249e6c583ab1f73cc7ca7ee..7e6ba7131d4a0385d8726f249e72b987e4ec6549 100644 (file)
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -835,6 +835,7 @@ g_volume_get_drive
 g_volume_get_mount
 g_volume_can_mount
 g_volume_should_automount
+g_volume_get_activation_root
 g_volume_mount
 g_volume_mount_finish
 g_volume_can_eject

diff --git a/gio/ChangeLog b/gio/ChangeLog
index 658c7f44d3401f4ac8aa00926dd8936c824270df..c5441e133bda8c13fa6fbafec29af72c277ee16b 100644 (file)
--- a/gio/ChangeLog
+++ b/gio/ChangeLog
@@ -1,3 +1,10 @@
+2008-07-06  David Zeuthen  <davidz@redhat.com>
+
+       * gio.symbols:
+       * gvolume.[ch]: Add new method g_volume_get_activation_root(). This
+       is needed for easily handling adoption of foreign volumes by
+       out-of-process volume monitors (#541793)
+
 2008-07-06  David Zeuthen  <davidz@redhat.com>
 
        * gvolumemonitor.[ch]:

diff --git a/gio/gio.symbols b/gio/gio.symbols
index 9a890f4606179a9f68f54595ed051782c034e500..260b2548ed81ee9b45e0a268a193788911625d84 100644 (file)
--- a/gio/gio.symbols
+++ b/gio/gio.symbols
@@ -735,6 +735,7 @@ g_volume_eject
 g_volume_eject_finish
 g_volume_get_identifier
 g_volume_enumerate_identifiers
+g_volume_get_activation_root
 #endif
 #endif
 

diff --git a/gio/gvolume.c b/gio/gvolume.c
index 70005828e05446055ae9b3017d061c826eafaed3..4530701a6eda5f639808f213e1223161858a3444 100644 (file)
--- a/gio/gvolume.c
+++ b/gio/gvolume.c
@@ -516,6 +516,88 @@ g_volume_enumerate_identifiers (GVolume *volume)
   return (* iface->enumerate_identifiers) (volume);
 }
 
+/**
+ * g_volume_get_activation_root:
+ * @volume: a #GVolume
+ *
+ * Gets the activation root for a #GVolume if it is known ahead of
+ * mount time. Returns %NULL otherwise. If not %NULL and if @volume
+ * is mounted, then the result of g_mount_get_root() on the
+ * #GMount object obtained from g_volume_get_mount() will always
+ * either be equal or a prefix of what this function returns. In
+ * other words, in code
+ *
+ * <programlisting>
+ *   GMount *mount;
+ *   GFile *mount_root
+ *   GFile *volume_activation_root;
+ *
+ *   mount = g_volume_get_mount (volume); // mounted, so never NULL
+ *   mount_root = g_mount_get_root (mount);
+ *   volume_activation_root = g_volume_get_activation_root(volume); // assume not NULL
+ * </programlisting>
+ *
+ * then the expression
+ *
+ * <programlisting>
+ *   (g_file_has_prefix (volume_activation_root, mount_root) ||
+      g_file_equal (volume_activation_root, mount_root))
+ * </programlisting>
+ *
+ * will always be %TRUE.
+ *
+ * There is a number of possible uses of this function.
+ *
+ * First, implementations of #GVolumeMonitor can use this method to
+ * determine if a #GMount should be adopted in the implementation of
+ * g_volume_monitor_adopt_orphan_mount() by testing if the result of
+ * this function equals (or has as prefix) the root of the given
+ * #GMount. In particular this is useful in the in-process proxy part
+ * of an out-of-process volume monitor implementation.
+ *
+ * Second, applications such as a file manager can use this to
+ * navigate to the correct root in response to the user navigating to
+ * a server. Now suppose there is a volume monitor for networked
+ * servers that creates #GVolume objects corresponding to the
+ * "favorite servers" (e.g. set up by the user via some "Connect to
+ * Server" dialog). Suppose also that one of the favorite servers is
+ * named "public_html @ fd.o" and the URI is
+ * <literal>sftp://people.freedesktop.org/home/david/public_html</literal>.
+ *
+ * Now, due to the way GIO works, when the corresponding #GVolume is
+ * mounted then a #GMount (typically adopted by the volume monitor)
+ * will appear with the mount root (e.g. the result of
+ * g_mount_get_root())
+ * <literal>sftp://people.freedesktop.org</literal>. However, this
+ * function (g_volume_get_activation_root()) can return a #GFile for
+ * the URI
+ * <literal>sftp://people.freedesktop.org/home/david/public_html</literal>.
+ *
+ * All this means that a file manager can use the latter URI for
+ * navigating when the user clicks an icon representing the #GVolume
+ * (e.g. clicking an icon with the name "public_html @ fd.o" or
+ * similar).
+ *
+ * Returns: the activation root of @volume or %NULL. Use
+ * g_object_unref() to free.
+ *
+ * Since: 2.18
+ **/
+GFile *
+g_volume_get_activation_root (GVolume *volume)
+{
+  GVolumeIface *iface;
+
+  g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
+  iface = G_VOLUME_GET_IFACE (volume);
+
+  if (iface->get_activation_root == NULL)
+    return NULL;
+
+  return (* iface->get_activation_root) (volume);
+}
+
+
 
 #define __G_VOLUME_C__
 #include "gioaliasdef.c"

diff --git a/gio/gvolume.h b/gio/gvolume.h
index 72a74e14ddd9ea4c7560130675abb0661e600200..5631dbd1a457937ef0c65a040128dbcf6b0b3a12 100644 (file)
--- a/gio/gvolume.h
+++ b/gio/gvolume.h
@@ -94,6 +94,8 @@ G_BEGIN_DECLS
  * @enumerate_identifiers: Returns an array strings listing the kinds
  *    of <link linkend="volume-identifier">identifiers</link> which the #GVolume has.
  * @should_automount: Returns %TRUE if the #GVolume should be automatically mounted.
+ * @get_activation_root: Returns the activation root for the #GVolume if it is known in advance or %NULL if
+ *   it is not known.
  * 
  * Interface for implementing operations for mountable volumes.
  **/
@@ -140,6 +142,8 @@ struct _GVolumeIface
   char **  (*enumerate_identifiers)    (GVolume             *volume);
 
   gboolean (*should_automount)         (GVolume             *volume);
+
+  GFile *  (*get_activation_root)      (GVolume             *volume);
   
 };
 
@@ -174,6 +178,8 @@ char *   g_volume_get_identifier        (GVolume              *volume,
                                         const char           *kind);
 char **  g_volume_enumerate_identifiers (GVolume              *volume);
 
+GFile *  g_volume_get_activation_root   (GVolume              *volume);
+
 
 G_END_DECLS