How to use Gnomevfs

 

GnomeVFS

Another library that was introduced in GNOME 1.4, but still worth mentioning here, is GnomeVFS (GNOME Virtual File System). GnomeVFS is a great library which makes accessing various kinds of file systems transparent to the user and developer. The user doesn't even have to take care of whether a file is located on the local machine or on a remote 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 8192 GtkWidget * 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 this string to read an image which is displayed in a window. The string can represent 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 asynchronous operations, such as fetching a file in the background. If you, for example, are writing an FTP client, you don't want the entire GUI to freeze while a file is being received. This could be solved by using threads in your application, but using threads makes the application much more complex and harder to debug.

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

The method is very similar to using synchronous calls. But instead of waiting for the various function calls to open, read and close to finish, the asynchronous functions return immediately. When the operation 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 operation of opening an URI. This function will return immediately so that you can carry on with other operations.

When the uri has been opened, 'callback' will be called and you can start reading with gnome_vfs_async_read() from the handle. When all data has been read, you call gnome_vfs_async_close() to close the connection.

Writing your own GnomeVFS modules

If GnomeVFS is lacking support for some file system or network protocol, you can write your own module to handle this extra functionality. You then have instant transparent support for this, in all programs using GnomeVFS to access files! How to write such a GnomeVFS module is outside the scope of this article and will be handled in a later article.