Index: gio/ChangeLog
===================================================================
--- gio/ChangeLog	(revision 7168)
+++ gio/ChangeLog	(working copy)
@@ -1,5 +1,12 @@
 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]:
 	* gunionvolumemonitor.c: Export the eject-button signal on the
 	volume monitor class (#541794).
Index: gio/gvolume.c
===================================================================
--- gio/gvolume.c	(revision 7168)
+++ gio/gvolume.c	(working copy)
@@ -516,6 +516,85 @@
   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 #GMount should be adopted in the implementation of
+ * g_volume_monitor_adopt_orphan_mount() - 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>.
+ * 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"
Index: gio/gvolume.h
===================================================================
--- gio/gvolume.h	(revision 7168)
+++ gio/gvolume.h	(working copy)
@@ -94,6 +94,8 @@
  * @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 @@
   char **  (*enumerate_identifiers)    (GVolume             *volume);
 
   gboolean (*should_automount)         (GVolume             *volume);
+
+  GFile *  (*get_activation_root)      (GVolume             *volume);
   
 };
 
@@ -174,7 +178,9 @@
 					 const char           *kind);
 char **  g_volume_enumerate_identifiers (GVolume              *volume);
 
+GFile *  g_volume_get_activation_root   (GVolume              *volume);
 
+
 G_END_DECLS
 
 #endif /* __G_VOLUME_H__ */
Index: gio/gio.symbols
===================================================================
--- gio/gio.symbols	(revision 7168)
+++ gio/gio.symbols	(working copy)
@@ -735,6 +735,7 @@
 g_volume_eject_finish
 g_volume_get_identifier
 g_volume_enumerate_identifiers
+g_volume_get_activation_root
 #endif
 #endif
 
