## GnomeVFSDrive

GnomeVFSDrive — Container for GnomeVFSVolume (floppy drive, CD reader, ...)

## Synopsis

    enum                GnomeVFSDeviceType;
                        GnomeVFSDrive;
    struct              GnomeVFSDriveClass;
    #define             GNOME_IS_VFS_DRIVE                  (o)
    #define             GNOME_IS_VFS_DRIVE_CLASS            (k)
    #define             GNOME_VFS_TYPE_DRIVE
    #define             GNOME_VFS_DRIVE                     (o)
    #define             GNOME_VFS_DRIVE_CLASS               (k)
    gint                gnome_vfs_drive_compare             (GnomeVFSDrive *a,
                                                             GnomeVFSDrive *b);
    void                gnome_vfs_drive_eject               (GnomeVFSDrive *drive,
                                                             GnomeVFSVolumeOpCallback callback,
                                                             gpointer user_data);
    char *              gnome_vfs_drive_get_activation_uri  (GnomeVFSDrive *drive);
    char *              gnome_vfs_drive_get_device_path     (GnomeVFSDrive *drive);
    GnomeVFSDeviceType  gnome_vfs_drive_get_device_type     (GnomeVFSDrive *drive);
    char *              gnome_vfs_drive_get_display_name    (GnomeVFSDrive *drive);
    char *              gnome_vfs_drive_get_hal_udi         (GnomeVFSDrive *drive);
    char *              gnome_vfs_drive_get_icon            (GnomeVFSDrive *drive);
    gulong              gnome_vfs_drive_get_id              (GnomeVFSDrive *drive);
    GnomeVFSVolume *    gnome_vfs_drive_get_mounted_volume  (GnomeVFSDrive *drive);
    GList *             gnome_vfs_drive_get_mounted_volumes (GnomeVFSDrive *drive);
    void                gnome_vfs_drive_volume_list_free    (GList *volumes);
    GType               gnome_vfs_drive_get_type            (void);
    gboolean            gnome_vfs_drive_is_connected        (GnomeVFSDrive *drive);
    gboolean            gnome_vfs_drive_is_mounted          (GnomeVFSDrive *drive);
    gboolean            gnome_vfs_drive_is_user_visible     (GnomeVFSDrive *drive);
    void                gnome_vfs_drive_mount               (GnomeVFSDrive *drive,
                                                             GnomeVFSVolumeOpCallback callback,
                                                             gpointer user_data);
    GnomeVFSDrive *     gnome_vfs_drive_ref                 (GnomeVFSDrive *drive);
    void                gnome_vfs_drive_unmount             (GnomeVFSDrive *drive,
                                                             GnomeVFSVolumeOpCallback callback,
                                                             gpointer user_data);
    void                gnome_vfs_drive_unref               (GnomeVFSDrive *drive);

## Object Hierarchy

      GObject
       +----GnomeVFSDrive

## Signals

      "volume-mounted"                                 : Run First
      "volume-pre-unmount"                             : Run First
      "volume-unmounted"                               : Run First

## Description

## Details

### enum GnomeVFSDeviceType

    typedef enum {
    	GNOME_VFS_DEVICE_TYPE_UNKNOWN,
    	GNOME_VFS_DEVICE_TYPE_AUDIO_CD,
    	GNOME_VFS_DEVICE_TYPE_VIDEO_DVD,
    	GNOME_VFS_DEVICE_TYPE_HARDDRIVE,
    	GNOME_VFS_DEVICE_TYPE_CDROM,
    	GNOME_VFS_DEVICE_TYPE_FLOPPY,
    	GNOME_VFS_DEVICE_TYPE_ZIP,
    	GNOME_VFS_DEVICE_TYPE_JAZ,
    	GNOME_VFS_DEVICE_TYPE_NFS,
    	GNOME_VFS_DEVICE_TYPE_AUTOFS,
    	GNOME_VFS_DEVICE_TYPE_CAMERA,
    	GNOME_VFS_DEVICE_TYPE_MEMORY_STICK,
    	GNOME_VFS_DEVICE_TYPE_SMB,
    	GNOME_VFS_DEVICE_TYPE_APPLE,
    	GNOME_VFS_DEVICE_TYPE_MUSIC_PLAYER,
    	GNOME_VFS_DEVICE_TYPE_WINDOWS,
    	GNOME_VFS_DEVICE_TYPE_LOOPBACK,
    	GNOME_VFS_DEVICE_TYPE_NETWORK
    } GnomeVFSDeviceType;

Identifies the device type of a GnomeVFSVolume or a GnomeVFSDrive.

`GNOME_VFS_DEVICE_TYPE_UNKNOWN` | the type of this GnomeVFSVolume or GnomeVFSDrive is not known.
`GNOME_VFS_DEVICE_TYPE_AUDIO_CD` | only used for GnomeVFSVolume objects. Denotes that this volume is an audio CD.
`GNOME_VFS_DEVICE_TYPE_VIDEO_DVD` | only used for GnomeVFSVolume objects. Denotes that this volume is a video DVD.
`GNOME_VFS_DEVICE_TYPE_HARDDRIVE` | this is a mount point refering to a harddisk partition that neither has a Microsoft file system (FAT, VFAT, NTFS) nor an Apple file system (HFS, HFS+).
`GNOME_VFS_DEVICE_TYPE_CDROM` | this may either be a mount point or a HAL drive/volume. Either way, it refers to a CD-ROM device respectively volume.
`GNOME_VFS_DEVICE_TYPE_FLOPPY` | the volume or drive referenced by this GnomeVFSVolume or GnomeVFSDrive is a floppy disc respectively a floppy drive.
`GNOME_VFS_DEVICE_TYPE_ZIP` | the volume or drive referenced by this GnomeVFSVolume or GnomeVFSDrive is a ZIP disc respectively a ZIP drive.
`GNOME_VFS_DEVICE_TYPE_JAZ` | the volume or drive referenced by this GnomeVFSVolume or GnomeVFSDrive is a JAZ disc respectively a JAZ drive.
`GNOME_VFS_DEVICE_TYPE_NFS` | this is a mount point having an NFS file system.
`GNOME_VFS_DEVICE_TYPE_AUTOFS` | this is a mount point having an AutoFS file system.
`GNOME_VFS_DEVICE_TYPE_CAMERA` | only used for GnomeVFSVolume objects. Denotes that this volume is a camera.
`GNOME_VFS_DEVICE_TYPE_MEMORY_STICK` | only used for GnomeVFSVolume objects. Denotes that this volume is a memory stick.
`GNOME_VFS_DEVICE_TYPE_SMB` | this is a mount point having a Samba file system.
`GNOME_VFS_DEVICE_TYPE_APPLE` | this is a mount point refering to a harddisk partition, that has an Apple file system (HFS, HFS+).
`GNOME_VFS_DEVICE_TYPE_MUSIC_PLAYER` | only used for GnomeVFSVolume objects. Denotes that this volume is a music player.
`GNOME_VFS_DEVICE_TYPE_WINDOWS` | this is a mount point refering to a harddisk partition, that has a Microsoft file system (FAT, VFAT, NTFS).
`GNOME_VFS_DEVICE_TYPE_LOOPBACK` | this is a mount point refering to a loopback device.
`GNOME_VFS_DEVICE_TYPE_NETWORK` | only used for GnomeVFSVolume objects, denoting that this volume refers to a network mount that is not managed by the kernel VFS but exclusively known to GnomeVFS.

### GnomeVFSDrive

    typedef struct _GnomeVFSDrive GnomeVFSDrive;

### struct GnomeVFSDriveClass

    struct GnomeVFSDriveClass {
    	GObjectClass parent_class;

    	void (* volume_mounted)	  	(GnomeVFSDrive *drive,
    				   	 GnomeVFSVolume *volume);
    	void (* volume_pre_unmount) (GnomeVFSDrive *drive,
    				   	 GnomeVFSVolume *volume);
    	void (* volume_unmounted) (GnomeVFSDrive *drive,
    				   	 GnomeVFSVolume *volume);
    };

### GNOME_IS_VFS_DRIVE()

    #define GNOME_IS_VFS_DRIVE(o)       (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNOME_VFS_TYPE_DRIVE))

`o` : |

### GNOME_IS_VFS_DRIVE_CLASS()

    #define GNOME_IS_VFS_DRIVE_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), GNOME_VFS_TYPE_DRIVE))

`k` : |

### GNOME_VFS_TYPE_DRIVE

    #define GNOME_VFS_TYPE_DRIVE        (gnome_vfs_drive_get_type ())

### GNOME_VFS_DRIVE()

    #define GNOME_VFS_DRIVE(o)          (G_TYPE_CHECK_INSTANCE_CAST ((o), GNOME_VFS_TYPE_DRIVE, GnomeVFSDrive))

`o` : |

### GNOME_VFS_DRIVE_CLASS()

    #define GNOME_VFS_DRIVE_CLASS(k)    (G_TYPE_CHECK_CLASS_CAST((k), GNOME_VFS_TYPE_DRIVE, GnomeVFSDriveClass))

`k` : |

### gnome_vfs_drive_compare ()

    gint                gnome_vfs_drive_compare             (GnomeVFSDrive *a,
                                                             GnomeVFSDrive *b);

Compares two GnomeVFSDrive objects `a` and `b`. Two GnomeVFSDrive objects referring to different drives are guaranteed to not return 0 when comparing them, if they refer to the same drive 0 is returned.

The resulting gint should be used to determine the order in which `a` and `b` are displayed in graphical user interfces.

The comparison algorithm first of all peeks the device type of `a` and `b`, they will be sorted in the following order:

- Magnetic and opto-magnetic drives (ZIP, floppy)

- Optical drives (CD, DVD)

- External drives (USB sticks, music players)

- Mounted hard disks<

- Other drives<

Afterwards, the display name of `a` and `b` is compared using a locale-sensitive sorting algorithm, which involves `g_utf8_collate_key()`.

If two drives have the same display name, their unique ID is compared which can be queried using `gnome_vfs_drive_get_id()`.

`a` : | a GnomeVFSDrive.
`b` : | a GnomeVFSDrive.
Returns : | 0 if the drives refer to the same `GnomeVFSDrive`, a negative value if `a` should be displayed before `b`, or a positive value if `a` should be displayed after `b`.

Since 2.6

### gnome_vfs_drive_eject ()

    void                gnome_vfs_drive_eject               (GnomeVFSDrive *drive,
                                                             GnomeVFSVolumeOpCallback callback,
                                                             gpointer user_data);

If `drive` has associated GnomeVFSVolume objects, all of them will be unmounted by calling `gnome_vfs_volume_unmount()` for each volume in `gnome_vfs_drive_get_mounted_volumes()`, except for the last one, for which `gnome_vfs_volume_eject()` is called to ensure that the `drive`'s media is ejected.

If `drive` however has no associated GnomeVFSVolume objects, it simply calls an unmount helper on the `drive`.

`drive` : | the GnomeVFSDrive that should be ejcted.
`callback` : | the GnomeVFSVolumeOpCallback that should be invoked after ejecting `drive`.
`user_data` : | the user data to pass to `callback`.

Since 2.6

### gnome_vfs_drive_get_activation_uri ()

    char *              gnome_vfs_drive_get_activation_uri  (GnomeVFSDrive *drive);

Returns the activation URI of a GnomeVFSDrive.

The returned URI usually refers to a valid location. You can check the validity of the location by calling `gnome_vfs_uri_new()` with the URI, and checking whether the return value is not `NULL`.

`drive` : | a GnomeVFSDrive.
Returns : | a newly allocated string for the activation uri of the drive.

Since 2.6

### gnome_vfs_drive_get_device_path ()

    char *              gnome_vfs_drive_get_device_path     (GnomeVFSDrive *drive);

Returns the device path of a GnomeVFSDrive.

For HAL drives, this returns the value of the drives's "block.device" key. For UNIX mounts, it returns the `mntent`'s `mnt_fsname` entry.

Otherwise, it returns `NULL`.

`drive` : | a GnomeVFSDrive.
Returns : | a newly allocated string for the device path of the drive.

Since 2.6

### gnome_vfs_drive_get_device_type ()

    GnomeVFSDeviceType  gnome_vfs_drive_get_device_type     (GnomeVFSDrive *drive);

`drive` : | a GnomeVFSDrive.
Returns : | device type, a GnomeVFSDeviceType value.

Since 2.6

### gnome_vfs_drive_get_display_name ()

    char *              gnome_vfs_drive_get_display_name    (GnomeVFSDrive *drive);

`drive` : | a GnomeVFSDrive.
Returns : | a newly allocated string for the display name of the `drive`.

Since 2.6

### gnome_vfs_drive_get_hal_udi ()

    char *              gnome_vfs_drive_get_hal_udi         (GnomeVFSDrive *drive);

Returns the HAL UDI of a GnomeVFSDrive.

For HAL drives, this matches the value of the "info.udi" key, for other drives it is `NULL`.

`drive` : | a GnomeVFSDrive.
Returns : | a newly allocated string for the unique device id of the `drive`, or `NULL`.

Since 2.6

### gnome_vfs_drive_get_icon ()

    char *              gnome_vfs_drive_get_icon            (GnomeVFSDrive *drive);

`drive` : | a GnomeVFSDrive.
Returns : | a newly allocated string for the icon filename of the `drive`.

Since 2.6

### gnome_vfs_drive_get_id ()

    gulong              gnome_vfs_drive_get_id              (GnomeVFSDrive *drive);

`drive` : | a GnomeVFSDrive.
Returns : | drive id, a gulong value.

Since 2.6

### gnome_vfs_drive_get_mounted_volume ()

    GnomeVFSVolume *    gnome_vfs_drive_get_mounted_volume  (GnomeVFSDrive *drive);

### Warning

`gnome_vfs_drive_get_mounted_volume` is deprecated and should not be used in newly-written code. Use `gnome_vfs_drive_get_mounted_volumes()` instead.

Returns the first mounted volume for the `drive`.

`drive` : | a GnomeVFSDrive.
Returns : | a GnomeVFSVolume.

Since 2.6

### gnome_vfs_drive_get_mounted_volumes ()

    GList *             gnome_vfs_drive_get_mounted_volumes (GnomeVFSDrive *drive);

`drive` : | a GnomeVFSDrive.
Returns : | list of mounted volumes for the `drive`.

Since 2.8

### gnome_vfs_drive_volume_list_free ()

    void                gnome_vfs_drive_volume_list_free    (GList *volumes);

Frees the list `volumes`, if it is not `NULL`.

`volumes` : | list of GnomeVFSVolumes to be freed, or `NULL`.

Since 2.8

### gnome_vfs_drive_get_type ()

    GType               gnome_vfs_drive_get_type            (void);

Returns : |

### gnome_vfs_drive_is_connected ()

    gboolean            gnome_vfs_drive_is_connected        (GnomeVFSDrive *drive);

`drive` : | a GnomeVFSDrive.
Returns : | `TRUE` if the `drive` is connected, `FALSE` otherwise.

Since 2.6

### gnome_vfs_drive_is_mounted ()

    gboolean            gnome_vfs_drive_is_mounted          (GnomeVFSDrive *drive);

`drive` : | a GnomeVFSDrive.
Returns : | `TRUE` if the `drive` is mounted, `FALSE` otherwise.

Since 2.6

### gnome_vfs_drive_is_user_visible ()

    gboolean            gnome_vfs_drive_is_user_visible     (GnomeVFSDrive *drive);

Returns whether the `drive` is visible to the user. This should be used by applications to determine whether it is included in user interfaces listing available drives.

`drive` : | a GnomeVFSDrive.
Returns : | `TRUE` if the `drive` is visible to the user, `FALSE` otherwise.

Since 2.6

### gnome_vfs_drive_mount ()

    void                gnome_vfs_drive_mount               (GnomeVFSDrive *drive,
                                                             GnomeVFSVolumeOpCallback callback,
                                                             gpointer user_data);

`drive` : | the GnomeVFSDrive that should be mounted.
`callback` : | the GnomeVFSVolumeOpCallback that should be invoked after mounting `drive`.
`user_data` : | the user data to pass to `callback`.

Since 2.6

### gnome_vfs_drive_ref ()

    GnomeVFSDrive *     gnome_vfs_drive_ref                 (GnomeVFSDrive *drive);

Increases the refcount of the `drive` by 1, if it is not `NULL`.

`drive` : | a GnomeVFSDrive, or `NULL`.
Returns : | the `drive` with its refcount increased by one, or `NULL` if `drive` is `NULL`.

Since 2.6

### gnome_vfs_drive_unmount ()

    void                gnome_vfs_drive_unmount             (GnomeVFSDrive *drive,
                                                             GnomeVFSVolumeOpCallback callback,
                                                             gpointer user_data);

`gnome_vfs_drive_unmount()` invokes `gnome_vfs_drive_eject()`, if the `drive` signals that it should be ejected when it is unmounted. This may be true for CD-ROMs, USB sticks and other devices, depending on the backend providing the GnomeVFSDrive `drive`.

If the `drive` does not signal that it should be ejected when it is unmounted, `gnome_vfs_drive_unmount()` calls `gnome_vfs_volume_unmount()` for each of the `drive`'s mounted GnomeVFSVolumes, which can be queried using `gnome_vfs_drive_get_mounted_volumes()`.

`drive` : | the GnomeVFSDrive that should be unmounted.
`callback` : | the GnomeVFSVolumeOpCallback that should be invoked after unmounting `drive`.
`user_data` : | the user data to pass to `callback`.

Since 2.6

### gnome_vfs_drive_unref ()

    void                gnome_vfs_drive_unref               (GnomeVFSDrive *drive);

Decreases the refcount of the `drive` by 1, if it is not `NULL`.

`drive` : | a GnomeVFSDrive, or `NULL`.

Since 2.6

## Signal Details

### The `"volume-mounted"` signal

    void                user_function                      (GnomeVFSDrive  *drive,
                                                            GnomeVFSVolume *volume,
                                                            gpointer        user_data)      : Run First

This signal is emitted after the GnomeVFSVolume `volume` has been mounted.

When the `volume` is mounted, it is added to the `drive`'s list of mounted volumes, which can be queried using `gnome_vfs_drive_get_mounted_volumes()`.

It is also added to the list of the GnomeVFSVolumeMonitor's list of mounted volumes, which can be queried using `gnome_vfs_volume_monitor_get_mounted_volumes()`.

`drive` : | the GnomeVFSDrive which received the signal.
`volume` : | the GnomeVFSVolume that has been mounted.
`user_data` : | user data set when the signal handler was connected.

### The `"volume-pre-unmount"` signal

    void                user_function                      (GnomeVFSDrive  *drive,
                                                            GnomeVFSVolume *volume,
                                                            gpointer        user_data)      : Run First

This signal is emitted when the GnomeVFSVolume `volume`, which has been present in the GnomeVFSDrive `drive`, is about to be unmounted.

When the `volume` is unmounted, it is removed from the `drive`'s list of mounted volumes, which can be queried using `gnome_vfs_drive_get_mounted_volumes()`.

It is also removed from the GnomeVFSVolumeMonitor's list of mounted volumes, which can be queried using `gnome_vfs_volume_monitor_get_mounted_volumes()`.

When a client application receives this signal, it must free all resources associated with the `volume`, for instance cancel all pending file operations on the `volume`, and cancel all pending file monitors using `gnome_vfs_monitor_cancel()`.

`drive` : | the GnomeVFSDrive which received the signal.
`volume` : | the GnomeVFSVolume that is about to be unmounted.
`user_data` : | user data set when the signal handler was connected.

### The `"volume-unmounted"` signal

    void                user_function                      (GnomeVFSDrive  *drive,
                                                            GnomeVFSVolume *volume,
                                                            gpointer        user_data)      : Run First

This signal is emitted after the GnomeVFSVolume `volume`, which had been present in the GnomeVFSDrive `drive`, has been unmounted.

When the `volume` is unmounted, it is removed from the `drive`'s list of mounted volumes, which can be queried using `gnome_vfs_drive_get_mounted_volumes()`.

It is also removed from the GnomeVFSVolumeMonitor's list of mounted volumes, which can be queried using `gnome_vfs_volume_monitor_get_mounted_volumes()`.

`drive` : | the GnomeVFSDrive which received the signal.
`volume` : | the GnomeVFSVolume that has been unmounted.
`user_data` : | user data set when the signal handler was connected.