libgnomevfs/gnome-vfs-xfer.h

   1 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
   2
   3 /* gnome-vfs-xfer.h - File transfers in the GNOME Virtual File System.
   4
   5    Copyright (C) 1999 Free Software Foundation
   6
   7    The Gnome Library is free software; you can redistribute it and/or
   8    modify it under the terms of the GNU Library General Public License as
   9    published by the Free Software Foundation; either version 2 of the
  10    License, or (at your option) any later version.
  11
  12    The Gnome Library is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15    Library General Public License for more details.
  16
  17    You should have received a copy of the GNU Library General Public
  18    License along with the Gnome Library; see the file COPYING.LIB.  If not,
  19    write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20    Boston, MA 02111-1307, USA.
  21
  22    Author: Ettore Perazzoli <ettore@comm2000.it> */
  23
  24 #ifndef GNOME_VFS_XFER_H
  25 #define GNOME_VFS_XFER_H
  26
  27 #include <libgnomevfs/gnome-vfs-file-info.h>
  28
  29 G_BEGIN_DECLS
  30
  31 /* Xfer options.
  32  * FIXME bugzilla.eazel.com 1205:
  33  * Split these up into xfer options and xfer actions
  34  */
  35 typedef enum {
  36         GNOME_VFS_XFER_DEFAULT = 0,
  37         GNOME_VFS_XFER_UNUSED_1 = 1 << 0,
  38         GNOME_VFS_XFER_FOLLOW_LINKS = 1 << 1,
  39         GNOME_VFS_XFER_UNUSED_2 = 1 << 2,
  40         GNOME_VFS_XFER_RECURSIVE = 1 << 3,
  41         GNOME_VFS_XFER_SAMEFS = 1 << 4,
  42         GNOME_VFS_XFER_DELETE_ITEMS = 1 << 5,
  43         GNOME_VFS_XFER_EMPTY_DIRECTORIES = 1 << 6,
  44         GNOME_VFS_XFER_NEW_UNIQUE_DIRECTORY = 1 << 7,
  45         GNOME_VFS_XFER_REMOVESOURCE = 1 << 8,
  46         GNOME_VFS_XFER_USE_UNIQUE_NAMES = 1 << 9,
  47         GNOME_VFS_XFER_LINK_ITEMS = 1 << 10,
  48         GNOME_VFS_XFER_FOLLOW_LINKS_RECURSIVE = 1 << 11
  49 } GnomeVFSXferOptions;
  50
  51 /* Progress status, to be reported to the caller of the transfer operation.  */
  52 typedef enum {
  53         GNOME_VFS_XFER_PROGRESS_STATUS_OK = 0,
  54         GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR = 1,
  55         GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE = 2,
  56         /* during the duplicate status the progress callback is asked to
  57            supply a new unique name */
  58         GNOME_VFS_XFER_PROGRESS_STATUS_DUPLICATE = 3
  59 } GnomeVFSXferProgressStatus;
  60
  61 /* The different ways to deal with overwriting during a transfer operation.  */
  62 typedef enum {
  63         /* Interrupt transferring with an error (GNOME_VFS_ERROR_FILEEXISTS).  */
  64         GNOME_VFS_XFER_OVERWRITE_MODE_ABORT = 0,
  65         /* Invoke the progress callback with a
  66            `GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE' status code. */
  67         GNOME_VFS_XFER_OVERWRITE_MODE_QUERY = 1,
  68         /* Overwrite files silently.  */
  69         GNOME_VFS_XFER_OVERWRITE_MODE_REPLACE = 2,
  70         /* Ignore files silently.  */
  71         GNOME_VFS_XFER_OVERWRITE_MODE_SKIP = 3
  72 } GnomeVFSXferOverwriteMode;
  73
  74 /**
  75  * GnomeVFSXferOverwriteAction:
  76  * @GNOME_VFS_XFER_OVERWRITE_ACTION_ABORT: abort the transfer
  77  * @GNOME_VFS_XFER_OVERWRITE_ACTION_REPLACE: replace the existing file
  78  * @GNOME_VFS_XFER_OVERWRITE_ACTION_REPLACE_ALL: replace the existing file, and all future files
  79  * without prompting the callback.
  80  * @GNOME_VFS_XFER_OVERWRITE_ACTION_SKIP: don't copy over the existing file
  81  * @GNOME_VFS_XFER_OVERWRITE_ACTION_SKIP_ALL: don't copy over the existing file, and all future
  82  * files without prompting the callback.
  83  *
  84  * This defines the actions to perform before a file is being overwritten
  85  * (i.e., these are the answers that can be given to a replace query).
  86  **/
  87 typedef enum {
  88         GNOME_VFS_XFER_OVERWRITE_ACTION_ABORT = 0,
  89         GNOME_VFS_XFER_OVERWRITE_ACTION_REPLACE = 1,
  90         GNOME_VFS_XFER_OVERWRITE_ACTION_REPLACE_ALL = 2,
  91         GNOME_VFS_XFER_OVERWRITE_ACTION_SKIP = 3,
  92         GNOME_VFS_XFER_OVERWRITE_ACTION_SKIP_ALL = 4
  93 } GnomeVFSXferOverwriteAction;
  94
  95 typedef enum {
  96         /* Interrupt transferring with an error (code returned is code of the
  97            operation that has caused the error).  */
  98         GNOME_VFS_XFER_ERROR_MODE_ABORT = 0,
  99         /* Invoke the progress callback with a
 100            `GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR' status code. */
 101         GNOME_VFS_XFER_ERROR_MODE_QUERY = 1
 102 } GnomeVFSXferErrorMode;
 103
 104 /* This defines the possible actions to be performed after an error has
 105    occurred.  */
 106 typedef enum {
 107         /* Interrupt operation and return `GNOME_VFS_ERROR_INTERRUPTED'.  */
 108         GNOME_VFS_XFER_ERROR_ACTION_ABORT = 0,
 109         /* Try the same operation again.  */
 110         GNOME_VFS_XFER_ERROR_ACTION_RETRY = 1,
 111         /* Skip this file and continue normally.  */
 112         GNOME_VFS_XFER_ERROR_ACTION_SKIP = 2
 113 } GnomeVFSXferErrorAction;
 114
 115 /* This specifies the current phase in the transfer operation.  Phases whose
 116    comments are marked with `(*)' are always reported in "normal" (i.e. no
 117    error) condition; the other ones are only reported if an error happens in
 118    that specific phase.  */
 119 typedef enum {
 120         /* Initial phase */
 121         GNOME_VFS_XFER_PHASE_INITIAL,
 122         /* Checking if destination can handle move/copy */
 123         GNOME_VFS_XFER_CHECKING_DESTINATION,
 124         /* Collecting file list */
 125         GNOME_VFS_XFER_PHASE_COLLECTING,
 126         /* File list collected (*) */
 127         GNOME_VFS_XFER_PHASE_READYTOGO,
 128         /* Opening source file for reading */
 129         GNOME_VFS_XFER_PHASE_OPENSOURCE,
 130         /* Creating target file for copy */
 131         GNOME_VFS_XFER_PHASE_OPENTARGET,
 132         /* Copying data from source to target (*) */
 133         GNOME_VFS_XFER_PHASE_COPYING,
 134         /* Moving file from source to target (*) */
 135         GNOME_VFS_XFER_PHASE_MOVING,
 136         /* Reading data from source file */
 137         GNOME_VFS_XFER_PHASE_READSOURCE,
 138         /* Writing data to target file */
 139         GNOME_VFS_XFER_PHASE_WRITETARGET,
 140         /* Closing source file */
 141         GNOME_VFS_XFER_PHASE_CLOSESOURCE,
 142         /* Closing target file */
 143         GNOME_VFS_XFER_PHASE_CLOSETARGET,
 144         /* Deleting source file */
 145         GNOME_VFS_XFER_PHASE_DELETESOURCE,
 146         /* Setting attributes on target file */
 147         GNOME_VFS_XFER_PHASE_SETATTRIBUTES,
 148         /* Go to the next file (*) */
 149         GNOME_VFS_XFER_PHASE_FILECOMPLETED,
 150         /* cleaning up after a move (removing source files, etc.) */
 151         GNOME_VFS_XFER_PHASE_CLEANUP,
 152         /* Operation finished (*) */
 153         GNOME_VFS_XFER_PHASE_COMPLETED,
 154         GNOME_VFS_XFER_NUM_PHASES
 155 } GnomeVFSXferPhase;
 156
 157 /* Progress information for the transfer operation.  This is especially useful
 158    for interactive programs.  */
 159 typedef struct {
 160         /* Progress status (see above for a description).  */
 161         GnomeVFSXferProgressStatus status;
 162
 163         /* VFS status code.  If `status' is
 164            `GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR', you should look at this
 165            member to know what has happened.  */
 166         GnomeVFSResult vfs_status;
 167
 168         /* Current phase in the transferring process.  */
 169         GnomeVFSXferPhase phase;
 170
 171         /* Source URI. FIXME bugzilla.eazel.com 1206: change name? */
 172         gchar *source_name;
 173
 174         /* Destination URI. FIXME bugzilla.eazel.com 1206: change name? */
 175         gchar *target_name;
 176
 177         /* Index of file being copied. */
 178         gulong file_index;
 179
 180         /* Total number of files to be copied.  */
 181         gulong files_total;
 182
 183         /* Total number of bytes to be copied.  */
 184         GnomeVFSFileSize bytes_total;
 185
 186         /* Total size of this file (in bytes).  */
 187         GnomeVFSFileSize file_size;
 188
 189         /* Bytes copied for this file so far.  */
 190         GnomeVFSFileSize bytes_copied;
 191
 192         /* Total amount of data copied from the beginning.  */
 193         GnomeVFSFileSize total_bytes_copied;
 194
 195         /* Target unique name used when duplicating, etc. to avoid collisions */
 196         gchar *duplicate_name;
 197
 198         /* Count used in the unique name e.g. (copy 2), etc. */
 199         int duplicate_count;
 200
 201         gboolean top_level_item;
 202         /* indicates that the copied/moved/deleted item is an actual item
 203          * passed in the uri list rather than one encountered by recursively
 204          * traversing directories. Used by metadata copying.
 205          */
 206
 207         /* Reserved for future expansions to GnomeVFSXferProgressInfo
 208          * without having to break ABI compatibility */
 209         void *reserved1;
 210         void *reserved2;
 211
 212 } GnomeVFSXferProgressInfo;
 213
 214 /* This is the prototype for functions called during a transfer operation to
 215    report progress.  If the return value is `FALSE' (0), the operation is
 216    interrupted immediately: the transfer function returns with the value of
 217    `vfs_status' if it is different from `GNOME_VFS_OK', or with
 218    `GNOME_VFS_ERROR_INTERRUPTED' otherwise.  The effect of other values depend
 219    on the value of `info->status':
 220
 221    - If the status is `GNOME_VFS_XFER_PROGRESS_STATUS_OK', the transfer
 222      operation is resumed normally.
 223
 224    - If the status is `GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR', the return
 225      value is interpreted as a `GnomeVFSXferErrorAction' and operation is
 226      interrupted, continued or retried accordingly.
 227
 228    - If the status is `GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE', the return
 229      value is interpreted as a `GnomeVFSXferOverwriteAction'.  */
 230
 231 typedef gint (* GnomeVFSXferProgressCallback)   (GnomeVFSXferProgressInfo *info,
 232                                                  gpointer data);
 233
 234 typedef struct GnomeVFSProgressCallbackState {
 235
 236         /* xfer state */
 237         GnomeVFSXferProgressInfo *progress_info;
 238
 239         /* Callback called for every xfer operation. For async calls called
 240            in async xfer context. */
 241         GnomeVFSXferProgressCallback sync_callback;
 242
 243         /* Callback called periodically every few hundred miliseconds
 244            and whenever user interaction is needed. For async calls
 245            called in the context of the async call caller. */
 246         GnomeVFSXferProgressCallback update_callback;
 247
 248         /* User data passed to sync_callback. */
 249         gpointer user_data;
 250
 251         /* Async job state passed to the update callback. */
 252         gpointer async_job_data;
 253
 254         /* When will update_callback be called next. */
 255         gint64 next_update_callback_time;
 256
 257         /* When will update_callback be called next. */
 258         gint64 next_text_update_callback_time;
 259
 260         /* Period at which the update_callback will be called. */
 261         gint64 update_callback_period;
 262
 263
 264         /* Reserved for future expansions to GnomeVFSProgressCallbackState
 265          * without having to break ABI compatibility */
 266         void *reserved1;
 267         void *reserved2;
 268
 269 } GnomeVFSProgressCallbackState;
 270
 271 GnomeVFSResult gnome_vfs_xfer_uri_list    (const GList                  *source_uri_list,
 272                                            const GList                  *target_uri_list,
 273                                            GnomeVFSXferOptions           xfer_options,
 274                                            GnomeVFSXferErrorMode         error_mode,
 275                                            GnomeVFSXferOverwriteMode     overwrite_mode,
 276                                            GnomeVFSXferProgressCallback  progress_callback,
 277                                            gpointer                      data);
 278 GnomeVFSResult gnome_vfs_xfer_uri         (const GnomeVFSURI            *source_uri,
 279                                            const GnomeVFSURI            *target_uri,
 280                                            GnomeVFSXferOptions           xfer_options,
 281                                            GnomeVFSXferErrorMode         error_mode,
 282                                            GnomeVFSXferOverwriteMode     overwrite_mode,
 283                                            GnomeVFSXferProgressCallback  progress_callback,
 284                                            gpointer                      data);
 285 GnomeVFSResult gnome_vfs_xfer_delete_list (const GList                  *source_uri_list,
 286                                            GnomeVFSXferErrorMode         error_mode,
 287                                            GnomeVFSXferOptions           xfer_options,
 288                                            GnomeVFSXferProgressCallback  progress_callback,
 289                                            gpointer                      data);
 290
 291 G_END_DECLS
 292
 293 #endif /* GNOME_VFS_XFER_H */