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

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