GnomeVFSVolume

GnomeVFSVolume — Abstraction for a mounted file system or a network location.

Synopsis

#define             GNOME_IS_VFS_VOLUME                 (o)
#define             GNOME_IS_VFS_VOLUME_CLASS           (k)
#define             GNOME_VFS_TYPE_VOLUME
#define             GNOME_VFS_VOLUME                    (o)
#define             GNOME_VFS_VOLUME_CLASS              (k)
                    GnomeVFSVolume;
                    GnomeVFSVolumeClass;
void                (*GnomeVFSVolumeOpCallback)         (gboolean succeeded,
                                                         char *error,
                                                         char *detailed_error,
                                                         gpointer user_data);
enum                GnomeVFSVolumeType;
gint                gnome_vfs_volume_compare            (GnomeVFSVolume *a,
                                                         GnomeVFSVolume *b);
void                gnome_vfs_volume_eject              (GnomeVFSVolume *volume,
                                                         GnomeVFSVolumeOpCallback callback,
                                                         gpointer user_data);
char *              gnome_vfs_volume_get_activation_uri (GnomeVFSVolume *volume);
char *              gnome_vfs_volume_get_device_path    (GnomeVFSVolume *volume);
GnomeVFSDeviceType  gnome_vfs_volume_get_device_type    (GnomeVFSVolume *volume);
char *              gnome_vfs_volume_get_display_name   (GnomeVFSVolume *volume);
GnomeVFSDrive *     gnome_vfs_volume_get_drive          (GnomeVFSVolume *volume);
char *              gnome_vfs_volume_get_filesystem_type
                                                        (GnomeVFSVolume *volume);
char *              gnome_vfs_volume_get_hal_udi        (GnomeVFSVolume *volume);
char *              gnome_vfs_volume_get_icon           (GnomeVFSVolume *volume);
gulong              gnome_vfs_volume_get_id             (GnomeVFSVolume *volume);
GType               gnome_vfs_volume_get_type           (void);
GnomeVFSVolumeType  gnome_vfs_volume_get_volume_type    (GnomeVFSVolume *volume);
gboolean            gnome_vfs_volume_handles_trash      (GnomeVFSVolume *volume);
gboolean            gnome_vfs_volume_is_mounted         (GnomeVFSVolume *volume);
gboolean            gnome_vfs_volume_is_read_only       (GnomeVFSVolume *volume);
gboolean            gnome_vfs_volume_is_user_visible    (GnomeVFSVolume *volume);
GnomeVFSVolume *    gnome_vfs_volume_ref                (GnomeVFSVolume *volume);
GType               gnome_vfs_volume_type_get_type      (void);
void                gnome_vfs_volume_unmount            (GnomeVFSVolume *volume,
                                                         GnomeVFSVolumeOpCallback callback,
                                                         gpointer user_data);
void                gnome_vfs_volume_unref              (GnomeVFSVolume *volume);
void                gnome_vfs_connect_to_server         (const char *uri,
                                                         const char *display_name,
                                                         const char *icon);

Object Hierarchy

  GObject
   +----GnomeVFSVolume

Description

Details

GNOME_IS_VFS_VOLUME()

#define GNOME_IS_VFS_VOLUME(o)       (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNOME_VFS_TYPE_VOLUME))

o :


GNOME_IS_VFS_VOLUME_CLASS()

#define GNOME_IS_VFS_VOLUME_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), GNOME_VFS_TYPE_VOLUME))

k :


GNOME_VFS_TYPE_VOLUME

#define GNOME_VFS_TYPE_VOLUME        (gnome_vfs_volume_get_type ())


GNOME_VFS_VOLUME()

#define GNOME_VFS_VOLUME(o)          (G_TYPE_CHECK_INSTANCE_CAST ((o), GNOME_VFS_TYPE_VOLUME, GnomeVFSVolume))

o :


GNOME_VFS_VOLUME_CLASS()

#define GNOME_VFS_VOLUME_CLASS(k)    (G_TYPE_CHECK_CLASS_CAST((k), GNOME_VFS_TYPE_VOLUME, GnomeVFSVolumeClass))

k :


GnomeVFSVolume

typedef struct _GnomeVFSVolume GnomeVFSVolume;


GnomeVFSVolumeClass

typedef struct {
	GObjectClass parent_class;
} GnomeVFSVolumeClass;


GnomeVFSVolumeOpCallback ()

void                (*GnomeVFSVolumeOpCallback)         (gboolean succeeded,
                                                         char *error,
                                                         char *detailed_error,
                                                         gpointer user_data);

Note that if succeeded is FALSE and error, detailed_error are both empty strings the client is not supposed to display a dialog as an external mount/umount/eject helper will have done so.

succeeded :

whether the volume operation succeeded

error :

a string identifying the error that occurred, if succeeded is FALSE. Otherwise NULL.

detailed_error :

a string more specifically identifying the error that occurred, if succeeded is FALSE. Otherwise NULL.

user_data :

the user data that was passed when registering the callback.

Since 2.6


enum GnomeVFSVolumeType

typedef enum {
	GNOME_VFS_VOLUME_TYPE_MOUNTPOINT,
	GNOME_VFS_VOLUME_TYPE_VFS_MOUNT,
	GNOME_VFS_VOLUME_TYPE_CONNECTED_SERVER
} GnomeVFSVolumeType;


gnome_vfs_volume_compare ()

gint                gnome_vfs_volume_compare            (GnomeVFSVolume *a,
                                                         GnomeVFSVolume *b);

Compares two GnomeVFSVolume objects a and b. Two GnomeVFSVolume objects referring to different volumes are guaranteed to not return 0 when comparing them, if they refer to the same volume 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 volumes (ZIP, floppy)

  • Optical volumes (CD, DVD)

  • External volumes (USB sticks, music players)

  • Mounted hard disks

  • Network mounts

  • Other volumes

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

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

a :

a GnomeVFSVolume.

b :

a GnomeVFSVolume.

Returns :

0 if the volumes refer to the same GnomeVFSVolume, 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_volume_eject ()

void                gnome_vfs_volume_eject              (GnomeVFSVolume *volume,
                                                         GnomeVFSVolumeOpCallback callback,
                                                         gpointer user_data);

Requests ejection of a GnomeVFSVolume.

Before the unmount operation is executed, the "pre-unmount" signal is emitted.

If the volume is a mount point (its type is GNOME_VFS_VOLUME_TYPE_MOUNTPOINT), it is unmounted, and if it refers to a disc, it is also ejected.

If the volume is a special VFS mount, i.e. its type is GNOME_VFS_VOLUME_TYPE_VFS_MOUNT, it is ejected.

If the volume is a connected server, it is removed from the list of connected servers.

Otherwise, no further action is done.

volume :

the GnomeVFSVolume that should be ejected.

callback :

the GnomeVFSVolumeOpCallback that should be invoked after ejecting of volume.

user_data :

the user data to pass to callback.

Since 2.6


gnome_vfs_volume_get_activation_uri ()

char *              gnome_vfs_volume_get_activation_uri (GnomeVFSVolume *volume);

Returns the activation URI of a GnomeVFSVolume.

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.

volume :

a GnomeVFSVolume.

Returns :

a newly allocated string for activation uri of volume.

Since 2.6


gnome_vfs_volume_get_device_path ()

char *              gnome_vfs_volume_get_device_path    (GnomeVFSVolume *volume);

Returns the device path of a GnomeVFSVolume.

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

Otherwise, it returns NULL.

volume :

a GnomeVFSVolume.

Returns :

a newly allocated string for device path of volume.

Since 2.6


gnome_vfs_volume_get_device_type ()

GnomeVFSDeviceType  gnome_vfs_volume_get_device_type    (GnomeVFSVolume *volume);

Returns the GnomeVFSDeviceType of the volume.

volume :

a GnomeVFSVolume.

Returns :

the device type for volume.

Since 2.6


gnome_vfs_volume_get_display_name ()

char *              gnome_vfs_volume_get_display_name   (GnomeVFSVolume *volume);

Returns the display name of the volume.

volume :

a GnomeVFSVolume.

Returns :

a newly allocated string for display name of volume.

Since 2.6


gnome_vfs_volume_get_drive ()

GnomeVFSDrive *     gnome_vfs_volume_get_drive          (GnomeVFSVolume *volume);

volume :

a GnomeVFSVolume.

Returns :

the drive for the volume.

Since 2.6


gnome_vfs_volume_get_filesystem_type ()

char *              gnome_vfs_volume_get_filesystem_type
                                                        (GnomeVFSVolume *volume);

Returns a string describing the file system on volume, or NULL if no information on the underlying file system is available.

The file system may be used to provide special functionality that depends on the file system type, for instance to determine whether trashing is supported (cf. gnome_vfs_volume_handles_trash()).

For HAL mounts, this returns the value of the "volume.fstype" key, for traditional UNIX mounts it is set to the mntent's mnt_type key, for connected servers, NULL is returned.

As of GnomeVFS 2.15.4, the following file systems are recognized by GnomeVFS:

Table 3. Recognized File Systems

File System Display Name Supports Trash
affs AFFS Volume No
afs AFS Network Volume No
auto Auto-detected Volume No
cd9660 CD-ROM Drive No
cdda CD Digital Audio No
cdrom CD-ROM Drive No
devfs Hardware Device Volume No
encfs EncFS Volume Yes
ext2 Ext2 Linux Volume Yes
ext2fs Ext2 Linux Volume Yes
ext3 Ext3 Linux Volume Yes
fat MSDOS Volume Yes
ffs BSD Volume Yes
fuse FUSE Volume Yes
hfs MacOS Volume Yes
hfsplus MacOS Volume No
iso9660 CDROM Volume No
hsfs Hsfs CDROM Volume No
jfs JFS Volume Yes
hpfs Windows NT Volume No
kernfs System Volume No
lfs BSD Volume Yes
linprocfs System Volume No
mfs Memory Volume Yes
minix Minix Volume No
msdos MSDOS Volume No
msdosfs MSDOS Volume No
nfs NFS Network Volume Yes
ntfs Windows NT Volume No
nwfs Netware Volume No
proc System Volume No
procfs System Volume No
ptyfs System Volume No
reiser4 Reiser4 Linux Volume Yes
reiserfs ReiserFS Linux Volume Yes
smbfs Windows Shared Volume Yes
supermount SuperMount Volume No
udf DVD Volume No
ufs Solaris/BSD Volume Yes
udfs Udfs Solaris Volume Yes
pcfs Pcfs Solaris Volume Yes
samfs Sun SAM-QFS Volume Yes
tmpfs Temporary Volume Yes
umsdos Enhanced DOS Volume No
vfat Windows VFAT Volume Yes
xenix Xenix Volume No
xfs XFS Linux Volume Yes
xiafs XIAFS Volume No
cifs CIFS Volume Yes


volume :

a GnomeVFSVolume.

Returns :

a newly allocated string for filesystem type of volume.

Since 2.6


gnome_vfs_volume_get_hal_udi ()

char *              gnome_vfs_volume_get_hal_udi        (GnomeVFSVolume *volume);

Returns the HAL UDI of a GnomeVFSVolume.

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

volume :

a GnomeVFSVolume.

Returns :

a newly allocated string for unique device id of volume, or NULL.

Since 2.6


gnome_vfs_volume_get_icon ()

char *              gnome_vfs_volume_get_icon           (GnomeVFSVolume *volume);

volume :

a GnomeVFSVolume.

Returns :

a newly allocated string for the icon filename of volume.

Since 2.6


gnome_vfs_volume_get_id ()

gulong              gnome_vfs_volume_get_id             (GnomeVFSVolume *volume);

Returns the ID of the volume,

Two GnomeVFSVolumes are guaranteed to refer to the same volume if they have the same ID.

volume :

a GnomeVFSVolume.

Returns :

the id for the volume.

Since 2.6


gnome_vfs_volume_get_type ()

GType               gnome_vfs_volume_get_type           (void);

Returns :


gnome_vfs_volume_get_volume_type ()

GnomeVFSVolumeType  gnome_vfs_volume_get_volume_type    (GnomeVFSVolume *volume);

Returns the GnomeVFSVolumeType of the volume.

volume :

a GnomeVFSVolume.

Returns :

the volume type for volume.

Since 2.6


gnome_vfs_volume_handles_trash ()

gboolean            gnome_vfs_volume_handles_trash      (GnomeVFSVolume *volume);

Returns whether the file system on a volume supports trashing of files.

If the volume has an AutoFS file system (i.e. gnome_vfs_volume_get_device_type() returns GNOME_VFS_DEVICE_TYPE_AUTOFS), or if the volume is mounted read-only (gnome_vfs_volume_is_read_only() returns TRUE), it is assumed to not support trashing of files.

Otherwise, if the volume provides file system information, it is determined whether the file system supports trashing of files. See gnome_vfs_volume_get_filesystem_type() for details which volumes provide file system information, and which file systems currently support a trash.

volume :

a GnomeVFSVolume.

Returns :

TRUE if volume handles trash, FALSE otherwise.

Since 2.6


gnome_vfs_volume_is_mounted ()

gboolean            gnome_vfs_volume_is_mounted         (GnomeVFSVolume *volume);

Returns whether the file system on a volume is currently mounted.

For HAL volumes, this reflects the value of the "volume.is_mounted" key, for traditional UNIX mounts and connected servers, TRUE is returned, because their existence implies that they are mounted.

volume :

a GnomeVFSVolume.

Returns :

TRUE if the volume is mounted, FALSE otherwise.

Since 2.6


gnome_vfs_volume_is_read_only ()

gboolean            gnome_vfs_volume_is_read_only       (GnomeVFSVolume *volume);

Returns whether the file system on a volume is read-only.

For HAL volumes, the "volume.is_mounted_read_only" key is authoritative, for traditional UNIX mounts it returns TRUE if the mount was done with the "ro" option. For servers, FALSE is returned.

volume :

a GnomeVFSVolume.

Returns :

TRUE if the volume is read-only to the user, FALSE otherwise.

Since 2.6


gnome_vfs_volume_is_user_visible ()

gboolean            gnome_vfs_volume_is_user_visible    (GnomeVFSVolume *volume);

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

volume :

a GnomeVFSVolume.

Returns :

TRUE if volume is visible to the user, FALSE otherwise.

Since 2.6


gnome_vfs_volume_ref ()

GnomeVFSVolume *    gnome_vfs_volume_ref                (GnomeVFSVolume *volume);

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

volume :

a GnomeVFSVolume, or NULL.

Returns :

the volume with its refcount increased by one, or NULL if volume is NULL.

Since 2.6


gnome_vfs_volume_type_get_type ()

GType               gnome_vfs_volume_type_get_type      (void);

Returns :


gnome_vfs_volume_unmount ()

void                gnome_vfs_volume_unmount            (GnomeVFSVolume *volume,
                                                         GnomeVFSVolumeOpCallback callback,
                                                         gpointer user_data);

Note that gnome_vfs_volume_unmount() may also invoke gnome_vfs_volume_eject(), if the volume 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 volume.

volume :

the GnomeVFSVolume that should be unmounted.

callback :

the GnomeVFSVolumeOpCallback that should be invoked after unmounting volume.

user_data :

the user data to pass to callback.

Since 2.6


gnome_vfs_volume_unref ()

void                gnome_vfs_volume_unref              (GnomeVFSVolume *volume);

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

volume :

a GnomeVFSVolume, or NULL.

Since 2.6


gnome_vfs_connect_to_server ()

void                gnome_vfs_connect_to_server         (const char *uri,
                                                         const char *display_name,
                                                         const char *icon);

This function adds a server connection to the specified uri, which is displayed in user interfaces with the specified display_name and icon.

If this function is invoked successfully, the created server shows up in the list of mounted volumes of the GnomeVFSVolumeMonitor, which can be queried using gnome_vfs_volume_monitor_get_mounted_volumes().

Note

This function does not have a return value. Hence, you can't easily detect whether the specified server was successfully created. The actual creation and consumption of the new server through the GnomeVFSVolumeMonitor is done asynchronously.

uri, display_name, and icon can be freely chosen, but should be meaningful:

uri should refer to a valid location. You can check the validity of the location by calling gnome_vfs_uri_new() with uri, and checking whether the return value is not NULL.

The display_name should be queried from the user, and an empty string should not be considered valid.

icon typically references an icon from the icon theme. Some implementations currently use gnome-fs-smb, gnome-fs-ssh, gnome-fs-ftp and gnome-fs-share, depending on the type of the server referenced by uri. The icon naming conventions might change in the future, though. Obeying the freedesktop.org Icon Naming Specification is suggested.

uri :

The string representation of the server to connect to.

display_name :

The display name that is used to identify the server connection.

icon :

The icon that is used to identify the server connection.

Since 2.6