gio: Introduce get_sort_key() methods on GDrive, GVolume and GMount

This is needed to implement efficient and predictable proxy volume
monitors, see

 https://bugzilla.gnome.org/show_bug.cgi?id=661711

for details.

Signed-off-by: David Zeuthen <davidz@redhat.com>

docs/reference/gio/gio-sections.txt

@@ -1017,6 +1017,7 @@ g_mount_guess_content_type_sync
 g_mount_is_shadowed
 g_mount_shadow
 g_mount_unshadow
+g_mount_get_sort_key
 <SUBSECTION Standard>
 G_IS_MOUNT
 G_MOUNT
@@ -1053,6 +1054,7 @@ G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
 G_VOLUME_IDENTIFIER_KIND_UUID
 g_volume_enumerate_identifiers
 g_volume_get_identifier
+g_volume_get_sort_key
 <SUBSECTION Standard>
 G_VOLUME
 G_IS_VOLUME
@@ -1094,6 +1096,7 @@ g_drive_stop
 g_drive_stop_finish
 g_drive_enumerate_identifiers
 g_drive_get_identifier
+g_drive_get_sort_key
 <SUBSECTION Standard>
 G_DRIVE
 G_IS_DRIVE

gio/gdrive.c

@@ -869,3 +869,28 @@ g_drive_stop_finish (GDrive        *drive,
 
   return (* iface->stop_finish) (drive, result, error);
 }
+
+/**
+ * g_drive_get_sort_key:
+ * @drive: A #GDrive.
+ *
+ * Gets the sort key for @drive, if any.
+ *
+ * Returns: Sorting key for @drive or %NULL if no such key is available.
+ *
+ * Since: 2.32
+ */
+const gchar *
+g_drive_get_sort_key (GDrive  *drive)
+{
+  const gchar *ret = NULL;
+  GDriveIface *iface;
+
+  g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
+
+  iface = G_DRIVE_GET_IFACE (drive);
+  if (iface->get_sort_key != NULL)
+    ret = iface->get_sort_key (drive);
+
+  return ret;
+}

gio/gdrive.h

@@ -71,6 +71,7 @@ G_BEGIN_DECLS
  * @stop_button: Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22.
  * @eject_with_operation: Starts ejecting a #GDrive using a #GMountOperation. Since 2.22.
  * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
+ * @get_sort_key: Gets a key used for sorting #GDrive instances or %NULL if no such key exists. Since 2.32.
  *
  * Interface for creating #GDrive implementations.
  */
@@ -151,6 +152,8 @@ struct _GDriveIface
   gboolean    (* eject_with_operation_finish) (GDrive            *drive,
                                              GAsyncResult        *result,
                                              GError             **error);
+
+  const gchar * (* get_sort_key)        (GDrive              *drive);
 };
 
 GType    g_drive_get_type                 (void) G_GNUC_CONST;
@@ -223,6 +226,8 @@ gboolean    g_drive_eject_with_operation_finish (GDrive            *drive,
                                                GAsyncResult        *result,
                                                GError             **error);
 
+const gchar *g_drive_get_sort_key         (GDrive               *drive);
+
 G_END_DECLS
 
 #endif /* __G_DRIVE_H__ */

gio/gio.symbols

@@ -233,6 +233,7 @@ g_drive_stop
 g_drive_stop_finish
 g_drive_eject
 g_drive_eject_finish
+g_drive_get_sort_key
 g_file_attribute_info_list_new
 g_file_attribute_info_list_ref
 g_file_attribute_info_list_unref
@@ -704,6 +705,7 @@ g_mount_unmount
 g_mount_unmount_finish
 g_mount_eject
 g_mount_eject_finish
+g_mount_get_sort_key
 g_volume_get_type
 g_volume_get_name
 g_volume_get_icon
@@ -722,6 +724,7 @@ g_volume_enumerate_identifiers
 g_volume_get_activation_root
 g_volume_eject
 g_volume_eject_finish
+g_volume_get_sort_key
 g_volume_monitor_get_type
 g_volume_monitor_get_connected_drives
 g_volume_monitor_get_volume_for_uuid

gio/gmount.c

@@ -1012,3 +1012,28 @@ g_mount_unshadow (GMount *mount)
     g_warning ("Shadow ref count on GMount is negative");
   G_UNLOCK (priv_lock);
 }
+
+/**
+ * g_mount_get_sort_key:
+ * @mount: A #GMount.
+ *
+ * Gets the sort key for @mount, if any.
+ *
+ * Returns: Sorting key for @mount or %NULL if no such key is available.
+ *
+ * Since: 2.32
+ */
+const gchar *
+g_mount_get_sort_key (GMount  *mount)
+{
+  const gchar *ret = NULL;
+  GMountIface *iface;
+
+  g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
+
+  iface = G_MOUNT_GET_IFACE (mount);
+  if (iface->get_sort_key != NULL)
+    ret = iface->get_sort_key (mount);
+
+  return ret;
+}

gio/gmount.h

@@ -69,6 +69,7 @@ typedef struct _GMountIface    GMountIface;
  * @eject_with_operation: Starts ejecting a #GMount using a #GMountOperation. Since 2.22.
  * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
  * @get_default_location: Gets a #GFile indication a start location that can be use as the entry point for this mount. Since 2.24.
+ * @get_sort_key: Gets a key used for sorting #GMount instance or %NULL if no such key exists. Since 2.32.
  *
  * Interface for implementing operations for mounts.
  **/
@@ -156,6 +157,8 @@ struct _GMountIface
                                              GAsyncResult        *result,
                                              GError             **error);
   GFile     * (* get_default_location)      (GMount              *mount);
+
+  const gchar * (* get_sort_key)            (GMount              *mount);
 };
 
 GType       g_mount_get_type                  (void) G_GNUC_CONST;
@@ -243,6 +246,8 @@ gboolean    g_mount_eject_with_operation_finish (GMount            *mount,
                                                GAsyncResult        *result,
                                                GError             **error);
 
+const gchar *g_mount_get_sort_key             (GMount              *mount);
+
 G_END_DECLS
 
 #endif /* __G_MOUNT_H__ */

gio/gvolume.c

@@ -640,3 +640,28 @@ g_volume_get_activation_root (GVolume *volume)
 
   return (* iface->get_activation_root) (volume);
 }
+
+/**
+ * g_volume_get_sort_key:
+ * @volume: A #GVolume.
+ *
+ * Gets the sort key for @volume, if any.
+ *
+ * Returns: Sorting key for @volume or %NULL if no such key is available.
+ *
+ * Since: 2.32
+ */
+const gchar *
+g_volume_get_sort_key (GVolume  *volume)
+{
+  const gchar *ret = NULL;
+  GVolumeIface *iface;
+
+  g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
+
+  iface = G_VOLUME_GET_IFACE (volume);
+  if (iface->get_sort_key != NULL)
+    ret = iface->get_sort_key (volume);
+
+  return ret;
+}

gio/gvolume.h

@@ -101,6 +101,7 @@ G_BEGIN_DECLS
  *   it is not known.
  * @eject_with_operation: Starts ejecting a #GVolume using a #GMountOperation. Since 2.22.
  * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
+ * @get_sort_key: Gets a key used for sorting #GVolume instance or %NULL if no such key exists. Since 2.32.
  *
  * Interface for implementing operations for mountable volumes.
  **/
@@ -159,6 +160,8 @@ struct _GVolumeIface
   gboolean    (* eject_with_operation_finish) (GVolume           *volume,
                                              GAsyncResult        *result,
                                              GError             **error);
+
+  const gchar * (* get_sort_key)        (GVolume             *volume);
 };
 
 GType    g_volume_get_type              (void) G_GNUC_CONST;
@@ -209,6 +212,8 @@ gboolean    g_volume_eject_with_operation_finish (GVolume          *volume,
                                                GAsyncResult        *result,
                                                GError             **error);
 
+const gchar *g_volume_get_sort_key            (GVolume              *volume);
+
 G_END_DECLS
 
 #endif /* __G_VOLUME_H__ */