doc/html/gnome-vfs-first-steps.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>A Gentle Programming Primer</title><meta name="generator" content="DocBook XSL Stylesheets V1.61.0"><meta name="generator" content="GTK-Doc V1.1 (XML mode)"><style type="text/css">
   2         .synopsis, .classsynopsis {
   3             background: #eeeeee;
   4             border: solid 1px #aaaaaa;
   5             padding: 0.5em;
   6         }
   7         .programlisting {
   8             background: #eeeeff;
   9             border: solid 1px #aaaaff;
  10             padding: 0.5em;
  11         }
  12         .variablelist {
  13             padding: 4px;
  14             margin-left: 3em;
  15         }
  16         .navigation {
  17             background: #ffeeee;
  18             border: solid 1px #ffaaaa;
  19             margin-top: 0.5em;
  20             margin-bottom: 0.5em;
  21         }
  22         .navigation a {
  23             color: #770000;
  24         }
  25         .navigation a:visited {
  26             color: #550000;
  27         }
  28         .navigation .title {
  29             font-size: 200%;
  30         }
  31       </style><link rel="home" href="index.html" title="GnomeVFS - Filesystem Abstraction library"><link rel="up" href="about.html" title="Introduction to GnomeVFS"><link rel="previous" href="about.html" title="Introduction to GnomeVFS"><link rel="next" href="gnome-vfs-20-gnome-vfs-init.html" title="Initialization/Shutdown"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table class="navigation" 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></div></div><p>
  32       Using GnomeVFS in an existing application, or writing a new application
  33       with it, is actually very simple since GnomeVFS tries to mimic POSIX
  34       file access syntax and semantics. That means that most "standard unix calls"
  35       have a GnomeVFS equivalent that operates in a fairly similar manner. There are
  36       a few differences to keep in mind.
  37
  38       </p><div class="itemizedlist"><ul type="disc"><li><p>
  39             The most obvious is probably that all I/O operations return a <span class="type">GnomeVFSResult</span>
  40             indicating the success or failure of the operation. More on this later.
  41           </p></li><li><p>
  42             The types may be slightly different (but still parallel), for example rather than using an
  43             <span class="type">int</span> for a file-descriptor, GnomeVFS uses <span class="type">GnomeVFSHandle</span>, a handle
  44             to a particular URI.
  45           </p></li><li><p>
  46             Most operations come in Handle (think file descriptor) and URI form. The URI form may be
  47             more convenient if you do not want to track handles, etc, but just be aware that both are
  48             at your disposal and may be used interchangably. For example <tt class="function">gnome_vfs_open</tt>
  49             and <tt class="function">gnome_vfs_open_uri</tt>.
  50           </p></li></ul></div><p>
  51     </p><p>
  52       By way of example, consider the basic read command:
  53       </p><pre class="programlisting">
  54         ssize_t read (int fd, void *buf, size_t count);
  55       </pre><p>
  56     </p><p>
  57       The GnomeVFS equivalent is very similar, but you will notice slightly different data types. The
  58       consistent returning of a GnomeVFSResult also necessitated moving the return value of read into
  59       a pass-back-value pointer <i class="parameter"><tt>bytes_read</tt></i>:
  60       </p><pre class="programlisting">
  61         GnomeVFSResult gnome_vfs_read (GnomeVFSHandle *handle,
  62                                        gpointer buffer,
  63                                        GnomeVFSFileSize bytes,
  64                                        GnomeVFSFileSize *bytes_read);
  65       </pre><p>
  66     </p><p>
  67       So <tt class="function">gnome_vfs_read</tt> takes a <span class="type">GnomeVFSHandle</span>, which functions
  68       like a file descriptor, and attempts to read <i class="parameter"><tt>bytes</tt></i> bytes out of
  69       <i class="parameter"><tt>handle</tt></i> into <i class="parameter"><tt>buffer</tt></i>. The number of bytes succesfully
  70       read into <i class="parameter"><tt>buffer</tt></i> is returned in the pointer <i class="parameter"><tt>bytes_read</tt></i>.
  71       The return value of the function, a <span class="type">GnomeVFSResult</span> indicates the success of the
  72       operation or any errors that might have occurred (for example, permission denied).
  73       <span class="type">GnomeVFSResult</span> is just an enumeration.
  74     </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2823551"></a>Simple Sample Program</h3></div></div><div></div></div><p>
  75         Now lets write a simple program to copy a fixed number of bytes from one file and append
  76         it to another file.
  77       </p><p>
  78         </p><pre class="programlisting">
  79
  80 #include &lt;libgnomevfs/gnome-vfs.h&gt;
  81 #include &lt;gnome.h&gt;
  82
  83 #define BYTES_TO_PROCESS 256
  84
  85 int print_error (GnomeVFSResult result, const char *uri_string);
  86
  87 int
  88 main (int argc, char **argv)
  89 {
  90   GnomeVFSHandle *read_handle, *write_handle;
  91   const char *input_uri_string = argv[1];
  92   const char *output_uri_string = argv[2];
  93   GnomeVFSFileSize bytes_read, bytes_written;
  94   guint buffer[BYTES_TO_PROCESS];
  95   GnomeVFSResult result;
  96
  97   /* remember to initialize GnomeVFS! */
  98   if (!gnome_vfs_init ()) {
  99     printf ("Could not initialize GnomeVFS\n");
 100     return 1;
 101   }
 102
 103   /* open the input file for read access */
 104   result = gnome_vfs_open (&amp;read_handle, input_uri_string, GNOME_VFS_OPEN_READ);
 105   /* if the operation was not successful, print the error and abort */
 106   if (result != GNOME_VFS_OK) return print_error (result, input_uri_string);
 107
 108   /* we use create instead of open, because open will not create the file if it does
 109      not already exist. The last argument is the permissions to use if the file is created,
 110      the second to last tells GnomeVFS that its ok if the file already exists, and just open it */
 111   result = gnome_vfs_create (&amp;write_handle, output_uri_string, GNOME_VFS_OPEN_WRITE, FALSE, 0x777);
 112   if (result != GNOME_VFS_OK) return print_error (result, output_uri_string);
 113
 114   /* read data from the input uri */
 115   result = gnome_vfs_read (read_handle, buffer, BYTES_TO_PROCESS, &amp;bytes_read);
 116   if (result != GNOME_VFS_OK) return print_error (result, input_uri_string);
 117
 118   /* seek to the end of the output uri so we will append rather than overwrite */
 119   /* therefore, we seek 0 bytes relative to the end of the file */
 120   result = gnome_vfs_seek (write_handle, GNOME_VFS_SEEK_END, 0);
 121
 122   /* now write the data we read out to the output uri */
 123   result = gnome_vfs_write (write_handle, buffer, bytes_read, &amp;bytes_written);
 124   if (result != GNOME_VFS_OK) return print_error (result, output_uri_string);
 125
 126   return 0;
 127 }
 128
 129 int
 130 print_error (GnomeVFSResult result, const char *uri_string)
 131 {
 132   const char *error_string;
 133   /* get the string corresponding to this GnomeVFSResult value */
 134   error_string = gnome_vfs_result_to_string (result);
 135   printf ("Error %s occured opening location %s\n", error_string, uri_string);
 136   return 1;
 137 }
 138
 139
 140         </pre><p>
 141 </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2823578"></a>Conversion of a Sample Code Block</h3></div></div><div></div></div><p>
 142         </p></div></div><table class="navigation" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="0"><tr valign="middle"><td align="left"><a accesskey="p" href="about.html"><b>&lt;&lt; Introduction to GnomeVFS</b></a></td><td align="right"><a accesskey="n" href="gnome-vfs-20-gnome-vfs-init.html"><b>Initialization/Shutdown &gt;&gt;</b></a></td></tr></table></body></html>