enum GnomeVFSXferOptions

typedef enum {
	GNOME_VFS_XFER_DEFAULT = 0,
	GNOME_VFS_XFER_UNUSED_1 = 1 << 0,
	GNOME_VFS_XFER_FOLLOW_LINKS = 1 << 1,
	GNOME_VFS_XFER_UNUSED_2 = 1 << 2,
	GNOME_VFS_XFER_RECURSIVE = 1 << 3,
	GNOME_VFS_XFER_SAMEFS = 1 << 4,
	GNOME_VFS_XFER_DELETE_ITEMS = 1 << 5,
	GNOME_VFS_XFER_EMPTY_DIRECTORIES = 1 << 6,
	GNOME_VFS_XFER_NEW_UNIQUE_DIRECTORY = 1 << 7,
	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_TARGET_DEFAULT_PERMS = 1 << 12
} GnomeVFSXferOptions;

These options control the way gnome_vfs_xfer_uri(), gnome_vfs_xfer_uri_list(), gnome_vfs_xfer_delete_list() and gnome_vfs_async_xfer() work.

At a first glance the GnomeVFSXferOptions semantics are not very intuitive.

There are two types of GnomeVFSXferOptions: Those that define an operation, i.e. describe what to do, and those that influence how to execute the operation.

enum GnomeVFSXferProgressStatus

typedef enum {
	GNOME_VFS_XFER_PROGRESS_STATUS_OK = 0,
	GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR = 1,
	GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE = 2,
	GNOME_VFS_XFER_PROGRESS_STATUS_DUPLICATE = 3
} GnomeVFSXferProgressStatus;

The difference between GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE and GNOME_VFS_XFER_PROGRESS_STATUS_DUPLICATE is that they will be issued at different occassions, and that the return value will be interpreted differently. For details, see GnomeVFSXferProgressCallback.

enum GnomeVFSXferOverwriteMode

typedef enum {
	GNOME_VFS_XFER_OVERWRITE_MODE_ABORT = 0,
	GNOME_VFS_XFER_OVERWRITE_MODE_QUERY = 1,
	GNOME_VFS_XFER_OVERWRITE_MODE_REPLACE = 2,
	GNOME_VFS_XFER_OVERWRITE_MODE_SKIP = 3
} GnomeVFSXferOverwriteMode;

This is passed to gnome_vfs_xfer_uri(), gnome_vfs_xfer_uri_list(), gnome_vfs_xfer_delete_list() and gnome_vfs_async_xfer() and specifies what action should be taken when a target file already exists.

enum GnomeVFSXferOverwriteAction

typedef enum {
	GNOME_VFS_XFER_OVERWRITE_ACTION_ABORT = 0,
	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
} GnomeVFSXferOverwriteAction;

This defines the actions to perform before a file is being overwritten (i.e., these are the answers that can be given to a replace query).

enum GnomeVFSXferErrorMode

typedef enum {
	GNOME_VFS_XFER_ERROR_MODE_ABORT = 0,
	GNOME_VFS_XFER_ERROR_MODE_QUERY = 1
} GnomeVFSXferErrorMode;

This is passed to gnome_vfs_xfer_uri(), gnome_vfs_xfer_uri_list(), gnome_vfs_xfer_delete_list() and gnome_vfs_async_xfer() and specifies what action should be taken when transfer errors are detected.

The progress callback is either a GnomeVFSXferProgressCallback for synchronous Xfer operations, or a GnomeVFSAsyncXferProgressCallback for asynchronous operations.

enum GnomeVFSXferErrorAction

typedef enum {
	GNOME_VFS_XFER_ERROR_ACTION_ABORT = 0,
	GNOME_VFS_XFER_ERROR_ACTION_RETRY = 1,
	GNOME_VFS_XFER_ERROR_ACTION_SKIP = 2
} GnomeVFSXferErrorAction;

This defines the possible actions to be performed after a VFS error has occurred, i.e. when a GnomeVFS file operation issued during the transfer returned a result that is not equal to GNOME_VFS_OK.

It is returned by the progress callback which is either a GnomeVFSXferProgressCallback for synchronous Xfer operations, or a GnomeVFSAsyncXferProgressCallback for asynchronous operations.

enum GnomeVFSXferPhase

typedef enum {
	GNOME_VFS_XFER_PHASE_INITIAL,
	GNOME_VFS_XFER_CHECKING_DESTINATION,
	GNOME_VFS_XFER_PHASE_COLLECTING,
	GNOME_VFS_XFER_PHASE_READYTOGO,
	GNOME_VFS_XFER_PHASE_OPENSOURCE,
	GNOME_VFS_XFER_PHASE_OPENTARGET,
	GNOME_VFS_XFER_PHASE_COPYING,
	GNOME_VFS_XFER_PHASE_MOVING,
	GNOME_VFS_XFER_PHASE_READSOURCE,
	GNOME_VFS_XFER_PHASE_WRITETARGET,
	GNOME_VFS_XFER_PHASE_CLOSESOURCE,
	GNOME_VFS_XFER_PHASE_CLOSETARGET,
	GNOME_VFS_XFER_PHASE_DELETESOURCE,
	GNOME_VFS_XFER_PHASE_SETATTRIBUTES,
	GNOME_VFS_XFER_PHASE_FILECOMPLETED,
	GNOME_VFS_XFER_PHASE_CLEANUP,
	GNOME_VFS_XFER_PHASE_COMPLETED,
	GNOME_VFS_XFER_NUM_PHASES
} GnomeVFSXferPhase;

Specifies the current phase of an Xfer operation that was initiated using gnome_vfs_xfer_uri(), gnome_vfs_xfer_uri_list(), gnome_vfs_xfer_delete_list() or gnome_vfs_async_xfer().

Whenever the Xfer phase is in a phase that is highlighted with a (*), the GnomeVFSXferProgressCallback respectively GnomeVFSAsyncXferProgressCallback is never invoked with a GnomeVFSXferProgressStatus other than GNOME_VFS_XFER_PROGRESS_STATUS_OK.

GnomeVFSXferProgressInfo

typedef struct {
	GnomeVFSXferProgressStatus status;

	GnomeVFSResult vfs_status;

	GnomeVFSXferPhase phase;

	/* Source URI. FIXME bugzilla.eazel.com 1206: change name? */
	gchar *source_name;

	/* Destination URI. FIXME bugzilla.eazel.com 1206: change name? */
	gchar *target_name;

	gulong file_index;

	gulong files_total;

	GnomeVFSFileSize bytes_total;

	GnomeVFSFileSize file_size;

	GnomeVFSFileSize bytes_copied;

	GnomeVFSFileSize total_bytes_copied;

	gchar *duplicate_name;

	int duplicate_count;

	gboolean top_level_item;

	/* Reserved for future expansions to GnomeVFSXferProgressInfo
	 * without having to break ABI compatibility */
} GnomeVFSXferProgressInfo;

Provides progress information for the transfer operation. This is especially useful for interactive programs.

GnomeVFSXferProgressCallback ()

gint                (*GnomeVFSXferProgressCallback)     (GnomeVFSXferProgressInfo *info,
                                                         gpointer user_data);

This is the prototype for functions called during a transfer operation to report progress.

The interpretation of the return value of the callback depends on the GnomeVFSXferProgressStaus status field of GnomeVFSXferProgressInfo, some status/return value combinations require modification of particular info fields.

gnome_vfs_xfer_uri_list ()

GnomeVFSResult      gnome_vfs_xfer_uri_list             (const GList *source_uri_list,
                                                         const GList *target_uri_list,
                                                         GnomeVFSXferOptions xfer_options,
                                                         GnomeVFSXferErrorMode error_mode,
                                                         GnomeVFSXferOverwriteMode overwrite_mode,
                                                         GnomeVFSXferProgressCallback progress_callback,
                                                         gpointer data);

This function will transfer multiple files to multiple targets, given source URIs and destination URIs. If you want to do asynchronous file transfers, you have to use gnome_vfs_async_xfer() instead.

gnome_vfs_xfer_uri ()

GnomeVFSResult      gnome_vfs_xfer_uri                  (const GnomeVFSURI *source_uri,
                                                         const GnomeVFSURI *target_uri,
                                                         GnomeVFSXferOptions xfer_options,
                                                         GnomeVFSXferErrorMode error_mode,
                                                         GnomeVFSXferOverwriteMode overwrite_mode,
                                                         GnomeVFSXferProgressCallback progress_callback,
                                                         gpointer data);

This function works exactly like gnome_vfs_xfer_uri_list(), and is a convenience wrapper for only acting on one source/target URI pair.

gnome_vfs_xfer_delete_list ()

GnomeVFSResult      gnome_vfs_xfer_delete_list          (const GList *source_uri_list,
                                                         GnomeVFSXferErrorMode error_mode,
                                                         GnomeVFSXferOptions xfer_options,
                                                         GnomeVFSXferProgressCallback progress_callback,
                                                         gpointer data);

Unlinks items in the source_uri_list from their filesystems.