Interface

GioVolume

Description [src]

interface Gio.Volume : GObject.Object

The GVolume interface represents user-visible objects that can be mounted. For example, a file system partition on a USB flash drive, or an optical disc inserted into a disc drive.

If a GVolume is currently mounted, the corresponding GMount can be retrieved using g_volume_get_mount().

Mounting a GVolume instance is an asynchronous operation. For more information about asynchronous operations, see GAsyncResult and GTask. To mount a GVolume, first call g_volume_mount() with (at least) the GVolume instance, optionally a GMountOperation object and a GAsyncReadyCallback.

Typically, one will only want to pass NULL for the GMountOperation if automounting all volumes when a desktop session starts since it’s not desirable to put up a lot of dialogs asking for credentials.

The callback will be fired when the operation has resolved (either with success or failure), and a GAsyncResult instance will be passed to the callback. That callback should then call g_volume_mount_finish() with the GVolume instance and the GAsyncResult data to see if the operation was completed successfully. If a GError is present when g_volume_mount_finish() is called, then it will be filled with any error information.

Note, when porting from GnomeVFS, GVolume is the moral equivalent of GnomeVFSDrive.

Volume Identifiers

It is sometimes necessary to directly access the underlying operating system object behind a volume (e.g. for passing a volume to an application via the command line). For this purpose, GIO allows to obtain an ‘identifier’ for the volume. There can be different kinds of identifiers, such as Hal UDIs, filesystem labels, traditional Unix devices (e.g. /dev/sda2), UUIDs. GIO uses predefined strings as names for the different kinds of identifiers: G_VOLUME_IDENTIFIER_KIND_UUID, G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier() to obtain an identifier for a volume.

Note that G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available when the GVFS hal volume monitor is in use. Other volume monitors will generally be able to provide the G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE identifier, which can be used to obtain a hal device by means of libhal_manager_find_device_string_match().

Prerequisite

In order to implement Volume, your type must inherit fromGObject.

Instance methods

g_volume_can_eject

Checks if a volume can be ejected.

g_volume_can_mount

Checks if a volume can be mounted.

g_volume_eject

Ejects a volume. This is an asynchronous operation, and is finished by calling g_volume_eject_finish() with the volume and GAsyncResult returned in the callback.

deprecated: 2.22

g_volume_eject_finish

Finishes ejecting a volume. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned.

deprecated: 2.22

g_volume_eject_with_operation

Ejects a volume. This is an asynchronous operation, and is finished by calling g_volume_eject_with_operation_finish() with the volume and GAsyncResult data returned in the callback.

since: 2.22

g_volume_eject_with_operation_finish

Finishes ejecting a volume. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned.

since: 2.22

g_volume_enumerate_identifiers

Gets the kinds of identifiers that volume has. Use g_volume_get_identifier() to obtain the identifiers themselves.

g_volume_get_activation_root

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.

since: 2.18

g_volume_get_drive

Gets the drive for the volume.

g_volume_get_icon

Gets the icon for volume.

g_volume_get_identifier

Gets the identifier of the given kind for volume. See the introduction for more information about volume identifiers.

g_volume_get_mount

Gets the mount for the volume.

g_volume_get_name

Gets the name of volume.

g_volume_get_sort_key

Gets the sort key for volume, if any.

since: 2.32

g_volume_get_symbolic_icon

Gets the symbolic icon for volume.

since: 2.34

g_volume_get_uuid

Gets the UUID for the volume. The reference is typically based on the file system UUID for the volume in question and should be considered an opaque string. Returns NULL if there is no UUID available.

g_volume_mount

Mounts a volume. This is an asynchronous operation, and is finished by calling g_volume_mount_finish() with the volume and GAsyncResult returned in the callback.

g_volume_mount_finish

Finishes mounting a volume. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned.

g_volume_should_automount

Returns whether the volume should be automatically mounted.

Signals

Gio.Volume::changed

Emitted when the volume has been changed.

Gio.Volume::removed

This signal is emitted when the GVolume have been removed. If the recipient is holding references to the object they should release them so the object can be finalized.

Interface structure

struct GioVolumeIface {
  GTypeInterface g_iface;
  void (* changed) (
    GVolume* volume
  );
  void (* removed) (
    GVolume* volume
  );
  char* (* get_name) (
    GVolume* volume
  );
  GIcon* (* get_icon) (
    GVolume* volume
  );
  char* (* get_uuid) (
    GVolume* volume
  );
  GDrive* (* get_drive) (
    GVolume* volume
  );
  GMount* (* get_mount) (
    GVolume* volume
  );
  gboolean (* can_mount) (
    GVolume* volume
  );
  gboolean (* can_eject) (
    GVolume* volume
  );
  void (* mount_fn) (
    GVolume* volume,
    GMountMountFlags flags,
    GMountOperation* mount_operation,
    GCancellable* cancellable,
    GAsyncReadyCallback callback,
    gpointer user_data
  );
  gboolean (* mount_finish) (
    GVolume* volume,
    GAsyncResult* result,
    GError** error
  );
  void (* eject) (
    GVolume* volume,
    GMountUnmountFlags flags,
    GCancellable* cancellable,
    GAsyncReadyCallback callback,
    gpointer user_data
  );
  gboolean (* eject_finish) (
    GVolume* volume,
    GAsyncResult* result,
    GError** error
  );
  char* (* get_identifier) (
    GVolume* volume,
    const char* kind
  );
  char** (* enumerate_identifiers) (
    GVolume* volume
  );
  gboolean (* should_automount) (
    GVolume* volume
  );
  GFile* (* get_activation_root) (
    GVolume* volume
  );
  void (* eject_with_operation) (
    GVolume* volume,
    GMountUnmountFlags flags,
    GMountOperation* mount_operation,
    GCancellable* cancellable,
    GAsyncReadyCallback callback,
    gpointer user_data
  );
  gboolean (* eject_with_operation_finish) (
    GVolume* volume,
    GAsyncResult* result,
    GError** error
  );
  const gchar* (* get_sort_key) (
    GVolume* volume
  );
  GIcon* (* get_symbolic_icon) (
    GVolume* volume
  );
  
}

Interface for implementing operations for mountable volumes.

Interface members

`g_iface`	`GTypeInterface`
	The parent interface.
`changed`	`void (* changed) ( GVolume* volume )`
	Changed signal that is emitted when the volume’s state has changed.
`removed`	`void (* removed) ( GVolume* volume )`
	The removed signal that is emitted when the `GVolume` have been removed. If the recipient is holding references to the object they should release them so the object can be finalized.
`get_name`	`char* (* get_name) ( GVolume* volume )`
	Gets a string containing the name of the `GVolume`.
`get_icon`	`GIcon* (* get_icon) ( GVolume* volume )`
	Gets a `GIcon` for the `GVolume`.
`get_uuid`	`char* (* get_uuid) ( GVolume* volume )`
	Gets the UUID for the `GVolume`. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns `NULL` if there is no UUID available.
`get_drive`	`GDrive* (* get_drive) ( GVolume* volume )`
	Gets a `GDrive` the volume is located on. Returns `NULL` if the `GVolume` is not associated with a `GDrive`.
`get_mount`	`GMount* (* get_mount) ( GVolume* volume )`
	Gets a `GMount` representing the mounted volume. Returns `NULL` if the `GVolume` is not mounted.
`can_mount`	`gboolean (* can_mount) ( GVolume* volume )`
	Returns `TRUE` if the `GVolume` can be mounted.
`can_eject`	`gboolean (* can_eject) ( GVolume* volume )`
	Checks if a `GVolume` can be ejected.
`mount_fn`	`void (* mount_fn) ( GVolume* volume, GMountMountFlags flags, GMountOperation* mount_operation, GCancellable* cancellable, GAsyncReadyCallback callback, gpointer user_data )`
	Mounts a given `GVolume`. `GVolume` implementations must emit the `GMountOperation::aborted` signal before completing a mount operation that is aborted while awaiting input from the user through a `GMountOperation` instance.
`mount_finish`	`gboolean (* mount_finish) ( GVolume* volume, GAsyncResult* result, GError** error )`
	Finishes a mount operation.
`eject`	`void (* eject) ( GVolume* volume, GMountUnmountFlags flags, GCancellable* cancellable, GAsyncReadyCallback callback, gpointer user_data )`
	Ejects a given `GVolume`.
`eject_finish`	`gboolean (* eject_finish) ( GVolume* volume, GAsyncResult* result, GError** error )`
	Finishes an eject operation.
`get_identifier`	`char* (* get_identifier) ( GVolume* volume, const char* kind )`
	Returns the identifier of the given kind, or `NULL` if the `GVolume` doesn’t have one.
`enumerate_identifiers`	`char** (* enumerate_identifiers) ( GVolume* volume )`
	Returns an array strings listing the kinds of identifiers which the `GVolume` has.
`should_automount`	`gboolean (* should_automount) ( GVolume* volume )`
	Returns `TRUE` if the `GVolume` should be automatically mounted.
`get_activation_root`	`GFile* (* get_activation_root) ( GVolume* volume )`
	Returns the activation root for the `GVolume` if it is known in advance or `NULL` if it is not known.
`eject_with_operation`	`void (* eject_with_operation) ( GVolume* volume, GMountUnmountFlags flags, GMountOperation* mount_operation, GCancellable* cancellable, GAsyncReadyCallback callback, gpointer user_data )`
	Starts ejecting a `GVolume` using a `GMountOperation`. Since 2.22.
`eject_with_operation_finish`	`gboolean (* eject_with_operation_finish) ( GVolume* volume, GAsyncResult* result, GError** error )`
	Finishes an eject operation using a `GMountOperation`. Since 2.22.
`get_sort_key`	`const gchar* (* get_sort_key) ( GVolume* volume )`
	Gets a key used for sorting `GVolume` instance or `NULL` if no such key exists. Since 2.32.
`get_symbolic_icon`	`GIcon* (* get_symbolic_icon) ( GVolume* volume )`
	Gets a symbolic `GIcon` for the `GVolume`. Since 2.34.

Virtual methods

Gio.Volume.can_eject

Checks if a volume can be ejected.

Gio.Volume.can_mount

Checks if a volume can be mounted.

Gio.Volume.changed

Changed signal that is emitted when the volume’s state has changed.

Gio.Volume.eject

Ejects a volume. This is an asynchronous operation, and is finished by calling g_volume_eject_finish() with the volume and GAsyncResult returned in the callback.

deprecated: 2.22

Gio.Volume.eject_finish

Finishes ejecting a volume. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned.

deprecated: 2.22

Gio.Volume.eject_with_operation

Ejects a volume. This is an asynchronous operation, and is finished by calling g_volume_eject_with_operation_finish() with the volume and GAsyncResult data returned in the callback.

since: 2.22

Gio.Volume.eject_with_operation_finish

Finishes ejecting a volume. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned.

since: 2.22

Gio.Volume.enumerate_identifiers

Gets the kinds of identifiers that volume has. Use g_volume_get_identifier() to obtain the identifiers themselves.

Gio.Volume.get_activation_root

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.

since: 2.18