somehow the documentation regarding the Xfer operations didn't get in yesterday, this is a patch to fix this and some warnings during the building of the documentation. -- Diego González <diego pemas net>
Index: gnome-vfs/libgnomevfs/gnome-vfs-xfer.h
===================================================================
RCS file: /cvs/gnome/gnome-vfs/libgnomevfs/gnome-vfs-xfer.h,v
retrieving revision 1.12
diff -u -r1.12 gnome-vfs-xfer.h
--- gnome-vfs/libgnomevfs/gnome-vfs-xfer.h 29 Oct 2002 10:37:22 -0000 1.12
+++ gnome-vfs/libgnomevfs/gnome-vfs-xfer.h 19 Dec 2002 15:41:36 -0000
@@ -32,6 +32,35 @@
* FIXME bugzilla.eazel.com 1205:
* Split these up into xfer options and xfer actions
*/
+
+/**
+ * GnomeVFSXferOptions:
+ * @GNOME_VFS_XFER_DEFAULT: Default behavior. Which is to do a straight one
+ * to one copy.
+ * @GNOME_VFS_XFER_UNUSED_1:
+ * @GNOME_VFS_XFER_FOLLOW_LINKS: This means follow the value of the symbolic
+ * link when copying. (ie treat a symbolic link as a directory)
+ * @GNOME_VFS_XFER_UNUSED_2:
+ * @GNOME_VFS_XFER_RECURSIVE: Do a recursive copy of the source to the
+ * destination. Equivalent to the cp -r option in GNU cp.
+ * @GNOME_VFS_XFER_SAMEFS: Allow copying onto the same filesystem.
+ * @GNOME_VFS_XFER_DELETE_ITEMS: Equivalent to a mv.Where you will copy
+ * the contents of the source to the destination and then remove data from
+ * the source URI.
+ * @GNOME_VFS_XFER_EMPTY_DIRECTORIES:
+ * @GNOME_VFS_XFER_NEW_UNIQUE_DIRECTORY: Cill create a directory if it doesn't
+ * exist in the destination area. Useful with the GNOME_VFS_XFER_RECURSIVE xfer
+ * option.
+ * @GNOME_VFS_XFER_REMOVESOURCE: Remove the source data after whatever xfer
+ * option has been taken.
+ * @GNOME_VFS_XFER_USE_UNIQUE_NAMES: Check to make sure that what you copy onto
+ * the destination is not overwritten. It will only copy the unique items from
+ * the source to the destination.
+ * @GNOME_VFS_XFER_LINK_ITEMS:
+ * @GNOME_VFS_XFER_FOLLOW_LINKS_RECURSIVE:
+ *
+ * Describes the set of options that a transfer can deal with.
+ **/
typedef enum {
GNOME_VFS_XFER_DEFAULT = 0,
GNOME_VFS_XFER_UNUSED_1 = 1 << 0,
@@ -45,29 +74,42 @@
GNOME_VFS_XFER_REMOVESOURCE = 1 << 8,
GNOME_VFS_XFER_USE_UNIQUE_NAMES = 1 << 9,
GNOME_VFS_XFER_LINK_ITEMS = 1 << 10,
- GNOME_VFS_XFER_FOLLOW_LINKS_RECURSIVE = 1 << 11,
+ GNOME_VFS_XFER_FOLLOW_LINKS_RECURSIVE = 1 << 11
} GnomeVFSXferOptions;
-/* Progress status, to be reported to the caller of the transfer operation. */
+/**
+ * GnomeVFSXferProgressStatus:
+ * @GNOME_VFS_XFER_PROGRESS_STATUS_OK:
+ * @GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR:
+ * @GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE:
+ * @GNOME_VFS_XFER_PROGRESS_STATUS_DUPLICATE: During the duplicate status the
+ * progress callback is asked to supply a new unique name.
+ *
+ * Progress status, to be reported to the caller of the transfer operation.
+ **/
typedef enum {
GNOME_VFS_XFER_PROGRESS_STATUS_OK = 0,
GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR = 1,
GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE = 2,
- /* during the duplicate status the progress callback is asked to
- supply a new unique name */
GNOME_VFS_XFER_PROGRESS_STATUS_DUPLICATE = 3
} GnomeVFSXferProgressStatus;
-/* The different ways to deal with overwriting during a transfer operation. */
+/**
+ * GnomeVFSXferOverwriteMode:
+ * @GNOME_VFS_XFER_OVERWRITE_MODE_ABORT: Aborts the transfer with and error
+ * (GNOME_VFS_ERROR_FILEEXISTS).
+ * @GNOME_VFS_XFER_OVERWRITE_MODE_QUERY: Invoke the progress callback with
+ * a GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE status code.
+ * @GNOME_VFS_XFER_OVERWRITE_MODE_REPLACE: Replace the files silently.
+ * @GNOME_VFS_XFER_OVERWRITE_MODE_SKIP: Skip duplicate files silenty.
+ *
+ * The different ways to deal with overwriting during a transfer operation.
+**/
+
typedef enum {
- /* Interrupt transferring with an error (GNOME_VFS_ERROR_FILEEXISTS). */
GNOME_VFS_XFER_OVERWRITE_MODE_ABORT = 0,
- /* Invoke the progress callback with a
- `GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE' status code. */
GNOME_VFS_XFER_OVERWRITE_MODE_QUERY = 1,
- /* Overwrite files silently. */
GNOME_VFS_XFER_OVERWRITE_MODE_REPLACE = 2,
- /* Ignore files silently. */
GNOME_VFS_XFER_OVERWRITE_MODE_SKIP = 3
} GnomeVFSXferOverwriteMode;
@@ -89,26 +131,35 @@
GNOME_VFS_XFER_OVERWRITE_ACTION_REPLACE = 1,
GNOME_VFS_XFER_OVERWRITE_ACTION_REPLACE_ALL = 2,
GNOME_VFS_XFER_OVERWRITE_ACTION_SKIP = 3,
- GNOME_VFS_XFER_OVERWRITE_ACTION_SKIP_ALL = 4,
+ GNOME_VFS_XFER_OVERWRITE_ACTION_SKIP_ALL = 4
} GnomeVFSXferOverwriteAction;
+/**
+ * GnomeVFSXferErrorMode:
+ * @GNOME_VFS_XFER_ERROR_MODE_ABORT: The operation will be aborted whenever the
+ * transfer is interrupted. The error code returned is the code of the operation
+ * that caused the error.
+ * @GNOME_VFS_XFER_ERROR_MODE_QUERY: No error occured. Invoke the progress
+ * callback with a #GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR status code.
+ *
+ **/
typedef enum {
- /* Interrupt transferring with an error (code returned is code of the
- operation that has caused the error). */
GNOME_VFS_XFER_ERROR_MODE_ABORT = 0,
- /* Invoke the progress callback with a
- `GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR' status code. */
- GNOME_VFS_XFER_ERROR_MODE_QUERY = 1,
+ GNOME_VFS_XFER_ERROR_MODE_QUERY = 1
} GnomeVFSXferErrorMode;
-/* This defines the possible actions to be performed after an error has
- occurred. */
+/**
+ * GnomeVFSXferErrorAction:
+ * @GNOME_VFS_XFER_ERROR_ACTION_ABORT: Interrupt operation and return
+ * #GNOME_VFS_ERROR_INTERRUPTED.
+ * @GNOME_VFS_XFER_ERROR_ACTION_RETRY: Try the same operation again.
+ * @GNOME_VFS_XFER_ERROR_ACTION_SKIP: Skip this file and continue normally.
+ *
+ * Defines the possible actions to be performed after an error has occurred.
+ **/
typedef enum {
- /* Interrupt operation and return `GNOME_VFS_ERROR_INTERRUPTED'. */
GNOME_VFS_XFER_ERROR_ACTION_ABORT = 0,
- /* Try the same operation again. */
GNOME_VFS_XFER_ERROR_ACTION_RETRY = 1,
- /* Skip this file and continue normally. */
GNOME_VFS_XFER_ERROR_ACTION_SKIP = 2
} GnomeVFSXferErrorAction;
@@ -116,46 +167,60 @@
comments are marked with `(*)' are always reported in "normal" (i.e. no
error) condition; the other ones are only reported if an error happens in
that specific phase. */
+
+/**
+ * GnomeVFSXferPhase:
+ * @GNOME_VFS_XFER_PHASE_INITIAL: Initial phase.
+ * @GNOME_VFS_XFER_CHECKING_DESTINATION: Checking if destination can handle move/copy.
+ * @GNOME_VFS_XFER_PHASE_COLLECTING: Collecting file list.
+ * @GNOME_VFS_XFER_PHASE_READYTOGO: File list collected (*).
+ * @GNOME_VFS_XFER_PHASE_OPENSOURCE: Opening source file for reading.
+ * @GNOME_VFS_XFER_PHASE_OPENTARGET: Creating target file for copy.
+ * @GNOME_VFS_XFER_PHASE_COPYING: Copying data from source to target (*).
+ * @GNOME_VFS_XFER_PHASE_MOVING: Moving file from source to target (*).
+ * @GNOME_VFS_XFER_PHASE_READSOURCE: Reading data from source file.
+ * @GNOME_VFS_XFER_PHASE_WRITETARGET: Writing data to target file.
+ * @GNOME_VFS_XFER_PHASE_CLOSESOURCE: Closing source file.
+ * @GNOME_VFS_XFER_PHASE_CLOSETARGET: Closing target file.
+ * @GNOME_VFS_XFER_PHASE_DELETESOURCE: Deleting source file.
+ * @GNOME_VFS_XFER_PHASE_SETATTRIBUTES: Setting attributes on target file.
+ * @GNOME_VFS_XFER_PHASE_FILECOMPLETED: Go to the next file (*).
+ * @GNOME_VFS_XFER_PHASE_CLEANUP: Cleaning up after a move (removing source files, etc.).
+ * @GNOME_VFS_XFER_PHASE_COMPLETED: Operation finished (*).
+ * @GNOME_VFS_XFER_NUM_PHASES:
+ *
+ * This specifies the current phase in the transfer operation. Phases whose
+ * comment sare marked with (*) are always reported in "normal" (i.e. no error)
+ * condition; theother ones are only reported if an error happens in that
+ * specific phase.
+ **/
typedef enum {
- /* Initial phase */
GNOME_VFS_XFER_PHASE_INITIAL,
- /* Checking if destination can handle move/copy */
GNOME_VFS_XFER_CHECKING_DESTINATION,
- /* Collecting file list */
GNOME_VFS_XFER_PHASE_COLLECTING,
- /* File list collected (*) */
GNOME_VFS_XFER_PHASE_READYTOGO,
- /* Opening source file for reading */
GNOME_VFS_XFER_PHASE_OPENSOURCE,
- /* Creating target file for copy */
GNOME_VFS_XFER_PHASE_OPENTARGET,
- /* Copying data from source to target (*) */
GNOME_VFS_XFER_PHASE_COPYING,
- /* Moving file from source to target (*) */
GNOME_VFS_XFER_PHASE_MOVING,
- /* Reading data from source file */
GNOME_VFS_XFER_PHASE_READSOURCE,
- /* Writing data to target file */
GNOME_VFS_XFER_PHASE_WRITETARGET,
- /* Closing source file */
GNOME_VFS_XFER_PHASE_CLOSESOURCE,
- /* Closing target file */
GNOME_VFS_XFER_PHASE_CLOSETARGET,
- /* Deleting source file */
GNOME_VFS_XFER_PHASE_DELETESOURCE,
- /* Setting attributes on target file */
GNOME_VFS_XFER_PHASE_SETATTRIBUTES,
- /* Go to the next file (*) */
GNOME_VFS_XFER_PHASE_FILECOMPLETED,
- /* cleaning up after a move (removing source files, etc.) */
GNOME_VFS_XFER_PHASE_CLEANUP,
- /* Operation finished (*) */
GNOME_VFS_XFER_PHASE_COMPLETED,
GNOME_VFS_XFER_NUM_PHASES
} GnomeVFSXferPhase;
-/* Progress information for the transfer operation. This is especially useful
- for interactive programs. */
+/**
+ * GnomeVFSXferProgressInfo:
+ *
+ * The GnomeVFSXferProgressInfo structure contains information about the state
+ * of the transfer in progress. This is specially useful for interative programs.
+ **/
typedef struct {
/* Progress status (see above for a description). */
GnomeVFSXferProgressStatus status;
@@ -211,22 +276,28 @@
} GnomeVFSXferProgressInfo;
-/* This is the prototype for functions called during a transfer operation to
- report progress. If the return value is `FALSE' (0), the operation is
- interrupted immediately: the transfer function returns with the value of
- `vfs_status' if it is different from `GNOME_VFS_OK', or with
- `GNOME_VFS_ERROR_INTERRUPTED' otherwise. The effect of other values depend
- on the value of `info->status':
-
- - If the status is `GNOME_VFS_XFER_PROGRESS_STATUS_OK', the transfer
- operation is resumed normally.
-
- - If the status is `GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR', the return
- value is interpreted as a `GnomeVFSXferErrorAction' and operation is
- interrupted, continued or retried accordingly.
-
- - If the status is `GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE', the return
- value is interpreted as a `GnomeVFSXferOverwriteAction'. */
+/**
+ * GnomeVFSXferProgressCallback:
+ * @info: Information about the transfer in progress
+ * @data:
+ *
+ * This is the prototype for functions called during a transfer operation to
+ * report progress. Whenever this callback is called the value in info->status
+ * must be checked, it is here where the status of the transfer is passed and
+ * the effect of other values contained in @info depends on it.
+ *
+ * - If the status is #GNOME_VFS_XFER_PROGRESS_STATUS_OK, the transfer
+ * operation is resumed normally.
+ *
+ * - If the status is #GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR, the return
+ * value is interpreted as a `GnomeVFSXferErrorAction' and operation is
+ * interrupted, continued or retried accordingly.
+ *
+ * - If the status is #GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE, the return
+ * value is interpreted as a `GnomeVFSXferOverwriteAction'.
+ *
+ * Return Value: FALSE if the operation is interrupted inmediately, TRUE otherwise.
+ **/
typedef gint (* GnomeVFSXferProgressCallback) (GnomeVFSXferProgressInfo *info,
gpointer data);
Attachment:
signature.asc
Description: This is a digitally signed message part