![]() |
![]() |
![]() |
MateVFS - Filesystem Abstraction library | ![]() |
---|
Using MateVFS in an existing application, or writing a new application with it, is actually very simple since MateVFS tries to mimic POSIX file access syntax and semantics. That means that most "standard unix calls" have a MateVFS 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 MateVFSResult 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, MateVFS uses MateVFSHandle, 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 mate_vfs_open
and mate_vfs_open_uri
.
By way of example, consider the basic read command:
ssize_t read (int fd, void *buf, size_t count);
The MateVFS equivalent is very similar, but you will notice slightly different data types. The
consistent returning of a MateVFSResult also necessitated moving the return value of read into
a pass-back-value pointer bytes_read
:
MateVFSResult mate_vfs_read (MateVFSHandle *handle, gpointer buffer, MateVFSFileSize bytes, MateVFSFileSize *bytes_read);
So mate_vfs_read
takes a MateVFSHandle, which functions
like a file descriptor, and attempts to read bytes
bytes out of
handle
into buffer
. The number of bytes succesfully
read into buffer
is returned in the pointer bytes_read
.
The return value of the function, a MateVFSResult indicates the success of the
operation or any errors that might have occurred (for example, permission denied).
MateVFSResult is just an enumeration.
Now lets write a simple program to copy a fixed number of bytes from one file and append it to another file.
#include <stdio.h> #include <libmatevfs/mate-vfs.h> #include <libmatevfs/mate-vfs-utils.h> #define BYTES_TO_PROCESS 256 int print_error (MateVFSResult result, const char *uri_string); int main (int argc, char **argv) { MateVFSHandle *read_handle, *write_handle; char *input_uri_string; char *output_uri_string = argv[2]; MateVFSFileSize bytes_read, bytes_written; guint buffer[BYTES_TO_PROCESS]; MateVFSResult result; /* remember to initialize MateVFS! */ if (!mate_vfs_init ()) { printf ("Could not initialize MateVFS\n"); return 1; } /* Convert the user supplied filenames into proper MateVFS URIs */ input_uri_string = mate_vfs_make_uri_from_shell_arg (argv[1]); output_uri_string = mate_vfs_make_uri_from_shell_arg (argv[2]); /* open the input file for read access */ result = mate_vfs_open (&read_handle, input_uri_string, MATE_VFS_OPEN_READ); /* if the operation was not successful, print the error and abort */ if (result != MATE_VFS_OK) return print_error (result, input_uri_string); /* we use create instead of open, because open will not create the file if it does not already exist. The last argument is the permissions to use if the file is created, the second to last tells MateVFS that its ok if the file already exists, and just open it */ result = mate_vfs_create (&write_handle, output_uri_string, MATE_VFS_OPEN_WRITE, FALSE, 0777); if (result != MATE_VFS_OK) return print_error (result, output_uri_string); /* read data from the input uri */ result = mate_vfs_read (read_handle, buffer, BYTES_TO_PROCESS, &bytes_read); if (result != MATE_VFS_OK) return print_error (result, input_uri_string); /* seek to the end of the output uri so we will append rather than overwrite */ /* therefore, we seek 0 bytes relative to the end of the file */ result = mate_vfs_seek (write_handle, MATE_VFS_SEEK_END, 0); /* now write the data we read out to the output uri */ result = mate_vfs_write (write_handle, buffer, bytes_read, &bytes_written); if (result != MATE_VFS_OK) return print_error (result, output_uri_string); g_free (input_uri_string); g_free (output_uri_string); return 0; } int print_error (MateVFSResult result, const char *uri_string) { const char *error_string; /* get the string corresponding to this MateVFSResult value */ error_string = mate_vfs_result_to_string (result); printf ("Error %s occured opening location %s\n", error_string, uri_string); return 1; }