GnomeVFSDrive

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

Synopsis




enum        GnomeVFSDeviceType;
            GnomeVFSDrive;
            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"
            void        user_function      (GnomeVFSDrive  *drive,
                                            GnomeVFSVolume *volume,
                                            gpointer        user_data)      : Run first
"volume-pre-unmount"
            void        user_function      (GnomeVFSDrive  *drive,
                                            GnomeVFSVolume *volume,
                                            gpointer        user_data)      : Run first
"volume-unmounted"
            void        user_function      (GnomeVFSDrive  *drive,
                                            GnomeVFSVolume *volume,
                                            gpointer        user_data)      : 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;


GnomeVFSDriveClass

typedef struct {
	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);
} GnomeVFSDriveClass;


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.