How to use Gnomevfs

 

GnomeVFS

Another library that was introduced in GNOME 1.4, but still worthmentioning here, is GnomeVFS (GNOME Virtual File System). GnomeVFS is agreat library which makes accessing various kinds of file systemstransparent to the user and developer. The user doesn't even have totake care of whether a file is located on the local machine or on aremote server. Various protocols like HTTP, FTP, local files, WebDAV,are all used in the exact same way.

API

The API for accessing files have been kept close to the POSIX standard with some minor changes:

• For example, you use GnomeVFSHandle instead of file descriptors in GnomeVFS.
• All I/O operations return a GnomeVFSResult, indicating the result of the operation.

The API is very straight-forward and easy to use, as we'll show in the following example:

#include <glib.h>#include <gtk/gtk.h>#include <libgnomevfs/gnome-vfs.h>#define BUF_SIZE 8192GtkWidget *load_image (const gchar *uri){GnomeVFSHandle *handle;GnomeVFSResult result;GdkPixbufLoader *loader;GdkPixbuf *pixbuf;gchar buffer[BUF_SIZE];GnomeVFSFileSize bytes_read;result = gnome_vfs_open (&handle, uri, GNOME_VFS_OPEN_READ);loader = gdk_pixbuf_loader_new ();while (result == GNOME_VFS_OK) {result = gnome_vfs_read (handle, buffer, BUF_SIZE, &bytes_read);gdk_pixbuf_loader_write (loader, buffer, bytes_read, NULL);}gdk_pixbuf_loader_close (loader, NULL);pixbuf = gdk_pixbuf_loader_get_pixbuf (loader);if (!pixbuf) {return NULL;}return gtk_image_new_from_pixbuf (pixbuf);}int main (int argc, char *argv[]){GtkWidget *window;GtkWidget *image;if (argc < 2) {g_print ("Run with %s <uri>/n", argv[0]);return 1;}gtk_init (&argc, &argv);gnome_vfs_init ();window = gtk_window_new (GTK_WINDOW_TOPLEVEL);g_signal_connect (window, "destroy", gtk_main_quit, NULL);image = load_image (argv[1]);if (!image) {g_print ("Not a valid uri: %s/n", argv[1]);return 1;}gtk_container_add (GTK_CONTAINER (window), image);gtk_widget_show_all (window);gtk_main ();return 0;}

To compile the example:

# gcc `pkg-config --libs --cflags gtk+-2.0 gnome-vfs-2.0` /
      vfs-example.c -o vfs-example

The example reads a string from the command-line and uses thisstring to read an image which is displayed in a window. The string canrepresent an URL, like http://www.gnome.org/images/logo-large or it can represent a local file, like ~/picture.gif.

Asynchronous operations

GnomeVFS also provides methods for performing asynchronousoperations, such as fetching a file in the background. If you, forexample, are writing an FTP client, you don't want the entire GUI tofreeze while a file is being received. This could be solved by usingthreads in your application, but using threads makes the applicationmuch more complex and harder to debug.

Using the asynchronous operations in GnomeVFS makes it very easy toget the same functionality without the complexity of threads (GnomeVFSactually uses threads internally, but hides them from you).

The method is very similar to using synchronous calls. But insteadof waiting for the various function calls to open, read and close tofinish, the asynchronous functions return immediately. When theoperation is finished, a callback is invoked.

void gnome_vfs_async_open (GnomeVFSAsyncHandle **handle_return,
                                                const gchar *text_uri,                                                GnomeVFSOpenMode open_mode,                                                int  priority,                                                GnomeVFSAsyncOpenCallback   callback,                                                gpointer callback_data);

By calling gnome_vfs_async_open() you start asynchronous operationof opening an URI. This function will return immediately so that youcan carry on with other operations.

When the uri has been opened, 'callback' will be called and you canstart reading with gnome_vfs_async_read() from the handle. When alldata has been read, you call gnome_vfs_async_close() to close theconnection.

Writing your own GnomeVFS modules

If GnomeVFS is lacking support for some file system or networkprotocol, you can write your own module to handle this extrafunctionality. You then have instant transparent support for this, inall programs using GnomeVFS to access files! How to write such aGnomeVFS module is outside the scope of this article and will behandled in a later article.