doc/tmpl/gnome-vfs-async-ops.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Asynchronous File Operations
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5
   6 POSIX-style file operations that run outside your main loop
   7
   8 <!-- ##### SECTION Long_Description ##### -->
   9 <para>
  10   When executing an asynchornous operation on a file the program does not
  11   block waiting for the operation to finish, instead it keeps on running,
  12   which means that the process and the I/O operation can be both running
  13   concurrently. Once the I/O operation has been completed the process is
  14   notified using a callback.
  15 </para>
  16
  17 <para>
  18   Asynchronous operations are particularly good when long I/O operations
  19   are expected, in this case the program can continue normaly, the I/O
  20   will be performed in the background. On the other hand when operations
  21   are expected to be short (creating a file, writing/reading small amounts
  22   of data, etc.) synchronous operations are prefered.
  23 </para>
  24
  25 <para>
  26   Within a graphical desktop asynchornous I/O operations can be used to
  27   avoid blocking the UI (User Interface) during a long operation, and
  28   to be able to provide some kind of feedback to the user.
  29 </para>
  30
  31 <!-- ##### SECTION See_Also ##### -->
  32 <para>
  33
  34 </para>
  35
  36 <!-- ##### MACRO GNOME_VFS_PRIORITY_MIN ##### -->
  37 <para>
  38
  39 </para>
  40
  41
  42
  43 <!-- ##### MACRO GNOME_VFS_PRIORITY_MAX ##### -->
  44 <para>
  45
  46 </para>
  47
  48
  49
  50 <!-- ##### MACRO GNOME_VFS_PRIORITY_DEFAULT ##### -->
  51 <para>
  52
  53 </para>
  54
  55
  56
  57 <!-- ##### USER_FUNCTION GnomeVFSAsyncCallback ##### -->
  58 <para>
  59
  60 </para>
  61
  62 @handle:
  63 @result:
  64 @callback_data:
  65
  66
  67 <!-- ##### TYPEDEF GnomeVFSAsyncOpenCallback ##### -->
  68 <para>
  69
  70 </para>
  71
  72
  73 <!-- ##### TYPEDEF GnomeVFSAsyncCreateCallback ##### -->
  74 <para>
  75
  76 </para>
  77
  78
  79 <!-- ##### TYPEDEF GnomeVFSAsyncCreateAsChannelCallback ##### -->
  80 <para>
  81
  82 </para>
  83
  84
  85 <!-- ##### TYPEDEF GnomeVFSAsyncCloseCallback ##### -->
  86 <para>
  87
  88 </para>
  89
  90
  91 <!-- ##### USER_FUNCTION GnomeVFSAsyncReadCallback ##### -->
  92 <para>
  93
  94 </para>
  95
  96 @handle:
  97 @result:
  98 @buffer:
  99 @bytes_requested:
 100 @bytes_read:
 101 @callback_data:
 102
 103
 104 <!-- ##### USER_FUNCTION GnomeVFSAsyncWriteCallback ##### -->
 105 <para>
 106
 107 </para>
 108
 109 @handle:
 110 @result:
 111 @buffer:
 112 @bytes_requested:
 113 @bytes_written:
 114 @callback_data:
 115
 116
 117 <!-- ##### TYPEDEF GnomeVFSFindDirectoryResult ##### -->
 118 <para>
 119
 120 </para>
 121
 122
 123 <!-- ##### FUNCTION gnome_vfs_async_set_job_limit ##### -->
 124 <para>
 125
 126 </para>
 127
 128 @limit:
 129
 130
 131 <!-- ##### FUNCTION gnome_vfs_async_get_job_limit ##### -->
 132 <para>
 133
 134 </para>
 135
 136 @Returns:
 137
 138
 139 <!-- ##### FUNCTION gnome_vfs_async_cancel ##### -->
 140 <para>
 141
 142 </para>
 143
 144 @handle:
 145
 146
 147 <!-- ##### FUNCTION gnome_vfs_async_open ##### -->
 148 <para>
 149
 150 </para>
 151
 152 @handle_return:
 153 @text_uri:
 154 @open_mode:
 155 @priority:
 156 @callback:
 157 @callback_data:
 158
 159
 160 <!-- ##### FUNCTION gnome_vfs_async_open_uri ##### -->
 161 <para>
 162
 163 </para>
 164
 165 @handle_return:
 166 @uri:
 167 @open_mode:
 168 @priority:
 169 @callback:
 170 @callback_data:
 171
 172
 173 <!-- ##### FUNCTION gnome_vfs_async_open_as_channel ##### -->
 174 <para>
 175
 176 </para>
 177
 178 @handle_return:
 179 @text_uri:
 180 @open_mode:
 181 @advised_block_size:
 182 @priority:
 183 @callback:
 184 @callback_data:
 185
 186
 187 <!-- ##### FUNCTION gnome_vfs_async_open_uri_as_channel ##### -->
 188 <para>
 189
 190 </para>
 191
 192 @handle_return:
 193 @uri:
 194 @open_mode:
 195 @advised_block_size:
 196 @priority:
 197 @callback:
 198 @callback_data:
 199
 200
 201 <!-- ##### FUNCTION gnome_vfs_async_create ##### -->
 202 <para>
 203
 204 </para>
 205
 206 @handle_return:
 207 @text_uri:
 208 @open_mode:
 209 @exclusive:
 210 @perm:
 211 @priority:
 212 @callback:
 213 @callback_data:
 214
 215
 216 <!-- ##### FUNCTION gnome_vfs_async_create_uri ##### -->
 217 <para>
 218
 219 </para>
 220
 221 @handle_return:
 222 @uri:
 223 @open_mode:
 224 @exclusive:
 225 @perm:
 226 @priority:
 227 @callback:
 228 @callback_data:
 229
 230
 231 <!-- ##### FUNCTION gnome_vfs_async_create_symbolic_link ##### -->
 232 <para>
 233
 234 </para>
 235
 236 @handle_return:
 237 @uri:
 238 @uri_reference:
 239 @priority:
 240 @callback:
 241 @callback_data:
 242
 243
 244 <!-- ##### FUNCTION gnome_vfs_async_create_as_channel ##### -->
 245 <para>
 246
 247 </para>
 248
 249 @handle_return:
 250 @text_uri:
 251 @open_mode:
 252 @exclusive:
 253 @perm:
 254 @priority:
 255 @callback:
 256 @callback_data:
 257
 258
 259 <!-- ##### FUNCTION gnome_vfs_async_create_uri_as_channel ##### -->
 260 <para>
 261
 262 </para>
 263
 264 @handle_return:
 265 @uri:
 266 @open_mode:
 267 @exclusive:
 268 @perm:
 269 @priority:
 270 @callback:
 271 @callback_data:
 272
 273
 274 <!-- ##### FUNCTION gnome_vfs_async_close ##### -->
 275 <para>
 276
 277 </para>
 278
 279 @handle:
 280 @callback:
 281 @callback_data:
 282
 283
 284 <!-- ##### FUNCTION gnome_vfs_async_read ##### -->
 285 <para>
 286
 287 </para>
 288
 289 @handle:
 290 @buffer:
 291 @bytes:
 292 @callback:
 293 @callback_data:
 294
 295
 296 <!-- ##### FUNCTION gnome_vfs_async_write ##### -->
 297 <para>
 298
 299 </para>
 300
 301 @handle:
 302 @buffer:
 303 @bytes:
 304 @callback:
 305 @callback_data:
 306
 307
 308 <!-- ##### FUNCTION gnome_vfs_async_get_file_info ##### -->
 309 <para>
 310
 311 </para>
 312
 313 @handle_return:
 314 @uri_list:
 315 @options:
 316 @priority:
 317 @callback:
 318 @callback_data:
 319
 320
 321 <!-- ##### FUNCTION gnome_vfs_async_set_file_info ##### -->
 322 <para>
 323
 324 </para>
 325
 326 @handle_return:
 327 @uri:
 328 @info:
 329 @mask:
 330 @options:
 331 @priority:
 332 @callback:
 333 @callback_data:
 334
 335
 336 <!-- ##### FUNCTION gnome_vfs_async_load_directory ##### -->
 337 <para>
 338
 339 </para>
 340
 341 @handle_return:
 342 @text_uri:
 343 @options:
 344 @items_per_notification:
 345 @priority:
 346 @callback:
 347 @callback_data:
 348
 349
 350 <!-- ##### FUNCTION gnome_vfs_async_load_directory_uri ##### -->
 351 <para>
 352
 353 </para>
 354
 355 @handle_return:
 356 @uri:
 357 @options:
 358 @items_per_notification:
 359 @priority:
 360 @callback:
 361 @callback_data:
 362
 363
 364 <!-- ##### FUNCTION gnome_vfs_async_xfer ##### -->
 365 <para>
 366
 367 </para>
 368
 369 @handle_return:
 370 @source_uri_list:
 371 @target_uri_list:
 372 @xfer_options:
 373 @error_mode:
 374 @overwrite_mode:
 375 @priority:
 376 @progress_update_callback:
 377 @update_callback_data:
 378 @progress_sync_callback:
 379 @sync_callback_data:
 380 @Returns:
 381
 382
 383 <!-- ##### FUNCTION gnome_vfs_async_find_directory ##### -->
 384 <para>
 385
 386 </para>
 387
 388 @handle_return:
 389 @near_uri_list:
 390 @kind:
 391 @create_if_needed:
 392 @find_if_needed:
 393 @permissions:
 394 @priority:
 395 @callback:
 396 @user_data:
 397
 398
 399 <!-- ##### FUNCTION gnome_vfs_async_file_control ##### -->
 400 <para>
 401
 402 </para>
 403
 404 @handle:
 405 @operation:
 406 @operation_data:
 407 @operation_data_destroy_func:
 408 @callback:
 409 @callback_data:
 410
 411