doc/xml/gnome-vfs-async-ops.xml

   1 <refentry id="gnome-vfs-20-gnome-vfs-async-ops">
   2 <refmeta>
   3 <refentrytitle>Asynchronous File Operations</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>GNOME-VFS-2.0 Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Asynchronous File Operations</refname><refpurpose>
  10 POSIX-style file operations that run outside your main loop</refpurpose>
  11 </refnamediv>
  12
  13 <refsynopsisdiv><title>Synopsis</title>
  14
  15 <synopsis>
  16
  17
  18
  19 #define     <link linkend="GNOME-VFS-PRIORITY-MIN-CAPS">GNOME_VFS_PRIORITY_MIN</link>
  20 #define     <link linkend="GNOME-VFS-PRIORITY-MAX-CAPS">GNOME_VFS_PRIORITY_MAX</link>
  21 #define     <link linkend="GNOME-VFS-PRIORITY-DEFAULT-CAPS">GNOME_VFS_PRIORITY_DEFAULT</link>
  22 <link linkend="void">void</link>        (<link linkend="GnomeVFSAsyncCallback">*GnomeVFSAsyncCallback</link>)        (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle,
  23                                              <link linkend="GnomeVFSResult">GnomeVFSResult</link> result,
  24                                              <link linkend="gpointer">gpointer</link> callback_data);
  25 typedef     <link linkend="GnomeVFSAsyncOpenCallback">GnomeVFSAsyncOpenCallback</link>;
  26 typedef     <link linkend="GnomeVFSAsyncCreateCallback">GnomeVFSAsyncCreateCallback</link>;
  27 typedef     <link linkend="GnomeVFSAsyncCreateAsChannelCallback">GnomeVFSAsyncCreateAsChannelCallback</link>;
  28 typedef     <link linkend="GnomeVFSAsyncCloseCallback">GnomeVFSAsyncCloseCallback</link>;
  29 <link linkend="void">void</link>        (<link linkend="GnomeVFSAsyncReadCallback">*GnomeVFSAsyncReadCallback</link>)    (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle,
  30                                              <link linkend="GnomeVFSResult">GnomeVFSResult</link> result,
  31                                              <link linkend="gpointer">gpointer</link> buffer,
  32                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes_requested,
  33                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes_read,
  34                                              <link linkend="gpointer">gpointer</link> callback_data);
  35 <link linkend="void">void</link>        (<link linkend="GnomeVFSAsyncWriteCallback">*GnomeVFSAsyncWriteCallback</link>)   (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle,
  36                                              <link linkend="GnomeVFSResult">GnomeVFSResult</link> result,
  37                                              <link linkend="gconstpointer">gconstpointer</link> buffer,
  38                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes_requested,
  39                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes_written,
  40                                              <link linkend="gpointer">gpointer</link> callback_data);
  41 typedef     <link linkend="GnomeVFSFindDirectoryResult">GnomeVFSFindDirectoryResult</link>;
  42 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-set-job-limit">gnome_vfs_async_set_job_limit</link>   (<link linkend="int">int</link> limit);
  43 <link linkend="int">int</link>         <link linkend="gnome-vfs-async-get-job-limit">gnome_vfs_async_get_job_limit</link>   (void);
  44 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-cancel">gnome_vfs_async_cancel</link>          (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle);
  45 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-open">gnome_vfs_async_open</link>            (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
  46                                              const <link linkend="gchar">gchar</link> *text_uri,
  47                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
  48                                              <link linkend="int">int</link> priority,
  49                                              <link linkend="GnomeVFSAsyncOpenCallback">GnomeVFSAsyncOpenCallback</link> callback,
  50                                              <link linkend="gpointer">gpointer</link> callback_data);
  51 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-open-uri">gnome_vfs_async_open_uri</link>        (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
  52                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
  53                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
  54                                              <link linkend="int">int</link> priority,
  55                                              <link linkend="GnomeVFSAsyncOpenCallback">GnomeVFSAsyncOpenCallback</link> callback,
  56                                              <link linkend="gpointer">gpointer</link> callback_data);
  57 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-open-as-channel">gnome_vfs_async_open_as_channel</link> (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
  58                                              const <link linkend="gchar">gchar</link> *text_uri,
  59                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
  60                                              <link linkend="guint">guint</link> advised_block_size,
  61                                              <link linkend="int">int</link> priority,
  62                                              <link linkend="GnomeVFSAsyncOpenAsChannelCallback">GnomeVFSAsyncOpenAsChannelCallback</link> callback,
  63                                              <link linkend="gpointer">gpointer</link> callback_data);
  64 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-open-uri-as-channel">gnome_vfs_async_open_uri_as_channel</link>
  65                                             (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
  66                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
  67                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
  68                                              <link linkend="guint">guint</link> advised_block_size,
  69                                              <link linkend="int">int</link> priority,
  70                                              <link linkend="GnomeVFSAsyncOpenAsChannelCallback">GnomeVFSAsyncOpenAsChannelCallback</link> callback,
  71                                              <link linkend="gpointer">gpointer</link> callback_data);
  72 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-create">gnome_vfs_async_create</link>          (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
  73                                              const <link linkend="gchar">gchar</link> *text_uri,
  74                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
  75                                              <link linkend="gboolean">gboolean</link> exclusive,
  76                                              <link linkend="guint">guint</link> perm,
  77                                              <link linkend="int">int</link> priority,
  78                                              <link linkend="GnomeVFSAsyncOpenCallback">GnomeVFSAsyncOpenCallback</link> callback,
  79                                              <link linkend="gpointer">gpointer</link> callback_data);
  80 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-create-uri">gnome_vfs_async_create_uri</link>      (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
  81                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
  82                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
  83                                              <link linkend="gboolean">gboolean</link> exclusive,
  84                                              <link linkend="guint">guint</link> perm,
  85                                              <link linkend="int">int</link> priority,
  86                                              <link linkend="GnomeVFSAsyncOpenCallback">GnomeVFSAsyncOpenCallback</link> callback,
  87                                              <link linkend="gpointer">gpointer</link> callback_data);
  88 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-create-symbolic-link">gnome_vfs_async_create_symbolic_link</link>
  89                                             (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
  90                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
  91                                              const <link linkend="gchar">gchar</link> *uri_reference,
  92                                              <link linkend="int">int</link> priority,
  93                                              <link linkend="GnomeVFSAsyncOpenCallback">GnomeVFSAsyncOpenCallback</link> callback,
  94                                              <link linkend="gpointer">gpointer</link> callback_data);
  95 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-create-as-channel">gnome_vfs_async_create_as_channel</link>
  96                                             (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
  97                                              const <link linkend="gchar">gchar</link> *text_uri,
  98                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
  99                                              <link linkend="gboolean">gboolean</link> exclusive,
 100                                              <link linkend="guint">guint</link> perm,
 101                                              <link linkend="int">int</link> priority,
 102                                              <link linkend="GnomeVFSAsyncCreateAsChannelCallback">GnomeVFSAsyncCreateAsChannelCallback</link> callback,
 103                                              <link linkend="gpointer">gpointer</link> callback_data);
 104 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-create-uri-as-channel">gnome_vfs_async_create_uri_as_channel</link>
 105                                             (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 106                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
 107                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
 108                                              <link linkend="gboolean">gboolean</link> exclusive,
 109                                              <link linkend="guint">guint</link> perm,
 110                                              <link linkend="int">int</link> priority,
 111                                              <link linkend="GnomeVFSAsyncCreateAsChannelCallback">GnomeVFSAsyncCreateAsChannelCallback</link> callback,
 112                                              <link linkend="gpointer">gpointer</link> callback_data);
 113 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-close">gnome_vfs_async_close</link>           (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle,
 114                                              <link linkend="GnomeVFSAsyncCloseCallback">GnomeVFSAsyncCloseCallback</link> callback,
 115                                              <link linkend="gpointer">gpointer</link> callback_data);
 116 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-read">gnome_vfs_async_read</link>            (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle,
 117                                              <link linkend="gpointer">gpointer</link> buffer,
 118                                              <link linkend="guint">guint</link> bytes,
 119                                              <link linkend="GnomeVFSAsyncReadCallback">GnomeVFSAsyncReadCallback</link> callback,
 120                                              <link linkend="gpointer">gpointer</link> callback_data);
 121 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-write">gnome_vfs_async_write</link>           (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle,
 122                                              <link linkend="gconstpointer">gconstpointer</link> buffer,
 123                                              <link linkend="guint">guint</link> bytes,
 124                                              <link linkend="GnomeVFSAsyncWriteCallback">GnomeVFSAsyncWriteCallback</link> callback,
 125                                              <link linkend="gpointer">gpointer</link> callback_data);
 126 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-get-file-info">gnome_vfs_async_get_file_info</link>   (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 127                                              <link linkend="GList">GList</link> *uri_list,
 128                                              <link linkend="GnomeVFSFileInfoOptions">GnomeVFSFileInfoOptions</link> options,
 129                                              <link linkend="int">int</link> priority,
 130                                              <link linkend="GnomeVFSAsyncGetFileInfoCallback">GnomeVFSAsyncGetFileInfoCallback</link> callback,
 131                                              <link linkend="gpointer">gpointer</link> callback_data);
 132 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-set-file-info">gnome_vfs_async_set_file_info</link>   (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 133                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
 134                                              <link linkend="GnomeVFSFileInfo">GnomeVFSFileInfo</link> *info,
 135                                              <link linkend="GnomeVFSSetFileInfoMask">GnomeVFSSetFileInfoMask</link> mask,
 136                                              <link linkend="GnomeVFSFileInfoOptions">GnomeVFSFileInfoOptions</link> options,
 137                                              <link linkend="int">int</link> priority,
 138                                              <link linkend="GnomeVFSAsyncSetFileInfoCallback">GnomeVFSAsyncSetFileInfoCallback</link> callback,
 139                                              <link linkend="gpointer">gpointer</link> callback_data);
 140 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-load-directory">gnome_vfs_async_load_directory</link>  (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 141                                              const <link linkend="gchar">gchar</link> *text_uri,
 142                                              <link linkend="GnomeVFSFileInfoOptions">GnomeVFSFileInfoOptions</link> options,
 143                                              <link linkend="guint">guint</link> items_per_notification,
 144                                              <link linkend="int">int</link> priority,
 145                                              <link linkend="GnomeVFSAsyncDirectoryLoadCallback">GnomeVFSAsyncDirectoryLoadCallback</link> callback,
 146                                              <link linkend="gpointer">gpointer</link> callback_data);
 147 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-load-directory-uri">gnome_vfs_async_load_directory_uri</link>
 148                                             (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 149                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
 150                                              <link linkend="GnomeVFSFileInfoOptions">GnomeVFSFileInfoOptions</link> options,
 151                                              <link linkend="guint">guint</link> items_per_notification,
 152                                              <link linkend="int">int</link> priority,
 153                                              <link linkend="GnomeVFSAsyncDirectoryLoadCallback">GnomeVFSAsyncDirectoryLoadCallback</link> callback,
 154                                              <link linkend="gpointer">gpointer</link> callback_data);
 155 <link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-async-xfer">gnome_vfs_async_xfer</link>         (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 156                                              <link linkend="GList">GList</link> *source_uri_list,
 157                                              <link linkend="GList">GList</link> *target_uri_list,
 158                                              <link linkend="GnomeVFSXferOptions">GnomeVFSXferOptions</link> xfer_options,
 159                                              <link linkend="GnomeVFSXferErrorMode">GnomeVFSXferErrorMode</link> error_mode,
 160                                              <link linkend="GnomeVFSXferOverwriteMode">GnomeVFSXferOverwriteMode</link> overwrite_mode,
 161                                              <link linkend="int">int</link> priority,
 162                                              <link linkend="GnomeVFSAsyncXferProgressCallback">GnomeVFSAsyncXferProgressCallback</link> progress_update_callback,
 163                                              <link linkend="gpointer">gpointer</link> update_callback_data,
 164                                              <link linkend="GnomeVFSXferProgressCallback">GnomeVFSXferProgressCallback</link> progress_sync_callback,
 165                                              <link linkend="gpointer">gpointer</link> sync_callback_data);
 166 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-find-directory">gnome_vfs_async_find_directory</link>  (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 167                                              <link linkend="GList">GList</link> *near_uri_list,
 168                                              <link linkend="GnomeVFSFindDirectoryKind">GnomeVFSFindDirectoryKind</link> kind,
 169                                              <link linkend="gboolean">gboolean</link> create_if_needed,
 170                                              <link linkend="gboolean">gboolean</link> find_if_needed,
 171                                              <link linkend="guint">guint</link> permissions,
 172                                              <link linkend="int">int</link> priority,
 173                                              <link linkend="GnomeVFSAsyncFindDirectoryCallback">GnomeVFSAsyncFindDirectoryCallback</link> callback,
 174                                              <link linkend="gpointer">gpointer</link> user_data);
 175 <link linkend="void">void</link>        <link linkend="gnome-vfs-async-file-control">gnome_vfs_async_file_control</link>    (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle,
 176                                              const <link linkend="char">char</link> *operation,
 177                                              <link linkend="gpointer">gpointer</link> operation_data,
 178                                              <link linkend="GDestroyNotify">GDestroyNotify</link> operation_data_destroy_func,
 179                                              <link linkend="GnomeVFSAsyncFileControlCallback">GnomeVFSAsyncFileControlCallback</link> callback,
 180                                              <link linkend="gpointer">gpointer</link> callback_data);
 181 </synopsis>
 182 </refsynopsisdiv>
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192 <refsect1>
 193 <title>Description</title>
 194 <para>
 195   When executing an asynchornous operation on a file the program does not
 196   block waiting for the operation to finish, instead it keeps on running,
 197   which means that the process and the I/O operation can be both running
 198   concurrently. Once the I/O operation has been completed the process is
 199   notified using a callback.
 200 </para>
 201
 202 <para>
 203   Asynchronous operations are particularly good when long I/O operations
 204   are expected, in this case the program can continue normaly, the I/O
 205   will be performed in the background. On the other hand when operations
 206   are expected to be short (creating a file, writing/reading small amounts
 207   of data, etc.) synchronous operations are prefered.
 208 </para>
 209
 210 <para>
 211   Within a graphical desktop asynchornous I/O operations can be used to
 212   avoid blocking the UI (User Interface) during a long operation, and
 213   to be able to provide some kind of feedback to the user.
 214 </para>
 215 </refsect1>
 216
 217 <refsect1>
 218 <title>Details</title>
 219 <refsect2>
 220 <title><anchor id="GNOME-VFS-PRIORITY-MIN-CAPS"/>GNOME_VFS_PRIORITY_MIN</title>
 221 <indexterm><primary>GNOME_VFS_PRIORITY_MIN</primary></indexterm><programlisting>#define GNOME_VFS_PRIORITY_MIN     -10
 222 </programlisting>
 223 <para>
 224 The minimuum priority a job can have.</para>
 225 <para>
 226
 227 </para></refsect2>
 228 <refsect2>
 229 <title><anchor id="GNOME-VFS-PRIORITY-MAX-CAPS"/>GNOME_VFS_PRIORITY_MAX</title>
 230 <indexterm><primary>GNOME_VFS_PRIORITY_MAX</primary></indexterm><programlisting>#define GNOME_VFS_PRIORITY_MAX     10
 231 </programlisting>
 232 <para>
 233 The maximuum priority a job can have.</para>
 234 <para>
 235
 236 </para></refsect2>
 237 <refsect2>
 238 <title><anchor id="GNOME-VFS-PRIORITY-DEFAULT-CAPS"/>GNOME_VFS_PRIORITY_DEFAULT</title>
 239 <indexterm><primary>GNOME_VFS_PRIORITY_DEFAULT</primary></indexterm><programlisting>#define GNOME_VFS_PRIORITY_DEFAULT 0
 240 </programlisting>
 241 <para>
 242 The default job priority. Its best to use this
 243 unless you have a reason to do otherwise.</para>
 244 <para>
 245
 246 </para></refsect2>
 247 <refsect2>
 248 <title><anchor id="GnomeVFSAsyncCallback"/>GnomeVFSAsyncCallback ()</title>
 249 <indexterm><primary>GnomeVFSAsyncCallback</primary></indexterm><programlisting><link linkend="void">void</link>        (*GnomeVFSAsyncCallback)        (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle,
 250                                              <link linkend="GnomeVFSResult">GnomeVFSResult</link> result,
 251                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 252 <para>
 253 Basic callback from an async operation that passes no data back,
 254 informing the user of the <parameter>result</parameter> of the operation.</para>
 255 <para>
 256
 257 </para><variablelist role="params">
 258 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
 259 <listitem><simpara> handle of the operation generating the callback
 260 </simpara></listitem></varlistentry>
 261 <varlistentry><term><parameter>result</parameter>&nbsp;:</term>
 262 <listitem><simpara> <literal>GNOME_VFS_OK</literal> if the operation was successful, otherwise
 263 an error code.
 264 </simpara></listitem></varlistentry>
 265 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 266 <listitem><simpara> user data defined when the callback was established
 267 </simpara></listitem></varlistentry>
 268 </variablelist></refsect2>
 269 <refsect2>
 270 <title><anchor id="GnomeVFSAsyncOpenCallback"/>GnomeVFSAsyncOpenCallback</title>
 271 <indexterm><primary>GnomeVFSAsyncOpenCallback</primary></indexterm><programlisting>typedef GnomeVFSAsyncCallback GnomeVFSAsyncOpenCallback;
 272 </programlisting>
 273 <para>
 274 Basic callback from an async operation that passes no data back,
 275 informing the user of the <parameter>result</parameter> of the operation.</para>
 276 <para>
 277
 278 </para></refsect2>
 279 <refsect2>
 280 <title><anchor id="GnomeVFSAsyncCreateCallback"/>GnomeVFSAsyncCreateCallback</title>
 281 <indexterm><primary>GnomeVFSAsyncCreateCallback</primary></indexterm><programlisting>typedef GnomeVFSAsyncCallback GnomeVFSAsyncCreateCallback;
 282 </programlisting>
 283 <para>
 284 Basic callback from an async operation that passes no data back,
 285 informing the user of the <parameter>result</parameter> of the operation.</para>
 286 <para>
 287
 288 </para></refsect2>
 289 <refsect2>
 290 <title><anchor id="GnomeVFSAsyncCreateAsChannelCallback"/>GnomeVFSAsyncCreateAsChannelCallback</title>
 291 <indexterm><primary>GnomeVFSAsyncCreateAsChannelCallback</primary></indexterm><programlisting>typedef GnomeVFSAsyncOpenAsChannelCallback GnomeVFSAsyncCreateAsChannelCallback;
 292 </programlisting>
 293 <para>
 294 Callback for the <link linkend="gnome-vfs-async-create-as-channel"><function>gnome_vfs_async_create_as_channel()</function></link> function.</para>
 295 <para>
 296
 297 </para></refsect2>
 298 <refsect2>
 299 <title><anchor id="GnomeVFSAsyncCloseCallback"/>GnomeVFSAsyncCloseCallback</title>
 300 <indexterm><primary>GnomeVFSAsyncCloseCallback</primary></indexterm><programlisting>typedef GnomeVFSAsyncCallback GnomeVFSAsyncCloseCallback;
 301 </programlisting>
 302 <para>
 303 Basic callback from an async operation that passes no data back,
 304 informing the user of the <parameter>result</parameter> of the operation.</para>
 305 <para>
 306
 307 </para></refsect2>
 308 <refsect2>
 309 <title><anchor id="GnomeVFSAsyncReadCallback"/>GnomeVFSAsyncReadCallback ()</title>
 310 <indexterm><primary>GnomeVFSAsyncReadCallback</primary></indexterm><programlisting><link linkend="void">void</link>        (*GnomeVFSAsyncReadCallback)    (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle,
 311                                              <link linkend="GnomeVFSResult">GnomeVFSResult</link> result,
 312                                              <link linkend="gpointer">gpointer</link> buffer,
 313                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes_requested,
 314                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes_read,
 315                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 316 <para>
 317 Callback for the <link linkend="gnome-vfs-async-read"><function>gnome_vfs_async_read()</function></link> function.</para>
 318 <para>
 319
 320 </para><variablelist role="params">
 321 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
 322 <listitem><simpara> handle of the operation generating the callback
 323 </simpara></listitem></varlistentry>
 324 <varlistentry><term><parameter>result</parameter>&nbsp;:</term>
 325 <listitem><simpara> <literal>GNOME_VFS_OK</literal> if the operation was successful, otherwise
 326 an error code.
 327 </simpara></listitem></varlistentry>
 328 <varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
 329 <listitem><simpara> buffer containing data read from <parameter>handle</parameter>.
 330 </simpara></listitem></varlistentry>
 331 <varlistentry><term><parameter>bytes_requested</parameter>&nbsp;:</term>
 332 <listitem><simpara> the number of bytes asked for in the call to
 333 <link linkend="gnome-vfs-async-read"><function>gnome_vfs_async_read()</function></link>.
 334 </simpara></listitem></varlistentry>
 335 <varlistentry><term><parameter>bytes_read</parameter>&nbsp;:</term>
 336 <listitem><simpara> the number of bytes actually read from <parameter>handle</parameter> into <parameter>buffer</parameter>.
 337 </simpara></listitem></varlistentry>
 338 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 339 <listitem><simpara> user data defined when the callback was established
 340 </simpara></listitem></varlistentry>
 341 </variablelist></refsect2>
 342 <refsect2>
 343 <title><anchor id="GnomeVFSAsyncWriteCallback"/>GnomeVFSAsyncWriteCallback ()</title>
 344 <indexterm><primary>GnomeVFSAsyncWriteCallback</primary></indexterm><programlisting><link linkend="void">void</link>        (*GnomeVFSAsyncWriteCallback)   (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle,
 345                                              <link linkend="GnomeVFSResult">GnomeVFSResult</link> result,
 346                                              <link linkend="gconstpointer">gconstpointer</link> buffer,
 347                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes_requested,
 348                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes_written,
 349                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 350 <para>
 351 Callback for the <link linkend="gnome-vfs-async-write"><function>gnome_vfs_async_write()</function></link> function.</para>
 352 <para>
 353
 354 </para><variablelist role="params">
 355 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
 356 <listitem><simpara> handle of the operation generating the callback
 357 </simpara></listitem></varlistentry>
 358 <varlistentry><term><parameter>result</parameter>&nbsp;:</term>
 359 <listitem><simpara> <literal>GNOME_VFS_OK</literal> if the operation was successful, otherwise
 360 an error code.
 361 </simpara></listitem></varlistentry>
 362 <varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
 363 <listitem><simpara> buffer containing data written to <parameter>handle</parameter>.
 364 </simpara></listitem></varlistentry>
 365 <varlistentry><term><parameter>bytes_requested</parameter>&nbsp;:</term>
 366 <listitem><simpara> the number of bytes asked to write in the call to
 367 <link linkend="gnome-vfs-async-write"><function>gnome_vfs_async_write()</function></link>.
 368 </simpara></listitem></varlistentry>
 369 <varlistentry><term><parameter>bytes_written</parameter>&nbsp;:</term>
 370 <listitem><simpara> the number of bytes actually written to <parameter>handle</parameter> from <parameter>buffer</parameter>.
 371 </simpara></listitem></varlistentry>
 372 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 373 <listitem><simpara> user data defined when the callback was established
 374 </simpara></listitem></varlistentry>
 375 </variablelist></refsect2>
 376 <refsect2>
 377 <title><anchor id="GnomeVFSFindDirectoryResult"/>GnomeVFSFindDirectoryResult</title>
 378 <indexterm><primary>GnomeVFSFindDirectoryResult</primary></indexterm><programlisting>typedef struct {
 379         GnomeVFSURI *uri;
 380         GnomeVFSResult result;
 381
 382         /* Reserved to avoid future breaks in ABI compatibility */
 383         void *reserved1;
 384         void *reserved2;
 385 } GnomeVFSFindDirectoryResult;
 386 </programlisting>
 387 <para>
 388
 389 </para></refsect2>
 390 <refsect2>
 391 <title><anchor id="gnome-vfs-async-set-job-limit"/>gnome_vfs_async_set_job_limit ()</title>
 392 <indexterm><primary>gnome_vfs_async_set_job_limit</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_set_job_limit   (<link linkend="int">int</link> limit);</programlisting>
 393 <para>
 394 Restrict the number of worker threads used by Async operations
 395 to <parameter>limit</parameter>.</para>
 396 <para>
 397
 398 </para><variablelist role="params">
 399 <varlistentry><term><parameter>limit</parameter>&nbsp;:</term>
 400 <listitem><simpara> maximuum number of allowable threads
 401 </simpara></listitem></varlistentry>
 402 </variablelist></refsect2>
 403 <refsect2>
 404 <title><anchor id="gnome-vfs-async-get-job-limit"/>gnome_vfs_async_get_job_limit ()</title>
 405 <indexterm><primary>gnome_vfs_async_get_job_limit</primary></indexterm><programlisting><link linkend="int">int</link>         gnome_vfs_async_get_job_limit   (void);</programlisting>
 406 <para>
 407 Get the current maximuum allowable number of
 408 worker threads for Asynch operations.</para>
 409 <para>
 410
 411 </para><variablelist role="params">
 412 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> current maximuum number of threads
 413 </simpara></listitem></varlistentry>
 414 </variablelist></refsect2>
 415 <refsect2>
 416 <title><anchor id="gnome-vfs-async-cancel"/>gnome_vfs_async_cancel ()</title>
 417 <indexterm><primary>gnome_vfs_async_cancel</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_cancel          (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle);</programlisting>
 418 <para>
 419 Cancel an asynchronous operation and close all its callbacks.
 420 Its possible to still receive another call or two on the callback.</para>
 421 <para>
 422
 423 </para><variablelist role="params">
 424 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
 425 <listitem><simpara> handle of the async operation to be cancelled
 426 </simpara></listitem></varlistentry>
 427 </variablelist></refsect2>
 428 <refsect2>
 429 <title><anchor id="gnome-vfs-async-open"/>gnome_vfs_async_open ()</title>
 430 <indexterm><primary>gnome_vfs_async_open</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_open            (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 431                                              const <link linkend="gchar">gchar</link> *text_uri,
 432                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
 433                                              <link linkend="int">int</link> priority,
 434                                              <link linkend="GnomeVFSAsyncOpenCallback">GnomeVFSAsyncOpenCallback</link> callback,
 435                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 436 <para>
 437 Open <parameter>text_uri</parameter> according to mode <parameter>open_mode</parameter>.  On return, <parameter>handle_return</parameter> will
 438 contain a pointer to the operation. Once the file has been successfully opened,
 439 <parameter>callback</parameter> will be called with the GnomeVFSResult.</para>
 440 <para>
 441
 442 </para><variablelist role="params">
 443 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
 444 <listitem><simpara> A pointer to a pointer to a GnomeVFSHandle object
 445 </simpara></listitem></varlistentry>
 446 <varlistentry><term><parameter>text_uri</parameter>&nbsp;:</term>
 447 <listitem><simpara> string of the URI to open
 448 </simpara></listitem></varlistentry>
 449 <varlistentry><term><parameter>open_mode</parameter>&nbsp;:</term>
 450 <listitem><simpara> Open mode
 451 </simpara></listitem></varlistentry>
 452 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
 453 <listitem><simpara> a value from <literal>GNOME_VFS_PRIORITY_MIN</literal> to <literal>GNOME_VFS_PRIORITY_MAX</literal> (normally
 454 should be <literal>GNOME_VFS_PRIORITY_DEFAULT</literal>) indicating the priority to assign this job
 455 in allocating threads from the thread pool.
 456 </simpara></listitem></varlistentry>
 457 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
 458 <listitem><simpara> function to be called when the operation is complete
 459 </simpara></listitem></varlistentry>
 460 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 461 <listitem><simpara> data to pass <parameter>callback</parameter>
 462 </simpara></listitem></varlistentry>
 463 </variablelist></refsect2>
 464 <refsect2>
 465 <title><anchor id="gnome-vfs-async-open-uri"/>gnome_vfs_async_open_uri ()</title>
 466 <indexterm><primary>gnome_vfs_async_open_uri</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_open_uri        (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 467                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
 468                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
 469                                              <link linkend="int">int</link> priority,
 470                                              <link linkend="GnomeVFSAsyncOpenCallback">GnomeVFSAsyncOpenCallback</link> callback,
 471                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 472 <para>
 473 Open <parameter>uri</parameter> according to mode <parameter>open_mode</parameter>.  On return, <parameter>handle_return</parameter> will
 474 contain a pointer to the operation. Once the file has been successfully opened,
 475 <parameter>callback</parameter> will be called with the GnomeVFSResult.</para>
 476 <para>
 477
 478 </para><variablelist role="params">
 479 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
 480 <listitem><simpara> A pointer to a pointer to a GnomeVFSHandle object
 481 </simpara></listitem></varlistentry>
 482 <varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
 483 <listitem><simpara> URI to open
 484 </simpara></listitem></varlistentry>
 485 <varlistentry><term><parameter>open_mode</parameter>&nbsp;:</term>
 486 <listitem><simpara> Open mode
 487 </simpara></listitem></varlistentry>
 488 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
 489 <listitem><simpara> a value from <literal>GNOME_VFS_PRIORITY_MIN</literal> to <literal>GNOME_VFS_PRIORITY_MAX</literal> (normally
 490 should be <literal>GNOME_VFS_PRIORITY_DEFAULT</literal>) indicating the priority to assign this job
 491 in allocating threads from the thread pool.
 492 </simpara></listitem></varlistentry>
 493 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
 494 <listitem><simpara> function to be called when the operation is complete
 495 </simpara></listitem></varlistentry>
 496 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 497 <listitem><simpara> data to pass <parameter>callback</parameter>
 498 </simpara></listitem></varlistentry>
 499 </variablelist></refsect2>
 500 <refsect2>
 501 <title><anchor id="gnome-vfs-async-open-as-channel"/>gnome_vfs_async_open_as_channel ()</title>
 502 <indexterm><primary>gnome_vfs_async_open_as_channel</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_open_as_channel (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 503                                              const <link linkend="gchar">gchar</link> *text_uri,
 504                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
 505                                              <link linkend="guint">guint</link> advised_block_size,
 506                                              <link linkend="int">int</link> priority,
 507                                              <link linkend="GnomeVFSAsyncOpenAsChannelCallback">GnomeVFSAsyncOpenAsChannelCallback</link> callback,
 508                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 509 <para>
 510 Open <parameter>text_uri</parameter> as a <link linkend="GIOChannel"><type>GIOChannel</type></link>. Once the channel has been established
 511 <parameter>callback</parameter> will be called with <parameter>callback_data</parameter>, the result of the operation,
 512 and if the result was <literal>GNOME_VFS_OK</literal>, a reference to a <link linkend="GIOChannel"><type>GIOChannel</type></link> pointing
 513 at <parameter>text_uri</parameter> in <parameter>open_mode</parameter>.</para>
 514 <para>
 515
 516 </para><variablelist role="params">
 517 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
 518 <listitem><simpara> A pointer to a pointer to a GnomeVFSHandle object
 519 </simpara></listitem></varlistentry>
 520 <varlistentry><term><parameter>text_uri</parameter>&nbsp;:</term>
 521 <listitem><simpara> string of the URI to open as a <link linkend="GIOChannel"><type>GIOChannel</type></link>
 522 </simpara></listitem></varlistentry>
 523 <varlistentry><term><parameter>open_mode</parameter>&nbsp;:</term>
 524 <listitem><simpara> open for reading, writing, random, etc
 525 </simpara></listitem></varlistentry>
 526 <varlistentry><term><parameter>advised_block_size</parameter>&nbsp;:</term>
 527 <listitem><simpara> the preferred block size for <link linkend="GIOChannel"><type>GIOChannel</type></link> to read
 528 </simpara></listitem></varlistentry>
 529 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
 530 <listitem><simpara> a value from <literal>GNOME_VFS_PRIORITY_MIN</literal> to <literal>GNOME_VFS_PRIORITY_MAX</literal> (normally
 531 should be <literal>GNOME_VFS_PRIORITY_DEFAULT</literal>) indicating the priority to assign this job
 532 in allocating threads from the thread pool.
 533 </simpara></listitem></varlistentry>
 534 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
 535 <listitem><simpara> function to be called when the operation is complete
 536 </simpara></listitem></varlistentry>
 537 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 538 <listitem><simpara> data to pass <parameter>callback</parameter>
 539 </simpara></listitem></varlistentry>
 540 </variablelist></refsect2>
 541 <refsect2>
 542 <title><anchor id="gnome-vfs-async-open-uri-as-channel"/>gnome_vfs_async_open_uri_as_channel ()</title>
 543 <indexterm><primary>gnome_vfs_async_open_uri_as_channel</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_open_uri_as_channel
 544                                             (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 545                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
 546                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
 547                                              <link linkend="guint">guint</link> advised_block_size,
 548                                              <link linkend="int">int</link> priority,
 549                                              <link linkend="GnomeVFSAsyncOpenAsChannelCallback">GnomeVFSAsyncOpenAsChannelCallback</link> callback,
 550                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 551 <para>
 552 Open <parameter>uri</parameter> as a <link linkend="GIOChannel"><type>GIOChannel</type></link>. Once the channel has been established
 553 <parameter>callback</parameter> will be called with <parameter>callback_data</parameter>, the result of the operation,
 554 and if the result was <literal>GNOME_VFS_OK</literal>, a reference to a <link linkend="GIOChannel"><type>GIOChannel</type></link> pointing
 555 at <parameter>uri</parameter> in <parameter>open_mode</parameter>.</para>
 556 <para>
 557
 558 </para><variablelist role="params">
 559 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
 560 <listitem><simpara> A pointer to a pointer to a GnomeVFSHandle object
 561 </simpara></listitem></varlistentry>
 562 <varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
 563 <listitem><simpara> URI to open as a <link linkend="GIOChannel"><type>GIOChannel</type></link>
 564 </simpara></listitem></varlistentry>
 565 <varlistentry><term><parameter>open_mode</parameter>&nbsp;:</term>
 566 <listitem><simpara> open for reading, writing, random, etc
 567 </simpara></listitem></varlistentry>
 568 <varlistentry><term><parameter>advised_block_size</parameter>&nbsp;:</term>
 569 <listitem><simpara> the preferred block size for <link linkend="GIOChannel"><type>GIOChannel</type></link> to read
 570 </simpara></listitem></varlistentry>
 571 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
 572 <listitem><simpara> a value from <literal>GNOME_VFS_PRIORITY_MIN</literal> to <literal>GNOME_VFS_PRIORITY_MAX</literal> (normally
 573 should be <literal>GNOME_VFS_PRIORITY_DEFAULT</literal>) indicating the priority to assign this job
 574 in allocating threads from the thread pool.
 575 </simpara></listitem></varlistentry>
 576 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
 577 <listitem><simpara> function to be called when the operation is complete
 578 </simpara></listitem></varlistentry>
 579 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 580 <listitem><simpara> data to pass <parameter>callback</parameter>
 581 </simpara></listitem></varlistentry>
 582 </variablelist></refsect2>
 583 <refsect2>
 584 <title><anchor id="gnome-vfs-async-create"/>gnome_vfs_async_create ()</title>
 585 <indexterm><primary>gnome_vfs_async_create</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_create          (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 586                                              const <link linkend="gchar">gchar</link> *text_uri,
 587                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
 588                                              <link linkend="gboolean">gboolean</link> exclusive,
 589                                              <link linkend="guint">guint</link> perm,
 590                                              <link linkend="int">int</link> priority,
 591                                              <link linkend="GnomeVFSAsyncOpenCallback">GnomeVFSAsyncOpenCallback</link> callback,
 592                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 593 <para>
 594 Create a file at <parameter>uri</parameter> according to mode <parameter>open_mode</parameter>, with permissions <parameter>perm</parameter> (in
 595 the standard UNIX packed bit permissions format). When the create has been completed
 596 <parameter>callback</parameter> will be called with the result code and <parameter>callback_data</parameter>.</para>
 597 <para>
 598
 599 </para><variablelist role="params">
 600 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
 601 <listitem><simpara> A pointer to a pointer to a GnomeVFSHandle object
 602 </simpara></listitem></varlistentry>
 603 <varlistentry><term><parameter>text_uri</parameter>&nbsp;:</term>
 604 <listitem><simpara> String representing the URI to create
 605 </simpara></listitem></varlistentry>
 606 <varlistentry><term><parameter>open_mode</parameter>&nbsp;:</term>
 607 <listitem><simpara> mode to leave the file opened in after creation (or <literal>GNOME_VFS_OPEN_MODE_NONE</literal>
 608 to leave the file closed after creation)
 609 </simpara></listitem></varlistentry>
 610 <varlistentry><term><parameter>exclusive</parameter>&nbsp;:</term>
 611 <listitem><simpara> Whether the file should be created in "exclusive" mode:
 612 i.e. if this flag is nonzero, operation will fail if a file with the
 613 same name already exists.
 614 </simpara></listitem></varlistentry>
 615 <varlistentry><term><parameter>perm</parameter>&nbsp;:</term>
 616 <listitem><simpara> Bitmap representing the permissions for the newly created file
 617 (Unix style).
 618 </simpara></listitem></varlistentry>
 619 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
 620 <listitem><simpara> a value from <literal>GNOME_VFS_PRIORITY_MIN</literal> to <literal>GNOME_VFS_PRIORITY_MAX</literal> (normally
 621 should be <literal>GNOME_VFS_PRIORITY_DEFAULT</literal>) indicating the priority to assign this job
 622 in allocating threads from the thread pool.
 623 </simpara></listitem></varlistentry>
 624 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
 625 <listitem><simpara> function to be called when the operation is complete
 626 </simpara></listitem></varlistentry>
 627 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 628 <listitem><simpara> data to pass <parameter>callback</parameter>
 629 </simpara></listitem></varlistentry>
 630 </variablelist></refsect2>
 631 <refsect2>
 632 <title><anchor id="gnome-vfs-async-create-uri"/>gnome_vfs_async_create_uri ()</title>
 633 <indexterm><primary>gnome_vfs_async_create_uri</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_create_uri      (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 634                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
 635                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
 636                                              <link linkend="gboolean">gboolean</link> exclusive,
 637                                              <link linkend="guint">guint</link> perm,
 638                                              <link linkend="int">int</link> priority,
 639                                              <link linkend="GnomeVFSAsyncOpenCallback">GnomeVFSAsyncOpenCallback</link> callback,
 640                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 641 <para>
 642 Create a file at <parameter>uri</parameter> according to mode <parameter>open_mode</parameter>, with permissions <parameter>perm</parameter> (in
 643 the standard UNIX packed bit permissions format). When the create has been completed
 644 <parameter>callback</parameter> will be called with the result code and <parameter>callback_data</parameter>.</para>
 645 <para>
 646
 647 </para><variablelist role="params">
 648 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
 649 <listitem><simpara> A pointer to a pointer to a GnomeVFSHandle object
 650 </simpara></listitem></varlistentry>
 651 <varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
 652 <listitem><simpara> the URI to create a file at
 653 </simpara></listitem></varlistentry>
 654 <varlistentry><term><parameter>open_mode</parameter>&nbsp;:</term>
 655 <listitem><simpara> mode to leave the file opened in after creation (or <literal>GNOME_VFS_OPEN_MODE_NONE</literal>
 656 to leave the file closed after creation)
 657 </simpara></listitem></varlistentry>
 658 <varlistentry><term><parameter>exclusive</parameter>&nbsp;:</term>
 659 <listitem><simpara> Whether the file should be created in "exclusive" mode:
 660 i.e. if this flag is nonzero, operation will fail if a file with the
 661 same name already exists.
 662 </simpara></listitem></varlistentry>
 663 <varlistentry><term><parameter>perm</parameter>&nbsp;:</term>
 664 <listitem><simpara> Bitmap representing the permissions for the newly created file
 665 (Unix style).
 666 </simpara></listitem></varlistentry>
 667 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
 668 <listitem><simpara> a value from <literal>GNOME_VFS_PRIORITY_MIN</literal> to <literal>GNOME_VFS_PRIORITY_MAX</literal> (normally
 669 should be <literal>GNOME_VFS_PRIORITY_DEFAULT</literal>) indicating the priority to assign this job
 670 in allocating threads from the thread pool.
 671 </simpara></listitem></varlistentry>
 672 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
 673 <listitem><simpara> function to be called when the operation is complete
 674 </simpara></listitem></varlistentry>
 675 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 676 <listitem><simpara> data to pass <parameter>callback</parameter>
 677 </simpara></listitem></varlistentry>
 678 </variablelist></refsect2>
 679 <refsect2>
 680 <title><anchor id="gnome-vfs-async-create-symbolic-link"/>gnome_vfs_async_create_symbolic_link ()</title>
 681 <indexterm><primary>gnome_vfs_async_create_symbolic_link</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_create_symbolic_link
 682                                             (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 683                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
 684                                              const <link linkend="gchar">gchar</link> *uri_reference,
 685                                              <link linkend="int">int</link> priority,
 686                                              <link linkend="GnomeVFSAsyncOpenCallback">GnomeVFSAsyncOpenCallback</link> callback,
 687                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 688 <para>
 689 Create a symbolic link at <parameter>uri</parameter> pointing to <parameter>uri_reference</parameter>. When the operation
 690 has complete <parameter>callback</parameter> will be called with the result of the operation and
 691 <parameter>callback_data</parameter>.</para>
 692 <para>
 693
 694 </para><variablelist role="params">
 695 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
 696 <listitem><simpara> when the function returns will point to a handle for
 697 the async operation.
 698 </simpara></listitem></varlistentry>
 699 <varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
 700 <listitem><simpara> location to create the link at
 701 </simpara></listitem></varlistentry>
 702 <varlistentry><term><parameter>uri_reference</parameter>&nbsp;:</term>
 703 <listitem><simpara> location to point <parameter>uri</parameter> to (can be a URI fragment, i.e. relative)
 704 </simpara></listitem></varlistentry>
 705 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
 706 <listitem><simpara> a value from <literal>GNOME_VFS_PRIORITY_MIN</literal> to <literal>GNOME_VFS_PRIORITY_MAX</literal> (normally
 707 should be <literal>GNOME_VFS_PRIORITY_DEFAULT</literal>) indicating the priority to assign this job
 708 in allocating threads from the thread pool.
 709 </simpara></listitem></varlistentry>
 710 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
 711 <listitem><simpara> function to be called when the operation is complete
 712 </simpara></listitem></varlistentry>
 713 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 714 <listitem><simpara> data to pass <parameter>callback</parameter>
 715 </simpara></listitem></varlistentry>
 716 </variablelist></refsect2>
 717 <refsect2>
 718 <title><anchor id="gnome-vfs-async-create-as-channel"/>gnome_vfs_async_create_as_channel ()</title>
 719 <indexterm><primary>gnome_vfs_async_create_as_channel</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_create_as_channel
 720                                             (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 721                                              const <link linkend="gchar">gchar</link> *text_uri,
 722                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
 723                                              <link linkend="gboolean">gboolean</link> exclusive,
 724                                              <link linkend="guint">guint</link> perm,
 725                                              <link linkend="int">int</link> priority,
 726                                              <link linkend="GnomeVFSAsyncCreateAsChannelCallback">GnomeVFSAsyncCreateAsChannelCallback</link> callback,
 727                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 728 <para>
 729 Open <parameter>text_uri</parameter> as a <link linkend="GIOChannel"><type>GIOChannel</type></link>, creating it as necessary. Once the channel has
 730 been established <parameter>callback</parameter> will be called with <parameter>callback_data</parameter>, the result of the
 731 operation, and if the result was <literal>GNOME_VFS_OK</literal>, a reference to a <link linkend="GIOChannel"><type>GIOChannel</type></link> pointing
 732 at <parameter>text_uri</parameter> in <parameter>open_mode</parameter>.</para>
 733 <para>
 734
 735 </para><variablelist role="params">
 736 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
 737 <listitem><simpara> A pointer to a pointer to a GnomeVFSHandle object
 738 </simpara></listitem></varlistentry>
 739 <varlistentry><term><parameter>text_uri</parameter>&nbsp;:</term>
 740 <listitem><simpara> string of the URI to open as a <link linkend="GIOChannel"><type>GIOChannel</type></link>, creating it as necessary
 741 </simpara></listitem></varlistentry>
 742 <varlistentry><term><parameter>open_mode</parameter>&nbsp;:</term>
 743 <listitem><simpara> open for reading, writing, random, etc
 744 </simpara></listitem></varlistentry>
 745 <varlistentry><term><parameter>exclusive</parameter>&nbsp;:</term>
 746 <listitem><simpara> replace the file if it already exists
 747 </simpara></listitem></varlistentry>
 748 <varlistentry><term><parameter>perm</parameter>&nbsp;:</term>
 749 <listitem><simpara> standard POSIX-style permissions bitmask, permissions of created file
 750 </simpara></listitem></varlistentry>
 751 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
 752 <listitem><simpara> a value from <literal>GNOME_VFS_PRIORITY_MIN</literal> to <literal>GNOME_VFS_PRIORITY_MAX</literal> (normally
 753 should be <literal>GNOME_VFS_PRIORITY_DEFAULT</literal>) indicating the priority to assign this job
 754 in allocating threads from the thread pool.
 755 </simpara></listitem></varlistentry>
 756 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
 757 <listitem><simpara> function to be called when the operation is complete
 758 </simpara></listitem></varlistentry>
 759 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 760 <listitem><simpara> data to pass <parameter>callback</parameter>
 761 </simpara></listitem></varlistentry>
 762 </variablelist></refsect2>
 763 <refsect2>
 764 <title><anchor id="gnome-vfs-async-create-uri-as-channel"/>gnome_vfs_async_create_uri_as_channel ()</title>
 765 <indexterm><primary>gnome_vfs_async_create_uri_as_channel</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_create_uri_as_channel
 766                                             (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 767                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
 768                                              <link linkend="GnomeVFSOpenMode">GnomeVFSOpenMode</link> open_mode,
 769                                              <link linkend="gboolean">gboolean</link> exclusive,
 770                                              <link linkend="guint">guint</link> perm,
 771                                              <link linkend="int">int</link> priority,
 772                                              <link linkend="GnomeVFSAsyncCreateAsChannelCallback">GnomeVFSAsyncCreateAsChannelCallback</link> callback,
 773                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 774 <para>
 775
 776 </para><variablelist role="params">
 777 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
 778 <listitem><simpara>
 779 </simpara></listitem></varlistentry>
 780 <varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
 781 <listitem><simpara>
 782 </simpara></listitem></varlistentry>
 783 <varlistentry><term><parameter>open_mode</parameter>&nbsp;:</term>
 784 <listitem><simpara>
 785 </simpara></listitem></varlistentry>
 786 <varlistentry><term><parameter>exclusive</parameter>&nbsp;:</term>
 787 <listitem><simpara>
 788 </simpara></listitem></varlistentry>
 789 <varlistentry><term><parameter>perm</parameter>&nbsp;:</term>
 790 <listitem><simpara>
 791 </simpara></listitem></varlistentry>
 792 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
 793 <listitem><simpara>
 794 </simpara></listitem></varlistentry>
 795 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
 796 <listitem><simpara>
 797 </simpara></listitem></varlistentry>
 798 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 799 <listitem><simpara>
 800
 801
 802 </simpara></listitem></varlistentry>
 803 </variablelist></refsect2>
 804 <refsect2>
 805 <title><anchor id="gnome-vfs-async-close"/>gnome_vfs_async_close ()</title>
 806 <indexterm><primary>gnome_vfs_async_close</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_close           (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle,
 807                                              <link linkend="GnomeVFSAsyncCloseCallback">GnomeVFSAsyncCloseCallback</link> callback,
 808                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 809 <para>
 810 Close a handle opened with <link linkend="gnome-vfs-async-open"><function>gnome_vfs_async_open()</function></link>. When the close
 811 has completed, <parameter>callback</parameter> will be called with <parameter>callback_data</parameter> and
 812 the result of the operation.</para>
 813 <para>
 814
 815 </para><variablelist role="params">
 816 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
 817 <listitem><simpara> async handle to close
 818 </simpara></listitem></varlistentry>
 819 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
 820 <listitem><simpara> function to be called when the operation is complete
 821 </simpara></listitem></varlistentry>
 822 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 823 <listitem><simpara> data to pass <parameter>callback</parameter>
 824 </simpara></listitem></varlistentry>
 825 </variablelist></refsect2>
 826 <refsect2>
 827 <title><anchor id="gnome-vfs-async-read"/>gnome_vfs_async_read ()</title>
 828 <indexterm><primary>gnome_vfs_async_read</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_read            (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle,
 829                                              <link linkend="gpointer">gpointer</link> buffer,
 830                                              <link linkend="guint">guint</link> bytes,
 831                                              <link linkend="GnomeVFSAsyncReadCallback">GnomeVFSAsyncReadCallback</link> callback,
 832                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 833 <para>
 834 Read <parameter>bytes</parameter> bytes from the file pointed to be <parameter>handle</parameter> into <parameter>buffer</parameter>.
 835 When the operation is complete, <parameter>callback</parameter> will be called with the
 836 result of the operation and <parameter>callback_data</parameter>.</para>
 837 <para>
 838
 839 </para><variablelist role="params">
 840 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
 841 <listitem><simpara> handle for the file to be read
 842 </simpara></listitem></varlistentry>
 843 <varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
 844 <listitem><simpara> allocated block of memory to read into
 845 </simpara></listitem></varlistentry>
 846 <varlistentry><term><parameter>bytes</parameter>&nbsp;:</term>
 847 <listitem><simpara> number of bytes to read
 848 </simpara></listitem></varlistentry>
 849 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
 850 <listitem><simpara> function to be called when the operation is complete
 851 </simpara></listitem></varlistentry>
 852 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 853 <listitem><simpara> data to pass <parameter>callback</parameter>
 854 </simpara></listitem></varlistentry>
 855 </variablelist></refsect2>
 856 <refsect2>
 857 <title><anchor id="gnome-vfs-async-write"/>gnome_vfs_async_write ()</title>
 858 <indexterm><primary>gnome_vfs_async_write</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_write           (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle,
 859                                              <link linkend="gconstpointer">gconstpointer</link> buffer,
 860                                              <link linkend="guint">guint</link> bytes,
 861                                              <link linkend="GnomeVFSAsyncWriteCallback">GnomeVFSAsyncWriteCallback</link> callback,
 862                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 863 <para>
 864 Write <parameter>bytes</parameter> bytes from <parameter>buffer</parameter> into the file pointed to be <parameter>handle</parameter>.
 865 When the operation is complete, <parameter>callback</parameter> will be called with the
 866 result of the operation and <parameter>callback_data</parameter>.</para>
 867 <para>
 868
 869 </para><variablelist role="params">
 870 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
 871 <listitem><simpara> handle for the file to be written
 872 </simpara></listitem></varlistentry>
 873 <varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
 874 <listitem><simpara> block of memory containing data to be written
 875 </simpara></listitem></varlistentry>
 876 <varlistentry><term><parameter>bytes</parameter>&nbsp;:</term>
 877 <listitem><simpara> number of bytes to write
 878 </simpara></listitem></varlistentry>
 879 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
 880 <listitem><simpara> function to be called when the operation is complete
 881 </simpara></listitem></varlistentry>
 882 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 883 <listitem><simpara> data to pass <parameter>callback</parameter>
 884 </simpara></listitem></varlistentry>
 885 </variablelist></refsect2>
 886 <refsect2>
 887 <title><anchor id="gnome-vfs-async-get-file-info"/>gnome_vfs_async_get_file_info ()</title>
 888 <indexterm><primary>gnome_vfs_async_get_file_info</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_get_file_info   (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 889                                              <link linkend="GList">GList</link> *uri_list,
 890                                              <link linkend="GnomeVFSFileInfoOptions">GnomeVFSFileInfoOptions</link> options,
 891                                              <link linkend="int">int</link> priority,
 892                                              <link linkend="GnomeVFSAsyncGetFileInfoCallback">GnomeVFSAsyncGetFileInfoCallback</link> callback,
 893                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 894 <para>
 895 Fetch information about the files indicated in <parameter>uris</parameter> and return the
 896 information progressively to <parameter>callback</parameter>.</para>
 897 <para>
 898
 899 </para><variablelist role="params">
 900 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
 901 <listitem><simpara> when the function returns will point to a handle for
 902 the async operation.
 903 </simpara></listitem></varlistentry>
 904 <varlistentry><term><parameter>uri_list</parameter>&nbsp;:</term>
 905 <listitem><simpara> a GList of GnomeVFSURIs to fetch information about
 906 </simpara></listitem></varlistentry>
 907 <varlistentry><term><parameter>options</parameter>&nbsp;:</term>
 908 <listitem><simpara> packed boolean type providing control over various details
 909 of the get_file_info operation.
 910 </simpara></listitem></varlistentry>
 911 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
 912 <listitem><simpara> a value from <literal>GNOME_VFS_PRIORITY_MIN</literal> to <literal>GNOME_VFS_PRIORITY_MAX</literal> (normally
 913 should be <literal>GNOME_VFS_PRIORITY_DEFAULT</literal>) indicating the priority to assign this job
 914 in allocating threads from the thread pool.
 915 </simpara></listitem></varlistentry>
 916 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
 917 <listitem><simpara> function to be called when the operation is complete
 918 </simpara></listitem></varlistentry>
 919 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 920 <listitem><simpara> data to pass <parameter>callback</parameter>
 921 </simpara></listitem></varlistentry>
 922 </variablelist></refsect2>
 923 <refsect2>
 924 <title><anchor id="gnome-vfs-async-set-file-info"/>gnome_vfs_async_set_file_info ()</title>
 925 <indexterm><primary>gnome_vfs_async_set_file_info</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_set_file_info   (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 926                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
 927                                              <link linkend="GnomeVFSFileInfo">GnomeVFSFileInfo</link> *info,
 928                                              <link linkend="GnomeVFSSetFileInfoMask">GnomeVFSSetFileInfoMask</link> mask,
 929                                              <link linkend="GnomeVFSFileInfoOptions">GnomeVFSFileInfoOptions</link> options,
 930                                              <link linkend="int">int</link> priority,
 931                                              <link linkend="GnomeVFSAsyncSetFileInfoCallback">GnomeVFSAsyncSetFileInfoCallback</link> callback,
 932                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 933 <para>
 934 Set "file info" details about the file at <parameter>uri</parameter>, such as permissions, name,
 935 owner, and modification time.</para>
 936 <para>
 937
 938 </para><variablelist role="params">
 939 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
 940 <listitem><simpara> when the function returns will point to a handle for
 941 the async operation.
 942 </simpara></listitem></varlistentry>
 943 <varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
 944 <listitem><simpara> the URI to set the file info of
 945 </simpara></listitem></varlistentry>
 946 <varlistentry><term><parameter>info</parameter>&nbsp;:</term>
 947 <listitem><simpara> the struct containing new information about the file
 948 </simpara></listitem></varlistentry>
 949 <varlistentry><term><parameter>mask</parameter>&nbsp;:</term>
 950 <listitem><simpara> control which fields of <parameter>info</parameter> are changed about the file at <parameter>uri</parameter>
 951 </simpara></listitem></varlistentry>
 952 <varlistentry><term><parameter>options</parameter>&nbsp;:</term>
 953 <listitem><simpara> packed boolean type providing control over various details
 954 of the set_file_info operation.
 955 </simpara></listitem></varlistentry>
 956 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
 957 <listitem><simpara> a value from <literal>GNOME_VFS_PRIORITY_MIN</literal> to <literal>GNOME_VFS_PRIORITY_MAX</literal> (normally
 958 should be <literal>GNOME_VFS_PRIORITY_DEFAULT</literal>) indicating the priority to assign this job
 959 in allocating threads from the thread pool.
 960 </simpara></listitem></varlistentry>
 961 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
 962 <listitem><simpara> function to be called when the operation is complete
 963 </simpara></listitem></varlistentry>
 964 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
 965 <listitem><simpara> data to pass <parameter>callback</parameter>
 966 </simpara></listitem></varlistentry>
 967 </variablelist></refsect2>
 968 <refsect2>
 969 <title><anchor id="gnome-vfs-async-load-directory"/>gnome_vfs_async_load_directory ()</title>
 970 <indexterm><primary>gnome_vfs_async_load_directory</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_load_directory  (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
 971                                              const <link linkend="gchar">gchar</link> *text_uri,
 972                                              <link linkend="GnomeVFSFileInfoOptions">GnomeVFSFileInfoOptions</link> options,
 973                                              <link linkend="guint">guint</link> items_per_notification,
 974                                              <link linkend="int">int</link> priority,
 975                                              <link linkend="GnomeVFSAsyncDirectoryLoadCallback">GnomeVFSAsyncDirectoryLoadCallback</link> callback,
 976                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
 977 <para>
 978 Read the contents of the directory at <parameter>text_uri</parameter>, passing back GnomeVFSFileInfo
 979 structs about each file in the directory to <parameter>callback</parameter>. <parameter>items_per_notification</parameter>
 980 files will be processed between each call to <parameter>callback</parameter>.</para>
 981 <para>
 982
 983 </para><variablelist role="params">
 984 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
 985 <listitem><simpara> when the function returns will point to a handle for
 986 the async operation.
 987 </simpara></listitem></varlistentry>
 988 <varlistentry><term><parameter>text_uri</parameter>&nbsp;:</term>
 989 <listitem><simpara> string representing the URI of the directory to be loaded
 990 </simpara></listitem></varlistentry>
 991 <varlistentry><term><parameter>options</parameter>&nbsp;:</term>
 992 <listitem><simpara> packed boolean type providing control over various details
 993 of the get_file_info operation.
 994 </simpara></listitem></varlistentry>
 995 <varlistentry><term><parameter>items_per_notification</parameter>&nbsp;:</term>
 996 <listitem><simpara> number of files to process in a row before calling <parameter>callback</parameter>
 997 </simpara></listitem></varlistentry>
 998 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
 999 <listitem><simpara> a value from <literal>GNOME_VFS_PRIORITY_MIN</literal> to <literal>GNOME_VFS_PRIORITY_MAX</literal> (normally
1000 should be <literal>GNOME_VFS_PRIORITY_DEFAULT</literal>) indicating the priority to assign this job
1001 in allocating threads from the thread pool.
1002 </simpara></listitem></varlistentry>
1003 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
1004 <listitem><simpara> function to be called when the operation is complete
1005 </simpara></listitem></varlistentry>
1006 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
1007 <listitem><simpara> data to pass <parameter>callback</parameter>
1008 </simpara></listitem></varlistentry>
1009 </variablelist></refsect2>
1010 <refsect2>
1011 <title><anchor id="gnome-vfs-async-load-directory-uri"/>gnome_vfs_async_load_directory_uri ()</title>
1012 <indexterm><primary>gnome_vfs_async_load_directory_uri</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_load_directory_uri
1013                                             (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
1014                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> *uri,
1015                                              <link linkend="GnomeVFSFileInfoOptions">GnomeVFSFileInfoOptions</link> options,
1016                                              <link linkend="guint">guint</link> items_per_notification,
1017                                              <link linkend="int">int</link> priority,
1018                                              <link linkend="GnomeVFSAsyncDirectoryLoadCallback">GnomeVFSAsyncDirectoryLoadCallback</link> callback,
1019                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
1020 <para>
1021 Read the contents of the directory at <parameter>uri</parameter>, passing back GnomeVFSFileInfo structs
1022 about each file in the directory to <parameter>callback</parameter>. <parameter>items_per_notification</parameter>
1023 files will be processed between each call to <parameter>callback</parameter>.</para>
1024 <para>
1025
1026 </para><variablelist role="params">
1027 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
1028 <listitem><simpara> when the function returns will point to a handle for
1029 the async operation.
1030 </simpara></listitem></varlistentry>
1031 <varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
1032 <listitem><simpara> string representing the URI of the directory to be loaded
1033 </simpara></listitem></varlistentry>
1034 <varlistentry><term><parameter>options</parameter>&nbsp;:</term>
1035 <listitem><simpara> packed boolean type providing control over various details
1036 of the get_file_info operation.
1037 </simpara></listitem></varlistentry>
1038 <varlistentry><term><parameter>items_per_notification</parameter>&nbsp;:</term>
1039 <listitem><simpara> number of files to process in a row before calling <parameter>callback</parameter>
1040 </simpara></listitem></varlistentry>
1041 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
1042 <listitem><simpara> a value from <literal>GNOME_VFS_PRIORITY_MIN</literal> to <literal>GNOME_VFS_PRIORITY_MAX</literal> (normally
1043 should be <literal>GNOME_VFS_PRIORITY_DEFAULT</literal>) indicating the priority to assign this job
1044 in allocating threads from the thread pool.
1045 </simpara></listitem></varlistentry>
1046 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
1047 <listitem><simpara> function to be called when the operation is complete
1048 </simpara></listitem></varlistentry>
1049 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
1050 <listitem><simpara> data to pass <parameter>callback</parameter>
1051 </simpara></listitem></varlistentry>
1052 </variablelist></refsect2>
1053 <refsect2>
1054 <title><anchor id="gnome-vfs-async-xfer"/>gnome_vfs_async_xfer ()</title>
1055 <indexterm><primary>gnome_vfs_async_xfer</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_async_xfer         (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
1056                                              <link linkend="GList">GList</link> *source_uri_list,
1057                                              <link linkend="GList">GList</link> *target_uri_list,
1058                                              <link linkend="GnomeVFSXferOptions">GnomeVFSXferOptions</link> xfer_options,
1059                                              <link linkend="GnomeVFSXferErrorMode">GnomeVFSXferErrorMode</link> error_mode,
1060                                              <link linkend="GnomeVFSXferOverwriteMode">GnomeVFSXferOverwriteMode</link> overwrite_mode,
1061                                              <link linkend="int">int</link> priority,
1062                                              <link linkend="GnomeVFSAsyncXferProgressCallback">GnomeVFSAsyncXferProgressCallback</link> progress_update_callback,
1063                                              <link linkend="gpointer">gpointer</link> update_callback_data,
1064                                              <link linkend="GnomeVFSXferProgressCallback">GnomeVFSXferProgressCallback</link> progress_sync_callback,
1065                                              <link linkend="gpointer">gpointer</link> sync_callback_data);</programlisting>
1066 <para>
1067 Perform a copy operation in a seperate thread. <parameter>progress_update_callback</parameter> will be periodically
1068 polled with status of the operation (percent done, the current phase of operation, the
1069 current file being operated upon). If the xfer engine needs to query the caller to make
1070 a decision or report on important error it will do so on <parameter>progress_sync_callback</parameter>.</para>
1071 <para>
1072
1073 </para><variablelist role="params">
1074 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
1075 <listitem><simpara> when the function returns will point to a handle for
1076 </simpara></listitem></varlistentry>
1077 <varlistentry><term><parameter>source_uri_list</parameter>&nbsp;:</term>
1078 <listitem><simpara> <link linkend="GList"><type>GList</type></link> of <link linkend="GnomeVFSURI"><type>GnomeVFSURI</type></link> representing the files to be transferred
1079 </simpara></listitem></varlistentry>
1080 <varlistentry><term><parameter>target_uri_list</parameter>&nbsp;:</term>
1081 <listitem><simpara> <link linkend="GList"><type>GList</type></link> of <link linkend="GnomeVFSURI"><type>GnomeVFSURI</type></link>, the target locations for the elements
1082 in <parameter>source_uri_list</parameter>
1083 </simpara></listitem></varlistentry>
1084 <varlistentry><term><parameter>xfer_options</parameter>&nbsp;:</term>
1085 <listitem><simpara> various options controlling the details of the transfer.
1086 Use <literal>GNOME_VFS_XFER_REMOUVESOURCE</literal> to make the operation a move rather than a copy.
1087 </simpara></listitem></varlistentry>
1088 <varlistentry><term><parameter>error_mode</parameter>&nbsp;:</term>
1089 <listitem><simpara> report errors to the <parameter>progress_sync_callback</parameter>, or simply abort
1090 </simpara></listitem></varlistentry>
1091 <varlistentry><term><parameter>overwrite_mode</parameter>&nbsp;:</term>
1092 <listitem><simpara> controls whether the xfer engine will overwrite automatically,
1093 skip the file, abort the operation, or query <parameter>progress_sync_callback</parameter>
1094 </simpara></listitem></varlistentry>
1095 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
1096 <listitem><simpara> a value from <literal>GNOME_VFS_PRIORITY_MIN</literal> to <literal>GNOME_VFS_PRIORITY_MAX</literal> (normally
1097 should be <literal>GNOME_VFS_PRIORITY_DEFAULT</literal>) indicating the priority to assign this job
1098 in allocating threads from the thread pool.
1099 </simpara></listitem></varlistentry>
1100 <varlistentry><term><parameter>progress_update_callback</parameter>&nbsp;:</term>
1101 <listitem><simpara> called periodically to keep the client appraised of progress
1102 in completing the XFer operation, and the current phase of operation.
1103 </simpara></listitem></varlistentry>
1104 <varlistentry><term><parameter>update_callback_data</parameter>&nbsp;:</term>
1105 <listitem><simpara> user data passed to <parameter>progress_update_callback</parameter>
1106 </simpara></listitem></varlistentry>
1107 <varlistentry><term><parameter>progress_sync_callback</parameter>&nbsp;:</term>
1108 <listitem><simpara> called when the program requires responses to interactive queries
1109 (e.g. overwriting files, handling errors, etc)
1110 </simpara></listitem></varlistentry>
1111 <varlistentry><term><parameter>sync_callback_data</parameter>&nbsp;:</term>
1112 <listitem><simpara> user data passed to <parameter>progress_sync_callback</parameter>
1113 </simpara></listitem></varlistentry>
1114 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>GNOME_VFS_OK</literal> if the paramaters were in order,
1115 or <literal>GNOME_VFS_ERROR_BAD_PARAMETERS</literal> if something was wrong in the passed in arguments.
1116 </simpara></listitem></varlistentry>
1117 </variablelist></refsect2>
1118 <refsect2>
1119 <title><anchor id="gnome-vfs-async-find-directory"/>gnome_vfs_async_find_directory ()</title>
1120 <indexterm><primary>gnome_vfs_async_find_directory</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_find_directory  (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> **handle_return,
1121                                              <link linkend="GList">GList</link> *near_uri_list,
1122                                              <link linkend="GnomeVFSFindDirectoryKind">GnomeVFSFindDirectoryKind</link> kind,
1123                                              <link linkend="gboolean">gboolean</link> create_if_needed,
1124                                              <link linkend="gboolean">gboolean</link> find_if_needed,
1125                                              <link linkend="guint">guint</link> permissions,
1126                                              <link linkend="int">int</link> priority,
1127                                              <link linkend="GnomeVFSAsyncFindDirectoryCallback">GnomeVFSAsyncFindDirectoryCallback</link> callback,
1128                                              <link linkend="gpointer">gpointer</link> user_data);</programlisting>
1129 <para>
1130 There is quite a complicated logic behind finding/creating a Trash directory
1131 and you need to be aware of some implications:
1132 Finding the Trash the first time when using the file method may be pretty
1133 expensive. A cache file is used to store the location of that Trash file
1134 for next time.
1135 If <parameter>ceate_if_needed</parameter> is specified without <parameter>find_if_needed</parameter>, you may end up
1136 creating a Trash file when there already is one. Your app should start out
1137 by doing a gnome_vfs_find_directory with the <parameter>find_if_needed</parameter> to avoid this
1138 and then use the <parameter>create_if_needed</parameter> flag to create Trash lazily when it is
1139 needed for throwing away an item on a given disk.
1140 </para>
1141 <para>
1142 When the operation has completed, <parameter>callback</parameter> will be called with the result
1143 of the operation and <parameter>user_data</parameter>.</para>
1144 <para>
1145
1146 </para><variablelist role="params">
1147 <varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
1148 <listitem><simpara> when the function returns will point to a handle for
1149 </simpara></listitem></varlistentry>
1150 <varlistentry><term><parameter>near_uri_list</parameter>&nbsp;:</term>
1151 <listitem><simpara> a GList of GnomeVFSURIs, find a special directory on the same
1152 volume as <parameter>uris</parameter>
1153 </simpara></listitem></varlistentry>
1154 <varlistentry><term><parameter>kind</parameter>&nbsp;:</term>
1155 <listitem><simpara> kind of special directory
1156 </simpara></listitem></varlistentry>
1157 <varlistentry><term><parameter>create_if_needed</parameter>&nbsp;:</term>
1158 <listitem><simpara> If directory we are looking for does not exist, try to create it
1159 </simpara></listitem></varlistentry>
1160 <varlistentry><term><parameter>find_if_needed</parameter>&nbsp;:</term>
1161 <listitem><simpara> If we don't know where the directory is yet, look for it.
1162 </simpara></listitem></varlistentry>
1163 <varlistentry><term><parameter>permissions</parameter>&nbsp;:</term>
1164 <listitem><simpara> If creating, use these permissions
1165 </simpara></listitem></varlistentry>
1166 <varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
1167 <listitem><simpara> a value from <literal>GNOME_VFS_PRIORITY_MIN</literal> to <literal>GNOME_VFS_PRIORITY_MAX</literal> (normally
1168 should be <literal>GNOME_VFS_PRIORITY_DEFAULT</literal>) indicating the priority to assign this job
1169 in allocating threads from the thread pool.
1170 </simpara></listitem></varlistentry>
1171 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
1172 <listitem><simpara> function to be called when the operation is complete
1173 </simpara></listitem></varlistentry>
1174 <varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
1175 <listitem><simpara> data to pass <parameter>callback</parameter> *
1176 Used to return special directories such as Trash and Desktop from different
1177 file systems.
1178 </simpara></listitem></varlistentry>
1179 </variablelist></refsect2>
1180 <refsect2>
1181 <title><anchor id="gnome-vfs-async-file-control"/>gnome_vfs_async_file_control ()</title>
1182 <indexterm><primary>gnome_vfs_async_file_control</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_file_control    (<link linkend="GnomeVFSAsyncHandle">GnomeVFSAsyncHandle</link> *handle,
1183                                              const <link linkend="char">char</link> *operation,
1184                                              <link linkend="gpointer">gpointer</link> operation_data,
1185                                              <link linkend="GDestroyNotify">GDestroyNotify</link> operation_data_destroy_func,
1186                                              <link linkend="GnomeVFSAsyncFileControlCallback">GnomeVFSAsyncFileControlCallback</link> callback,
1187                                              <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
1188 <para>
1189 Execute a backend dependent operation specified by the string <parameter>operation</parameter>.
1190 This is typically used for specialized vfs backends that need additional
1191 operations that gnome-vfs doesn't have. Compare it to the unix call <link linkend="ioctl"><function>ioctl()</function></link>.
1192 The format of <parameter>operation_data</parameter> depends on the operation. Operation that are
1193 backend specific are normally namespaced by their module name.
1194 </para>
1195 <para>
1196 When the operation is complete, <parameter>callback</parameter> will be called with the
1197 result of the operation, <parameter>operation_data</parameter> and <parameter>callback_data</parameter>.</para>
1198 <para>
1199
1200 </para><variablelist role="params">
1201 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
1202 <listitem><simpara> handle of the file to affect
1203 </simpara></listitem></varlistentry>
1204 <varlistentry><term><parameter>operation</parameter>&nbsp;:</term>
1205 <listitem><simpara> The operation to execute
1206 </simpara></listitem></varlistentry>
1207 <varlistentry><term><parameter>operation_data</parameter>&nbsp;:</term>
1208 <listitem><simpara> The data needed to execute the operation
1209 </simpara></listitem></varlistentry>
1210 <varlistentry><term><parameter>operation_data_destroy_func</parameter>&nbsp;:</term>
1211 <listitem><simpara> Called to destroy operation_data when its no longer needed
1212 </simpara></listitem></varlistentry>
1213 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
1214 <listitem><simpara> function to be called when the operation is complete
1215 </simpara></listitem></varlistentry>
1216 <varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
1217 <listitem><simpara> data to pass <parameter>callback</parameter>
1218 </simpara></listitem></varlistentry>
1219 </variablelist><para>Since  2.2
1220 </para></refsect2>
1221
1222 </refsect1>
1223
1224
1225
1226
1227 </refentry>