A Gentle Programming Primer

Using GnomeVFS in an existing application, or writing a new application with it, is actually very simple since GnomeVFS tries to mimic POSIX file access syntax and semantics. That means that most "standard unix calls" have a GnomeVFS equivalent that operates in a fairly similar manner. There are a few differences to keep in mind.

• The most obvious is probably that all I/O operations return a GnomeVFSResult indicating the success or failure of the operation. More on this later.

• The types may be slightly different (but still parallel), for example rather than using an int for a file-descriptor, GnomeVFS uses GnomeVFSHandle, a handle to a particular URI.

• Most operations come in Handle (think file descriptor) and URI form. The URI form may be more convenient if you do not want to track handles, etc, but just be aware that both are at your disposal and may be used interchangably. For example gnome_vfs_open and gnome_vfs_open_uri.

By way of example, consider the basic read command:

ssize_t read (int fd, void *buf, size_t count);

The GnomeVFS equivalent is very similar, but you will notice slightly different data types. The consistent returning of a GnomeVFSResult also necessitated moving the return value of read into a pass-back-value pointer bytes_read:

GnomeVFSResult gnome_vfs_read (GnomeVFSHandle *handle, gpointer buffer, GnomeVFSFileSize bytes, GnomeVFSFileSize *bytes_read);