Writing Modules

Writing Modules — basic gnome-vfs module concepts

Introduction

GNOME VFS URIs (Uniform Resource Identifiers)


        ftp://username:password@host.net/path/to/file.tar.gz#gzip#tar/path/to/hello.c

        method://user:password@host/path/to/file

The GnomeVFSURI type

GNOME Virtual File System access method implementation

How file access is performed


        file:/home/ettore/file.gz#gzip

Implementing an access method in practice

Using shared libraries


The initialization/shutdown functions


GnomeVFSMethod *vfs_module_init (void);
void vfs_module_shutdown (GnomeVFSMethod *method);

The GnomeVFSMethod object


GnomeVFSResult (* open)              (GnomeVFSMethodHandle **method_handle_return,
                                      GnomeVFSURI *uri,
                                      GnomeVFSOpenMode mode
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* create)            (GnomeVFSMethodHandle **method_handle_return,
                                      GnomeVFSURI *uri,
                                      GnomeVFSOpenMode mode,
                                      gboolean exclusive,
                                      guint perm
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* close)             (GnomeVFSMethodHandle *method_handle
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* read)              (GnomeVFSMethodHandle *method_handle,
                                      gpointer buffer,
                                      GnomeVFSFileSize num_bytes,
                                      GnomeVFSFileSize *bytes_read_return
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* write)             (GnomeVFSMethodHandle *method_handle,
                                      gconstpointer buffer,
                                      GnomeVFSFileSize num_bytes,
                                      GnomeVFSFileSize *bytes_written_return
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* seek)              (GnomeVFSMethodHandle *method_handle,
                                      GnomeVFSSeekPosition  whence,
                                      GnomeVFSFileOffset    offset
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* tell)              (GnomeVFSMethodHandle *method_handle,
                                      GnomeVFSFileOffset *offset_return);

GnomeVFSResult (* truncate)          (GnomeVFSMethodHandle *method_handle,
                                      GnomeVFSFileSize where
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* open_directory)    (GnomeVFSMethodHandle **method_handle,
                                      GnomeVFSURI *uri,
                                      GnomeVFSFileInfoOptions options,
                                      const GList *meta_keys,
                                      const GnomeVFSDirectoryFilter *filter
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* close_directory)   (GnomeVFSMethodHandle *method_handle
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* read_directory)    (GnomeVFSMethodHandle *method_handle,
                                      GnomeVFSFileInfo *file_info
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* get_file_info)     (GnomeVFSURI *uri,
                                      GnomeVFSFileInfo *file_info,
                                      GnomeVFSFileInfoOptions options,
                                      const GList *meta_keys
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* get_file_info_from_handle)
                                     (GnomeVFSMethodHandle *method_handle,
                                      GnomeVFSFileInfo *file_info,
                                      GnomeVFSFileInfoOptions options,
                                      const GList *meta_keys
                                      GnomeVFSCancellation *cancellation);

gboolean       (* is_local)          (const GnomeVFSURI *uri
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* rename)            (GnomeVFSURI *uri, const gchar *new_name
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* make_directory)    (GnomeVFSURI *uri, guint perm
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* remove_directory)  (GnomeVFSURI *uri
                                      GnomeVFSCancellation *cancellation);

GnomeVFSResult (* unlink)            (GnomeVFSURI *uri
                                      GnomeVFSCancellation *cancellation);

Handling cancellation

The GnomeVFSCancellation object

  
gboolean gnome_vfs_cancellation_check (GnomeVFSCancellation *cancellation);

gint gnome_vfs_cancellation_get_fd (GnomeVFSCancellation *cancellation); 

Dealing with EINTR

Basic guidelines for writing a module

How to make the code thread safe


#ifdef G_THREADS_ENABLED
#define MUTEX_NEW()     g_mutex_new ()
#define MUTEX_FREE(a)   g_mutex_free (a)
#define MUTEX_LOCK(a)   if ((a) != NULL) g_mutex_lock (a)
#define MUTEX_UNLOCK(a) if ((a) != NULL) g_mutex_unlock (a)
#else
#define MUTEX_NEW()     NULL
#define MUTEX_FREE(a)
#define MUTEX_LOCK(a)
#define MUTEX_UNLOCK(a)
#endif