libgnomevfs/gnome-vfs-async-ops.h

   1 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
   2
   3 /* gnome-vfs-async-ops.h - Asynchronous operations in the GNOME Virtual File
   4    System.
   5
   6    Copyright (C) 1999 Free Software Foundation
   7
   8    The Gnome Library is free software; you can redistribute it and/or
   9    modify it under the terms of the GNU Library General Public License as
  10    published by the Free Software Foundation; either version 2 of the
  11    License, or (at your option) any later version.
  12
  13    The Gnome Library is distributed in the hope that it will be useful,
  14    but WITHOUT ANY WARRANTY; without even the implied warranty of
  15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16    Library General Public License for more details.
  17
  18    You should have received a copy of the GNU Library General Public
  19    License along with the Gnome Library; see the file COPYING.LIB.  If not,
  20    write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21    Boston, MA 02111-1307, USA.
  22
  23    Author: Ettore Perazzoli <ettore@comm2000.it> */
  24
  25 #ifndef GNOME_VFS_ASYNC_OPS_H
  26 #define GNOME_VFS_ASYNC_OPS_H
  27
  28 #include <glib/giochannel.h>
  29 #include <libgnomevfs/gnome-vfs-file-info.h>
  30 #include <libgnomevfs/gnome-vfs-find-directory.h>
  31 #include <libgnomevfs/gnome-vfs-handle.h>
  32 #include <libgnomevfs/gnome-vfs-xfer.h>
  33
  34 G_BEGIN_DECLS
  35
  36 /**
  37  * GNOME_VFS_PRIORITY_MIN:
  38  *
  39  * The minimuum priority a job can have.
  40  **/
  41 /**
  42  * GNOME_VFS_PRIORITY_MAX:
  43  *
  44  * The maximuum priority a job can have.
  45  **/
  46 /**
  47  * GNOME_VFS_PRIORITY_DEFAULT:
  48  *
  49  * The default job priority. Its best to use this
  50  * unless you have a reason to do otherwise.
  51  **/
  52
  53 #define GNOME_VFS_PRIORITY_MIN     -10
  54 #define GNOME_VFS_PRIORITY_MAX     10
  55 #define GNOME_VFS_PRIORITY_DEFAULT 0
  56
  57 typedef struct GnomeVFSAsyncHandle GnomeVFSAsyncHandle;
  58
  59 /**
  60  * GnomeVFSAsyncCallback:
  61  * @handle: handle of the operation generating the callback
  62  * @result: %GNOME_VFS_OK if the operation was successful, otherwise
  63  * an error code.
  64  * @callback_data: user data defined when the callback was established
  65  *
  66  * Basic callback from an async operation that passes no data back,
  67  * informing the user of the @result of the operation.
  68  **/
  69 typedef void    (* GnomeVFSAsyncCallback)       (GnomeVFSAsyncHandle *handle,
  70                                                  GnomeVFSResult result,
  71                                                  gpointer callback_data);
  72
  73 /**
  74  * GnomeVFSAsyncOpenCallback:
  75  * @handle: handle of the operation generating the callback
  76  * @result: %GNOME_VFS_OK if the operation was successful, otherwise
  77  * an error code.
  78  * @callback_data: user data defined when the callback was established
  79  *
  80  * Basic callback from an async operation that passes no data back,
  81  * informing the user of the @result of the operation.
  82  **/
  83 typedef GnomeVFSAsyncCallback GnomeVFSAsyncOpenCallback;
  84
  85 /**
  86  * GnomeVFSAsyncCreateCallback:
  87  * @handle: handle of the operation generating the callback
  88  * @result: %GNOME_VFS_OK if the operation was successful, otherwise
  89  * an error code.
  90  * @callback_data: user data defined when the callback was established
  91  *
  92  * Basic callback from an async operation that passes no data back,
  93  * informing the user of the @result of the operation.
  94  **/
  95 typedef GnomeVFSAsyncCallback GnomeVFSAsyncCreateCallback;
  96
  97 /**
  98  * GnomeVFSAsyncCloseCallback:
  99  * @handle: handle of the operation generating the callback
 100  * @result: %GNOME_VFS_OK if the operation was successful, otherwise
 101  * an error code.
 102  * @callback_data: user data defined when the callback was established
 103  *
 104  * Basic callback from an async operation that passes no data back,
 105  * informing the user of the @result of the operation.
 106  **/
 107 typedef GnomeVFSAsyncCallback GnomeVFSAsyncCloseCallback;
 108
 109 /**
 110  * GnomeVFSAsyncOpenAsChannelCallback:
 111  * @handle: handle of the operation generating the callback
 112  * @channel: a #GIOChannel corresponding to the file opened
 113  * @result: %GNOME_VFS_OK if the operation was successful, otherwise
 114  * an error code.
 115  * @callback_data: user data defined when the callback was established
 116  *
 117  * Callback for the gnome_vfs_async_open_as_channel() function.
 118  **/
 119 typedef void    (* GnomeVFSAsyncOpenAsChannelCallback)
 120                                                 (GnomeVFSAsyncHandle *handle,
 121                                                  GIOChannel *channel,
 122                                                  GnomeVFSResult result,
 123                                                  gpointer callback_data);
 124
 125 /**
 126  * GnomeVFSAsyncCreateAsChannelCallback:
 127  * @handle: handle of the operation generating the callback
 128  * @channel: a #GIOChannel corresponding to the file created
 129  * @result: %GNOME_VFS_OK if the operation was successful, otherwise
 130  * an error code.
 131  * @callback_data: user data defined when the callback was established
 132  *
 133  * Callback for the gnome_vfs_async_create_as_channel() function.
 134  **/
 135 typedef GnomeVFSAsyncOpenAsChannelCallback GnomeVFSAsyncCreateAsChannelCallback;
 136
 137 /**
 138  * GnomeVFSAsyncReadCallback:
 139  * @handle: handle of the operation generating the callback
 140  * @result: %GNOME_VFS_OK if the operation was successful, otherwise
 141  * an error code.
 142  * @buffer: buffer containing data read from @handle.
 143  * @bytes_requested: the number of bytes asked for in the call to
 144  * gnome_vfs_async_read().
 145  * @bytes_read: the number of bytes actually read from @handle into @buffer.
 146  * @callback_data: user data defined when the callback was established
 147  *
 148  * Callback for the gnome_vfs_async_read() function.
 149  **/
 150 typedef void    (* GnomeVFSAsyncReadCallback)   (GnomeVFSAsyncHandle *handle,
 151                                                  GnomeVFSResult result,
 152                                                  gpointer buffer,
 153                                                  GnomeVFSFileSize bytes_requested,
 154                                                  GnomeVFSFileSize bytes_read,
 155                                                  gpointer callback_data);
 156
 157 /**
 158  * GnomeVFSAsyncWriteCallback:
 159  * @handle: handle of the operation generating the callback
 160  * @result: %GNOME_VFS_OK if the operation was successful, otherwise
 161  * an error code.
 162  * @buffer: buffer containing data written to @handle.
 163  * @bytes_requested: the number of bytes asked to write in the call to
 164  * gnome_vfs_async_write().
 165  * @bytes_written: the number of bytes actually written to @handle from @buffer.
 166  * @callback_data: user data defined when the callback was established
 167  *
 168  * Callback for the gnome_vfs_async_write() function.
 169  **/
 170 typedef void    (* GnomeVFSAsyncWriteCallback)  (GnomeVFSAsyncHandle *handle,
 171                                                  GnomeVFSResult result,
 172                                                  gconstpointer buffer,
 173                                                  GnomeVFSFileSize bytes_requested,
 174                                                  GnomeVFSFileSize bytes_written,
 175                                                  gpointer callback_data);
 176
 177
 178 /**
 179  * GnomeVFSAsyncGetFileInfoCallback:
 180  * @handle: handle of the operation generating the callback
 181  * @results: #GList of #GnomeVFSFileInfoResult * items representing
 182  * the success of each gnome_vfs_get_file_info() and the data retrieved.
 183  * @callback_data: user data defined when the callback was established
 184  *
 185  * Callback for the gnome_vfs_async_get_file_info() function.
 186  **/
 187 typedef void    (* GnomeVFSAsyncGetFileInfoCallback)
 188                                                 (GnomeVFSAsyncHandle *handle,
 189                                                  GList *results, /* GnomeVFSGetFileInfoResult* items */
 190                                                  gpointer callback_data);
 191
 192 /**
 193  * GnomeVFSAsyncSetFileInfoCallback:
 194  * @handle: handle of the operation generating the callback
 195  * @result: %GNOME_VFS_OK if the operation was successful, otherwise a
 196  * #GnomeVFSResult error code
 197  * @file_info: if @result is %GNOME_VFS_OK, a #GnomeVFSFileInfo struct containing
 198  * requested information about the file
 199  * @callback_data: user data defined when the callback was established
 200  *
 201  * Callback for th egnome_vfs_async_set_file_info() function.
 202  **/
 203 typedef void    (* GnomeVFSAsyncSetFileInfoCallback)
 204                                                 (GnomeVFSAsyncHandle *handle,
 205                                                  GnomeVFSResult result,
 206                                                  GnomeVFSFileInfo *file_info,
 207                                                  gpointer callback_data);
 208
 209
 210 /**
 211  * GnomeVFSAsyncDirectoryLoadCallback:
 212  * @handle: handle of the operation generating the callback
 213  * @result: %GNOME_VFS_OK if the operation was sucessful,
 214  * %GNOME_VFS_ERROR_EOF if the last file in the directory
 215  * has been read, otherwise a #GnomeVFSResult error code
 216  * @list: a #GList of #GnomeVFSFileInfo structs representing
 217  * information about the files just loaded
 218  * @entries_read: number of entries read from @handle for this instance of
 219  * the callback.
 220  * @callback_data: user data defined when the callback was established
 221  *
 222  * Callback for the gnome_vfs_async_directory_load() function.
 223  **/
 224 typedef void    (* GnomeVFSAsyncDirectoryLoadCallback)
 225                                                 (GnomeVFSAsyncHandle *handle,
 226                                                  GnomeVFSResult result,
 227                                                  GList *list,
 228                                                  guint entries_read,
 229                                                  gpointer callback_data);
 230
 231 /**
 232  * GnomeVFSAsyncXferProgressCallback:
 233  * @handle: handle of the xfer operation generating the callback
 234  * @info: information on the current progress in the transfer
 235  * @data: user data defined when the transfer was established
 236  *
 237  * Callback for the gnome_vfs_async_xfer() function. Called periodically
 238  * to update the caller about the status of the transfer (percent complete,
 239  * phase of the operation, etc). If @info->status is not %GNOME_VFS_XFER_PROGRESS_STATUS_OK
 240  * then the callback is expected to make a "decision" about some problem / query
 241  * during the operation. The appropriate #GnomeVFSXferErrorAction or #GnomeVFSOverwriteAction
 242  * (depending on the particular state of @info->status) should be returned
 243  * informing the transfer engine how to proceed.
 244  *
 245  * Return value: 0 or an item from #GnomeVFSXferErrorAction or #GnomeVFSOverwriteAction
 246  **/
 247 typedef gint    (* GnomeVFSAsyncXferProgressCallback)
 248                                                 (GnomeVFSAsyncHandle *handle,
 249                                                  GnomeVFSXferProgressInfo *info,
 250                                                  gpointer data);
 251
 252 typedef struct {
 253         GnomeVFSURI *uri;
 254         GnomeVFSResult result;
 255
 256         /* Reserved to avoid future breaks in ABI compatibility */
 257         void *reserved1;
 258         void *reserved2;
 259 } GnomeVFSFindDirectoryResult;
 260
 261 /**
 262  * GnomeVFSAsyncFindDirectoryCallback:
 263  * @handle: handle of the operation generating the callback
 264  * @results: #GList of #GnomeVFSFindDirectoryResult *s containing
 265  * special directories matching the find criteria.
 266  * @data: user data defined when the operation was established
 267  *
 268  * Callback for the gnome_vfs_async_find_directory() function.
 269  **/
 270 typedef void    (* GnomeVFSAsyncFindDirectoryCallback)
 271                                                 (GnomeVFSAsyncHandle *handle,
 272                                                  GList *results /* GnomeVFSFindDirectoryResult */,
 273                                                  gpointer data);
 274
 275 typedef void    (* GnomeVFSAsyncFileControlCallback)    (GnomeVFSAsyncHandle *handle,
 276                                                          GnomeVFSResult result,
 277                                                          gpointer operation_data,
 278                                                          gpointer callback_data);
 279
 280 void           gnome_vfs_async_cancel                 (GnomeVFSAsyncHandle                   *handle);
 281
 282 void           gnome_vfs_async_open                   (GnomeVFSAsyncHandle                  **handle_return,
 283                                                        const gchar                           *text_uri,
 284                                                        GnomeVFSOpenMode                       open_mode,
 285                                                        int                                    priority,
 286                                                        GnomeVFSAsyncOpenCallback              callback,
 287                                                        gpointer                               callback_data);
 288 void           gnome_vfs_async_open_uri               (GnomeVFSAsyncHandle                  **handle_return,
 289                                                        GnomeVFSURI                           *uri,
 290                                                        GnomeVFSOpenMode                       open_mode,
 291                                                        int                                    priority,
 292                                                        GnomeVFSAsyncOpenCallback              callback,
 293                                                        gpointer                               callback_data);
 294 void           gnome_vfs_async_open_as_channel        (GnomeVFSAsyncHandle                  **handle_return,
 295                                                        const gchar                           *text_uri,
 296                                                        GnomeVFSOpenMode                       open_mode,
 297                                                        guint                                  advised_block_size,
 298                                                        int                                    priority,
 299                                                        GnomeVFSAsyncOpenAsChannelCallback     callback,
 300                                                        gpointer                               callback_data);
 301 void           gnome_vfs_async_open_uri_as_channel    (GnomeVFSAsyncHandle                  **handle_return,
 302                                                        GnomeVFSURI                           *uri,
 303                                                        GnomeVFSOpenMode                       open_mode,
 304                                                        guint                                  advised_block_size,
 305                                                        int                                    priority,
 306                                                        GnomeVFSAsyncOpenAsChannelCallback     callback,
 307                                                        gpointer                               callback_data);
 308 void           gnome_vfs_async_create                 (GnomeVFSAsyncHandle                  **handle_return,
 309                                                        const gchar                           *text_uri,
 310                                                        GnomeVFSOpenMode                       open_mode,
 311                                                        gboolean                               exclusive,
 312                                                        guint                                  perm,
 313                                                        int                                    priority,
 314                                                        GnomeVFSAsyncOpenCallback              callback,
 315                                                        gpointer                               callback_data);
 316 void           gnome_vfs_async_create_uri             (GnomeVFSAsyncHandle                  **handle_return,
 317                                                        GnomeVFSURI                           *uri,
 318                                                        GnomeVFSOpenMode                       open_mode,
 319                                                        gboolean                               exclusive,
 320                                                        guint                                  perm,
 321                                                        int                                    priority,
 322                                                        GnomeVFSAsyncOpenCallback              callback,
 323                                                        gpointer                               callback_data);
 324 void           gnome_vfs_async_create_symbolic_link   (GnomeVFSAsyncHandle                  **handle_return,
 325                                                        GnomeVFSURI                           *uri,
 326                                                        const gchar                           *uri_reference,
 327                                                        int                                    priority,
 328                                                        GnomeVFSAsyncOpenCallback              callback,
 329                                                        gpointer                               callback_data);
 330 void           gnome_vfs_async_create_as_channel      (GnomeVFSAsyncHandle                  **handle_return,
 331                                                        const gchar                           *text_uri,
 332                                                        GnomeVFSOpenMode                       open_mode,
 333                                                        gboolean                               exclusive,
 334                                                        guint                                  perm,
 335                                                        int                                    priority,
 336                                                        GnomeVFSAsyncCreateAsChannelCallback   callback,
 337                                                        gpointer                               callback_data);
 338 void           gnome_vfs_async_create_uri_as_channel  (GnomeVFSAsyncHandle                  **handle_return,
 339                                                        GnomeVFSURI                           *uri,
 340                                                        GnomeVFSOpenMode                       open_mode,
 341                                                        gboolean                               exclusive,
 342                                                        guint                                  perm,
 343                                                        int                                    priority,
 344                                                        GnomeVFSAsyncCreateAsChannelCallback   callback,
 345                                                        gpointer                               callback_data);
 346 void           gnome_vfs_async_close                  (GnomeVFSAsyncHandle                   *handle,
 347                                                        GnomeVFSAsyncCloseCallback             callback,
 348                                                        gpointer                               callback_data);
 349 void           gnome_vfs_async_read                   (GnomeVFSAsyncHandle                   *handle,
 350                                                        gpointer                               buffer,
 351                                                        guint                                  bytes,
 352                                                        GnomeVFSAsyncReadCallback              callback,
 353                                                        gpointer                               callback_data);
 354 void           gnome_vfs_async_write                  (GnomeVFSAsyncHandle                   *handle,
 355                                                        gconstpointer                          buffer,
 356                                                        guint                                  bytes,
 357                                                        GnomeVFSAsyncWriteCallback             callback,
 358                                                        gpointer                               callback_data);
 359 void           gnome_vfs_async_get_file_info          (GnomeVFSAsyncHandle                  **handle_return,
 360                                                        GList                                 *uri_list,
 361                                                        GnomeVFSFileInfoOptions                options,
 362                                                        int                                    priority,
 363                                                        GnomeVFSAsyncGetFileInfoCallback       callback,
 364                                                        gpointer                               callback_data);
 365
 366 /* Setting the file info sometimes changes more info than the
 367  * caller specified; for example, if the name changes the MIME type might
 368  * change, and if the owner changes the SUID & SGID bits might change.
 369  * Therefore the callback returns the new file info for the caller's
 370  * convenience. The GnomeVFSFileInfoOptions passed here are those used
 371  * for the returned file info; they are not used when setting.
 372  */
 373 void           gnome_vfs_async_set_file_info          (GnomeVFSAsyncHandle                  **handle_return,
 374                                                        GnomeVFSURI                           *uri,
 375                                                        GnomeVFSFileInfo                      *info,
 376                                                        GnomeVFSSetFileInfoMask                mask,
 377                                                        GnomeVFSFileInfoOptions                options,
 378                                                        int                                    priority,
 379                                                        GnomeVFSAsyncSetFileInfoCallback       callback,
 380                                                        gpointer                               callback_data);
 381 void           gnome_vfs_async_load_directory         (GnomeVFSAsyncHandle                  **handle_return,
 382                                                        const gchar                           *text_uri,
 383                                                        GnomeVFSFileInfoOptions                options,
 384                                                        guint                                  items_per_notification,
 385                                                        int                                    priority,
 386                                                        GnomeVFSAsyncDirectoryLoadCallback     callback,
 387                                                        gpointer                               callback_data);
 388 void           gnome_vfs_async_load_directory_uri     (GnomeVFSAsyncHandle                  **handle_return,
 389                                                        GnomeVFSURI                           *uri,
 390                                                        GnomeVFSFileInfoOptions                options,
 391                                                        guint                                  items_per_notification,
 392                                                        int                                    priority,
 393                                                        GnomeVFSAsyncDirectoryLoadCallback     callback,
 394                                                        gpointer                               callback_data);
 395 GnomeVFSResult gnome_vfs_async_xfer                   (GnomeVFSAsyncHandle                  **handle_return,
 396                                                        GList                                 *source_uri_list,
 397                                                        GList                                 *target_uri_list,
 398                                                        GnomeVFSXferOptions                    xfer_options,
 399                                                        GnomeVFSXferErrorMode                  error_mode,
 400                                                        GnomeVFSXferOverwriteMode              overwrite_mode,
 401                                                        int                                    priority,
 402                                                        GnomeVFSAsyncXferProgressCallback      progress_update_callback,
 403                                                        gpointer                               update_callback_data,
 404                                                        GnomeVFSXferProgressCallback           progress_sync_callback,
 405                                                        gpointer                               sync_callback_data);
 406 void           gnome_vfs_async_find_directory         (GnomeVFSAsyncHandle                  **handle_return,
 407                                                        GList                                 *near_uri_list,
 408                                                        GnomeVFSFindDirectoryKind              kind,
 409                                                        gboolean                               create_if_needed,
 410                                                        gboolean                               find_if_needed,
 411                                                        guint                                  permissions,
 412                                                        int                                    priority,
 413                                                        GnomeVFSAsyncFindDirectoryCallback     callback,
 414                                                        gpointer                               user_data);
 415
 416 void           gnome_vfs_async_file_control           (GnomeVFSAsyncHandle                   *handle,
 417                                                        const char                            *operation,
 418                                                        gpointer                               operation_data,
 419                                                        GDestroyNotify                         operation_data_destroy_func,
 420                                                        GnomeVFSAsyncFileControlCallback       callback,
 421                                                        gpointer                               callback_data);
 422
 423 G_END_DECLS
 424
 425 #endif /* GNOME_VFS_ASYNC_OPS_H */