MateVFSDrive

## MateVFSDrive MateVFSDrive — Container for MateVFSVolume (floppy drive, CD reader, ...) |

## Synopsis

    enum                MateVFSDeviceType;
                        MateVFSDrive;
    struct              MateVFSDriveClass;
    #define             MATE_IS_VFS_DRIVE                  (o)
    #define             MATE_IS_VFS_DRIVE_CLASS            (k)
    #define             MATE_VFS_TYPE_DRIVE
    #define             MATE_VFS_DRIVE                     (o)
    #define             MATE_VFS_DRIVE_CLASS               (k)
    gint                mate_vfs_drive_compare             (MateVFSDrive *a,
                                                             MateVFSDrive *b);
    void                mate_vfs_drive_eject               (MateVFSDrive *drive,
                                                             MateVFSVolumeOpCallback callback,
                                                             gpointer user_data);
    char *              mate_vfs_drive_get_activation_uri  (MateVFSDrive *drive);
    char *              mate_vfs_drive_get_device_path     (MateVFSDrive *drive);
    MateVFSDeviceType  mate_vfs_drive_get_device_type     (MateVFSDrive *drive);
    char *              mate_vfs_drive_get_display_name    (MateVFSDrive *drive);
    char *              mate_vfs_drive_get_hal_udi         (MateVFSDrive *drive);
    char *              mate_vfs_drive_get_icon            (MateVFSDrive *drive);
    gulong              mate_vfs_drive_get_id              (MateVFSDrive *drive);
    MateVFSVolume *    mate_vfs_drive_get_mounted_volume  (MateVFSDrive *drive);
    GList *             mate_vfs_drive_get_mounted_volumes (MateVFSDrive *drive);
    void                mate_vfs_drive_volume_list_free    (GList *volumes);
    GType               mate_vfs_drive_get_type            (void);
    gboolean            mate_vfs_drive_is_connected        (MateVFSDrive *drive);
    gboolean            mate_vfs_drive_is_mounted          (MateVFSDrive *drive);
    gboolean            mate_vfs_drive_is_user_visible     (MateVFSDrive *drive);
    void                mate_vfs_drive_mount               (MateVFSDrive *drive,
                                                             MateVFSVolumeOpCallback callback,
                                                             gpointer user_data);
    MateVFSDrive *     mate_vfs_drive_ref                 (MateVFSDrive *drive);
    void                mate_vfs_drive_unmount             (MateVFSDrive *drive,
                                                             MateVFSVolumeOpCallback callback,
                                                             gpointer user_data);
    void                mate_vfs_drive_unref               (MateVFSDrive *drive);

## Object Hierarchy

      GObject
       +----MateVFSDrive

## Signals

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

## Description

## Details

### enum MateVFSDeviceType

    typedef enum {
    	MATE_VFS_DEVICE_TYPE_UNKNOWN,
    	MATE_VFS_DEVICE_TYPE_AUDIO_CD,
    	MATE_VFS_DEVICE_TYPE_VIDEO_DVD,
    	MATE_VFS_DEVICE_TYPE_HARDDRIVE,
    	MATE_VFS_DEVICE_TYPE_CDROM,
    	MATE_VFS_DEVICE_TYPE_FLOPPY,
    	MATE_VFS_DEVICE_TYPE_ZIP,
    	MATE_VFS_DEVICE_TYPE_JAZ,
    	MATE_VFS_DEVICE_TYPE_NFS,
    	MATE_VFS_DEVICE_TYPE_AUTOFS,
    	MATE_VFS_DEVICE_TYPE_CAMERA,
    	MATE_VFS_DEVICE_TYPE_MEMORY_STICK,
    	MATE_VFS_DEVICE_TYPE_SMB,
    	MATE_VFS_DEVICE_TYPE_APPLE,
    	MATE_VFS_DEVICE_TYPE_MUSIC_PLAYER,
    	MATE_VFS_DEVICE_TYPE_WINDOWS,
    	MATE_VFS_DEVICE_TYPE_LOOPBACK,
    	MATE_VFS_DEVICE_TYPE_NETWORK
    } MateVFSDeviceType;

Identifies the device type of a MateVFSVolume or a MateVFSDrive.

`MATE_VFS_DEVICE_TYPE_UNKNOWN` | the type of this MateVFSVolume or MateVFSDrive is not known.
`MATE_VFS_DEVICE_TYPE_AUDIO_CD` | only used for MateVFSVolume objects. Denotes that this volume is an audio CD.
`MATE_VFS_DEVICE_TYPE_VIDEO_DVD` | only used for MateVFSVolume objects. Denotes that this volume is a video DVD.
`MATE_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+).
`MATE_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.
`MATE_VFS_DEVICE_TYPE_FLOPPY` | the volume or drive referenced by this MateVFSVolume or MateVFSDrive is a floppy disc respectively a floppy drive.
`MATE_VFS_DEVICE_TYPE_ZIP` | the volume or drive referenced by this MateVFSVolume or MateVFSDrive is a ZIP disc respectively a ZIP drive.
`MATE_VFS_DEVICE_TYPE_JAZ` | the volume or drive referenced by this MateVFSVolume or MateVFSDrive is a JAZ disc respectively a JAZ drive.
`MATE_VFS_DEVICE_TYPE_NFS` | this is a mount point having an NFS file system.
`MATE_VFS_DEVICE_TYPE_AUTOFS` | this is a mount point having an AutoFS file system.
`MATE_VFS_DEVICE_TYPE_CAMERA` | only used for MateVFSVolume objects. Denotes that this volume is a camera.
`MATE_VFS_DEVICE_TYPE_MEMORY_STICK` | only used for MateVFSVolume objects. Denotes that this volume is a memory stick.
`MATE_VFS_DEVICE_TYPE_SMB` | this is a mount point having a Samba file system.
`MATE_VFS_DEVICE_TYPE_APPLE` | this is a mount point refering to a harddisk partition, that has an Apple file system (HFS, HFS+).
`MATE_VFS_DEVICE_TYPE_MUSIC_PLAYER` | only used for MateVFSVolume objects. Denotes that this volume is a music player.
`MATE_VFS_DEVICE_TYPE_WINDOWS` | this is a mount point refering to a harddisk partition, that has a Microsoft file system (FAT, VFAT, NTFS).
`MATE_VFS_DEVICE_TYPE_LOOPBACK` | this is a mount point refering to a loopback device.
`MATE_VFS_DEVICE_TYPE_NETWORK` | only used for MateVFSVolume objects, denoting that this volume refers to a network mount that is not managed by the kernel VFS but exclusively known to MateVFS.

### MateVFSDrive

    typedef struct _MateVFSDrive MateVFSDrive;

### struct MateVFSDriveClass

    struct MateVFSDriveClass {
    	GObjectClass parent_class;

    	void (* volume_mounted)	  	(MateVFSDrive *drive,
    				   	 MateVFSVolume *volume);
    	void (* volume_pre_unmount) (MateVFSDrive *drive,
    				   	 MateVFSVolume *volume);
    	void (* volume_unmounted) (MateVFSDrive *drive,
    				   	 MateVFSVolume *volume);
    };

### MATE_IS_VFS_DRIVE()

    #define MATE_IS_VFS_DRIVE(o)       (G_TYPE_CHECK_INSTANCE_TYPE ((o), MATE_VFS_TYPE_DRIVE))

`o` : |

### MATE_IS_VFS_DRIVE_CLASS()

    #define MATE_IS_VFS_DRIVE_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), MATE_VFS_TYPE_DRIVE))

`k` : |

### MATE_VFS_TYPE_DRIVE

    #define MATE_VFS_TYPE_DRIVE        (mate_vfs_drive_get_type ())

### MATE_VFS_DRIVE()

    #define MATE_VFS_DRIVE(o)          (G_TYPE_CHECK_INSTANCE_CAST ((o), MATE_VFS_TYPE_DRIVE, MateVFSDrive))

`o` : |

### MATE_VFS_DRIVE_CLASS()

    #define MATE_VFS_DRIVE_CLASS(k)    (G_TYPE_CHECK_CLASS_CAST((k), MATE_VFS_TYPE_DRIVE, MateVFSDriveClass))

`k` : |

### mate_vfs_drive_compare ()

    gint                mate_vfs_drive_compare             (MateVFSDrive *a,
                                                             MateVFSDrive *b);

Compares two MateVFSDrive objects `a` and `b`. Two MateVFSDrive 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 `mate_vfs_drive_get_id()`.

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

Since 2.6

### mate_vfs_drive_eject ()

    void                mate_vfs_drive_eject               (MateVFSDrive *drive,
                                                             MateVFSVolumeOpCallback callback,
                                                             gpointer user_data);

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

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

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

Since 2.6

### mate_vfs_drive_get_activation_uri ()

    char *              mate_vfs_drive_get_activation_uri  (MateVFSDrive *drive);

Returns the activation URI of a MateVFSDrive.

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

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

Since 2.6

### mate_vfs_drive_get_device_path ()

    char *              mate_vfs_drive_get_device_path     (MateVFSDrive *drive);

Returns the device path of a MateVFSDrive.

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 MateVFSDrive.
Returns : | a newly allocated string for the device path of the drive.

Since 2.6

### mate_vfs_drive_get_device_type ()

    MateVFSDeviceType  mate_vfs_drive_get_device_type     (MateVFSDrive *drive);

`drive` : | a MateVFSDrive.
Returns : | device type, a MateVFSDeviceType value.

Since 2.6

### mate_vfs_drive_get_display_name ()

    char *              mate_vfs_drive_get_display_name    (MateVFSDrive *drive);

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

Since 2.6

### mate_vfs_drive_get_hal_udi ()

    char *              mate_vfs_drive_get_hal_udi         (MateVFSDrive *drive);

Returns the HAL UDI of a MateVFSDrive.

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

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

Since 2.6

### mate_vfs_drive_get_icon ()

    char *              mate_vfs_drive_get_icon            (MateVFSDrive *drive);

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

Since 2.6

### mate_vfs_drive_get_id ()

    gulong              mate_vfs_drive_get_id              (MateVFSDrive *drive);

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

Since 2.6

### mate_vfs_drive_get_mounted_volume ()

    MateVFSVolume *    mate_vfs_drive_get_mounted_volume  (MateVFSDrive *drive);

### Warning

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

Returns the first mounted volume for the `drive`.

`drive` : | a MateVFSDrive.
Returns : | a MateVFSVolume.

Since 2.6

### mate_vfs_drive_get_mounted_volumes ()

    GList *             mate_vfs_drive_get_mounted_volumes (MateVFSDrive *drive);

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

Since 2.8

### mate_vfs_drive_volume_list_free ()

    void                mate_vfs_drive_volume_list_free    (GList *volumes);

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

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

Since 2.8

### mate_vfs_drive_get_type ()

    GType               mate_vfs_drive_get_type            (void);

Returns : |

### mate_vfs_drive_is_connected ()

    gboolean            mate_vfs_drive_is_connected        (MateVFSDrive *drive);

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

Since 2.6

### mate_vfs_drive_is_mounted ()

    gboolean            mate_vfs_drive_is_mounted          (MateVFSDrive *drive);

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

Since 2.6

### mate_vfs_drive_is_user_visible ()

    gboolean            mate_vfs_drive_is_user_visible     (MateVFSDrive *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 MateVFSDrive.
Returns : | `TRUE` if the `drive` is visible to the user, `FALSE` otherwise.

Since 2.6

### mate_vfs_drive_mount ()

    void                mate_vfs_drive_mount               (MateVFSDrive *drive,
                                                             MateVFSVolumeOpCallback callback,
                                                             gpointer user_data);

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

Since 2.6

### mate_vfs_drive_ref ()

    MateVFSDrive *     mate_vfs_drive_ref                 (MateVFSDrive *drive);

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

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

Since 2.6

### mate_vfs_drive_unmount ()

    void                mate_vfs_drive_unmount             (MateVFSDrive *drive,
                                                             MateVFSVolumeOpCallback callback,
                                                             gpointer user_data);

`mate_vfs_drive_unmount()` invokes `mate_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 MateVFSDrive `drive`.

If the `drive` does not signal that it should be ejected when it is unmounted, `mate_vfs_drive_unmount()` calls `mate_vfs_volume_unmount()` for each of the `drive`'s mounted MateVFSVolumes, which can be queried using `mate_vfs_drive_get_mounted_volumes()`.

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

Since 2.6

### mate_vfs_drive_unref ()

    void                mate_vfs_drive_unref               (MateVFSDrive *drive);

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

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

Since 2.6

## Signal Details

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

    void                user_function                      (MateVFSDrive  *drive,
                                                            MateVFSVolume *volume,
                                                            gpointer        user_data)      : Run First

This signal is emitted after the MateVFSVolume `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 `mate_vfs_drive_get_mounted_volumes()`.

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

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

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

    void                user_function                      (MateVFSDrive  *drive,
                                                            MateVFSVolume *volume,
                                                            gpointer        user_data)      : Run First

This signal is emitted when the MateVFSVolume `volume`, which has been present in the MateVFSDrive `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 `mate_vfs_drive_get_mounted_volumes()`.

It is also removed from the MateVFSVolumeMonitor's list of mounted volumes, which can be queried using `mate_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 `mate_vfs_monitor_cancel()`.

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

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

    void                user_function                      (MateVFSDrive  *drive,
                                                            MateVFSVolume *volume,
                                                            gpointer        user_data)      : Run First

This signal is emitted after the MateVFSVolume `volume`, which had been present in the MateVFSDrive `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 `mate_vfs_drive_get_mounted_volumes()`.

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

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