File: //usr/share/gtk-doc/html/gnome-vfs-2.0/gnome-vfs-first-steps.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>A Gentle Programming Primer</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
<link rel="start" href="index.html" title="GnomeVFS - Filesystem Abstraction library">
<link rel="up" href="about.html" title="Introduction to GnomeVFS">
<link rel="prev" href="about.html" title="Introduction to GnomeVFS">
<link rel="next" href="gnome-vfs-20-gnome-vfs-init.html" title="Initialization/Shutdown">
<meta name="generator" content="GTK-Doc V1.7 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="chapter" href="about.html" title="Introduction to GnomeVFS">
<link rel="chapter" href="data-types.html" title="Basic Data Types">
<link rel="chapter" href="gnome-vfs-basic-file-ops.html" title="File Operations">
<link rel="chapter" href="gnome-vfs-directory-ops.html" title="Directory-Specific Operations">
<link rel="chapter" href="gnome-vfs-file-and-dirs-ops.html" title="Advanced File/Directory Operations">
<link rel="chapter" href="gnome-vfs-file-async-ops.html" title="Asynchronous Operations">
<link rel="chapter" href="volumes.html" title="Volumes and Drives Handling">
<link rel="chapter" href="networking.html" title="Networking">
<link rel="chapter" href="mime-registry.html" title="MIME Registry">
<link rel="chapter" href="modules.html" title="Filesystem Modules">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="about.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="about.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GnomeVFS - Filesystem Abstraction library</th>
<td><a accesskey="n" href="gnome-vfs-20-gnome-vfs-init.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="gnome-vfs-first-steps"></a>A Gentle Programming Primer</h2></div></div></div>
<p>
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.
</p>
<div class="itemizedlist"><ul type="disc">
<li><p>
The most obvious is probably that all I/O operations return a <span class="type">GnomeVFSResult</span>
indicating the success or failure of the operation. More on this later.
</p></li>
<li><p>
The types may be slightly different (but still parallel), for example rather than using an
<span class="type">int</span> for a file-descriptor, GnomeVFS uses <span class="type">GnomeVFSHandle</span>, a handle
to a particular URI.
</p></li>
<li><p>
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 <code class="function">gnome_vfs_open</code>
and <code class="function">gnome_vfs_open_uri</code>.
</p></li>
</ul></div>
<p>
</p>
<p>
By way of example, consider the basic read command:
</p>
<pre class="programlisting">
ssize_t read (int fd, void *buf, size_t count);
</pre>
<p>
</p>
<p>
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 <em class="parameter"><code>bytes_read</code></em>:
</p>
<pre class="programlisting">
GnomeVFSResult gnome_vfs_read (GnomeVFSHandle *handle,
gpointer buffer,
GnomeVFSFileSize bytes,
GnomeVFSFileSize *bytes_read);
</pre>
<p>
</p>
<p>
So <code class="function">gnome_vfs_read</code> takes a <span class="type">GnomeVFSHandle</span>, which functions
like a file descriptor, and attempts to read <em class="parameter"><code>bytes</code></em> bytes out of
<em class="parameter"><code>handle</code></em> into <em class="parameter"><code>buffer</code></em>. The number of bytes succesfully
read into <em class="parameter"><code>buffer</code></em> is returned in the pointer <em class="parameter"><code>bytes_read</code></em>.
The return value of the function, a <span class="type">GnomeVFSResult</span> indicates the success of the
operation or any errors that might have occurred (for example, permission denied).
<span class="type">GnomeVFSResult</span> is just an enumeration.
</p>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id2481030"></a>Simple Sample Program</h3></div></div></div>
<p>
Now lets write a simple program to copy a fixed number of bytes from one file and append
it to another file.
</p>
<p>
</p>
<pre class="programlisting">
#include <stdio.h>
#include <libgnomevfs/gnome-vfs.h>
#include <libgnomevfs/gnome-vfs-utils.h>
#define BYTES_TO_PROCESS 256
int print_error (GnomeVFSResult result, const char *uri_string);
int
main (int argc, char **argv)
{
GnomeVFSHandle *read_handle, *write_handle;
char *input_uri_string;
char *output_uri_string = argv[2];
GnomeVFSFileSize bytes_read, bytes_written;
guint buffer[BYTES_TO_PROCESS];
GnomeVFSResult result;
/* remember to initialize GnomeVFS! */
if (!gnome_vfs_init ()) {
printf ("Could not initialize GnomeVFS\n");
return 1;
}
/* Convert the user supplied filenames into proper GnomeVFS URIs */
input_uri_string = gnome_vfs_make_uri_from_shell_arg (argv[1]);
output_uri_string = gnome_vfs_make_uri_from_shell_arg (argv[2]);
/* open the input file for read access */
result = gnome_vfs_open (&read_handle, input_uri_string, GNOME_VFS_OPEN_READ);
/* if the operation was not successful, print the error and abort */
if (result != GNOME_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 GnomeVFS that its ok if the file already exists, and just open it */
result = gnome_vfs_create (&write_handle, output_uri_string, GNOME_VFS_OPEN_WRITE, FALSE, 0777);
if (result != GNOME_VFS_OK) return print_error (result, output_uri_string);
/* read data from the input uri */
result = gnome_vfs_read (read_handle, buffer, BYTES_TO_PROCESS, &bytes_read);
if (result != GNOME_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 = gnome_vfs_seek (write_handle, GNOME_VFS_SEEK_END, 0);
/* now write the data we read out to the output uri */
result = gnome_vfs_write (write_handle, buffer, bytes_read, &bytes_written);
if (result != GNOME_VFS_OK) return print_error (result, output_uri_string);
g_free (input_uri_string);
g_free (output_uri_string);
return 0;
}
int
print_error (GnomeVFSResult result, const char *uri_string)
{
const char *error_string;
/* get the string corresponding to this GnomeVFSResult value */
error_string = gnome_vfs_result_to_string (result);
printf ("Error %s occured opening location %s\n", error_string, uri_string);
return 1;
}
</pre>
<p>
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id2481051"></a>Conversion of a Sample Code Block</h3></div></div></div>
<p>
</p>
</div>
</div>
</body>
</html>