doc/about.sgml

   1 <chapter id="about">
   2   <title>Introduction to GnomeVFS</title>
   3
   4   <sect1>
   5     <title>Uses and Purpose</title>
   6     <para>
   7       GnomeVFS is a filesystem abstraction library allowing applications
   8       plugable transparent access to a variety of "real" filesystems, from
   9       WebDAV to digital cameras, to the local filesystem. It also contains
  10       a number of other convenient file utilities such as a comphrehensive
  11       MIME database / Application registry, and a copy engine. Use of GnomeVFS
  12       ensures that an application or component will be usable by Nautilus
  13       or other GnomeVFS applications for handling the display of data from
  14       various URIs, as well
  15     </para>
  16     <sect2>
  17       <title>User's Perspective</title>
  18       <para>
  19         From a user's perspective GnomeVFS enabled applications provide consistent
  20         access to their data, whether it be stored on remote servers or on their
  21         local harddisk, or even a peripheral device such as a Rio or a digital
  22         camera. Rather than having to work around the distinction between storage
  23         you can work off of and storage you can only "download" from or "upload" to,
  24         GnomeVFS allows users to store their documents and data wherever it is
  25         most convenient.
  26       </para>
  27     </sect2>
  28     <sect2>
  29       <title>Developer's Perspective</title>
  30       <para>
  31         Besides providing transparent access to data methods that you might
  32         otherwise have to implement, GnomeVFS provides a number of convenience
  33         libraries for processing URIs, detecting the MIME type of files, and
  34         even figuring out which applications or components to launch to view
  35         a file or what icon to use. Writing a GnomeVFS module may also be an
  36         appropriate solution to some data access problems as it allows the
  37         developer to implement a relatively small number of functions to gain
  38         general filesystem semantics (and of course, writing a GnomeVFS module
  39         benefits other applications too!).
  40       </para>
  41     </sect2>
  42   </sect1>
  43
  44   <sect1 id="gnome-vfs-first-steps">
  45     <title>A Gentle Programming Primer</title>
  46     <para>
  47       Using GnomeVFS in an existing application, or writing a new application
  48       with it, is actually very simple since GnomeVFS tries to mimic POSIX
  49       file access syntax and semantics. That means that most "standard unix calls"
  50       have a GnomeVFS equivalent that operates in a fairly similar manner. There are
  51       a few differences to keep in mind.
  52
  53       <itemizedlist>
  54
  55         <listitem>
  56           <para>
  57             The most obvious is probably that all I/O operations return a <type>GnomeVFSResult</type>
  58             indicating the success or failure of the operation. More on this later.
  59           </para>
  60         </listitem>
  61         <listitem>
  62           <para>
  63             The types may be slightly different (but still parallel), for example rather than using an
  64             <type>int</type> for a file-descriptor, GnomeVFS uses <type>GnomeVFSHandle</type>, a handle
  65             to a particular URI.
  66           </para>
  67         </listitem>
  68         <listitem>
  69           <para>
  70             Most operations come in Handle (think file descriptor) and URI form. The URI form may be
  71             more convenient if you do not want to track handles, etc, but just be aware that both are
  72             at your disposal and may be used interchangably. For example <function>gnome_vfs_open</function>
  73             and <function>gnome_vfs_open_uri</function>.
  74           </para>
  75         </listitem>
  76       </itemizedlist>
  77     </para>
  78     <para>
  79       By way of example, consider the basic read command:
  80       <programlisting>
  81         ssize_t read (int fd, void *buf, size_t count);
  82       </programlisting>
  83     </para>
  84     <para>
  85       The GnomeVFS equivalent is very similar, but you will notice slightly different data types. The
  86       consistent returning of a GnomeVFSResult also necessitated moving the return value of read into
  87       a pass-back-value pointer <parameter>bytes_read</parameter>:
  88       <programlisting>
  89         GnomeVFSResult gnome_vfs_read (GnomeVFSHandle *handle,
  90                                        gpointer buffer,
  91                                        GnomeVFSFileSize bytes,
  92                                        GnomeVFSFileSize *bytes_read);
  93       </programlisting>
  94     </para>
  95     <para>
  96       So <function>gnome_vfs_read</function> takes a <type>GnomeVFSHandle</type>, which functions
  97       like a file descriptor, and attempts to read <parameter>bytes</parameter> bytes out of
  98       <parameter>handle</parameter> into <parameter>buffer</parameter>. The number of bytes succesfully
  99       read into <parameter>buffer</parameter> is returned in the pointer <parameter>bytes_read</parameter>.
 100       The return value of the function, a <type>GnomeVFSResult</type> indicates the success of the
 101       operation or any errors that might have occurred (for example, permission denied).
 102       <type>GnomeVFSResult</type> is just an enumeration.
 103     </para>
 104     <sect2>
 105       <title>Simple Sample Program</title>
 106       <para>
 107         Now lets write a simple program to copy a fixed number of bytes from one file and append
 108         it to another file.
 109       </para>
 110       <para>
 111         <programlisting>
 112 <![CDATA[
 113 #include <libgnomevfs/gnome-vfs.h>
 114 #include <gnome.h>
 115
 116 #define BYTES_TO_PROCESS 256
 117
 118 int print_error (GnomeVFSResult result, const char *uri_string);
 119
 120 int
 121 main (int argc, char **argv)
 122 {
 123   GnomeVFSHandle *read_handle, *write_handle;
 124   const char *input_uri_string = argv[1];
 125   const char *output_uri_string = argv[2];
 126   GnomeVFSFileSize bytes_read, bytes_written;
 127   guint buffer[BYTES_TO_PROCESS];
 128   GnomeVFSResult result;
 129
 130   /* remember to initialize GnomeVFS! */
 131   if (!gnome_vfs_init ()) {
 132     printf ("Could not initialize GnomeVFS\n");
 133     return 1;
 134   }
 135
 136   /* open the input file for read access */
 137   result = gnome_vfs_open (&read_handle, input_uri_string, GNOME_VFS_OPEN_READ);
 138   /* if the operation was not successful, print the error and abort */
 139   if (result != GNOME_VFS_OK) return print_error (result, input_uri_string);
 140
 141   /* we use create instead of open, because open will not create the file if it does
 142      not already exist. The last argument is the permissions to use if the file is created,
 143      the second to last tells GnomeVFS that its ok if the file already exists, and just open it */
 144   result = gnome_vfs_create (&write_handle, output_uri_string, GNOME_VFS_OPEN_WRITE, FALSE, 0x777);
 145   if (result != GNOME_VFS_OK) return print_error (result, output_uri_string);
 146
 147   /* read data from the input uri */
 148   result = gnome_vfs_read (read_handle, buffer, BYTES_TO_PROCESS, &bytes_read);
 149   if (result != GNOME_VFS_OK) return print_error (result, input_uri_string);
 150
 151   /* seek to the end of the output uri so we will append rather than overwrite */
 152   /* therefore, we seek 0 bytes relative to the end of the file */
 153   result = gnome_vfs_seek (write_handle, GNOME_VFS_SEEK_END, 0);
 154
 155   /* now write the data we read out to the output uri */
 156   result = gnome_vfs_write (write_handle, buffer, bytes_read, &bytes_written);
 157   if (result != GNOME_VFS_OK) return print_error (result, output_uri_string);
 158
 159   return 0;
 160 }
 161
 162 int
 163 print_error (GnomeVFSResult result, const char *uri_string)
 164 {
 165   const char *error_string;
 166   /* get the string corresponding to this GnomeVFSResult value */
 167   error_string = gnome_vfs_result_to_string (result);
 168   printf ("Error %s occured opening location %s\n", error_string, uri_string);
 169   return 1;
 170 }
 171
 172 ]]>
 173         </programlisting>
 174 </para>
 175     </sect2>
 176     <sect2>
 177         <title>Conversion of a Sample Code Block</title>
 178         <para>
 179         </para>
 180       </sect2>
 181   </sect1>
 182 </chapter>