GnomeVFSVolume

## 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 GnomeVFSVolume::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