File Transfers: GnomeVFS - Filesystem Abstraction library

File Transfers

File Transfers — Conveniently copy/move/delete files en masse

Functions

gint	(*GnomeVFSXferProgressCallback) ()
GnomeVFSResult	gnome_vfs_xfer_uri_list ()
GnomeVFSResult	gnome_vfs_xfer_uri ()
GnomeVFSResult	gnome_vfs_xfer_delete_list ()

Types and Values

enum	GnomeVFSXferOptions
enum	GnomeVFSXferProgressStatus
enum	GnomeVFSXferOverwriteMode
enum	GnomeVFSXferOverwriteAction
enum	GnomeVFSXferErrorMode
enum	GnomeVFSXferErrorAction
enum	GnomeVFSXferPhase
	GnomeVFSXferProgressInfo

Description

Functions

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.

Table 1. Status/Return Value Overview

GnomeVFSXferProgressStatus status	Status	Only If	Return Value Interpretation
GNOME_VFS_XFER_PROGRESS_STATUS_OK	OK		`0`: abort, otherwise continue
GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR	VFS Error Ocurred	GnomeVFSXferErrorMode is GNOME_VFS_XFER_ERROR_MODE_QUERY	GnomeVFSXferErrorAction
GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE	Conflict Ocurred, Overwrite?	GnomeVFSXferOverwriteMode is GNOME_VFS_XFER_OVERWRITE_MODE_QUERY, GnomeVFSXferOptions does not have GNOME_VFS_XFER_USE_UNIQUE_NAMES.	GnomeVFSXferOverwriteAction
GNOME_VFS_XFER_PROGRESS_STATUS_DUPLICATE	Conflict Ocurred, New Target Name?	GnomeVFSXferOptions does have GNOME_VFS_XFER_USE_UNIQUE_NAMES.	`0`: abort, otherwise retry with new `duplicate_name` in `info` (free the old one!).

Each GnomeVFSXferProgressStatus provides one value signalling abortion that maps to 0. Therefore, returning 0 will always abort the Xfer. On abortion, if the info's vfs_status is GNOME_VFS_OK, the Xfer operation result will be set to GNOME_VFS_ERROR_INTERRUPTED, otherwise the operation result will be set to vfs_status to distinguish completely user-driven aborts from those involving a problem during the Xfer.

Parameters

info	The GnomeVFSXferProgressInfo associated with this transfer operation.
user_data	The user data passed to `gnome_vfs_xfer_uri()`, `gnome_vfs_xfer_uri_list()`, `gnome_vfs_xfer_delete_list()` or `gnome_vfs_async_xfer()`.

Returns

Whether the process should be aborted, or whether a special action should be taken.

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.

Parameters

source_uri_list	A GList of source GnomeVFSURIs.
target_uri_list	A GList of target GnomeVFSURIs, each corresponding to one URI in `source_uri_list` .
xfer_options	GnomeVFSXferOptions defining the desired operation and parameters.
error_mode	A GnomeVFSErrorMode specifying how to proceed if a VFS error occurs.
overwrite_mode	A GnomeVFSOverwriteMode specifying how to proceed if a file is being overwritten.
progress_callback	This GnomeVFSProgressCallback is used to inform the user about the progress of a transfer, and to request further input from him if a problem occurs.
data	Data to be passed back in callbacks from the xfer engine.

Returns

If all goes well it returns GNOME_VFS_OK. Check GnomeVFSResult for other values.

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.

Parameters

source_uri	A source GnomeVFSURI.
target_uri	A target GnomeVFSURI.
xfer_options	GnomeVFSXferOptions defining the desired operation and parameters.
error_mode	A GnomeVFSErrorMode specifying how to proceed if a VFS error occurs.
overwrite_mode	A GnomeVFSOverwriteMode specifying how to proceed if a file is being overwritten.
progress_callback	This GnomeVFSProgressCallback is used to inform the user about the progress of a transfer, and to request further input from him if a problem occurs.
data	Data to be passed back in callbacks from the xfer engine.

Returns

an integer representing the result of the operation.

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.

Parameters

source_uri_list	This is a list containing uris.
error_mode	Decide how you want to deal with interruptions.
xfer_options	Set whatever transfer options you need.
progress_callback	Callback to check on progress of transfer.
data	Data to be passed back in callbacks from the xfer engine.

Returns

GNOME_VFS_OK if successful, or the appropriate error code otherwise.

Types and Values

enum 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.

Table 2. Operation Selection

GnomeVFSXferOptions entry	Operation	UNIX equivalent	Comments
GNOME_VFS_XFER_DEFAULT	Copy	`cp`
GNOME_VFS_XFER_REMOVESOURCE	Move	`mv`
GNOME_VFS_XFER_LINK_ITEMS	Link	`ln -s`
GNOME_VFS_XFER_NEW_UNIQUE_DIRECTORY	Make Unique Directory	`mkdir`	implies GNOME_VFS_XFER_USE_UNIQUE_NAMES
GNOME_VFS_XFER_DELETE_ITEMS	Remove	`rm -r`
GNOME_VFS_XFER_EMPTY_DIRECTORIES	Remove Directory Contents	foreach file: `( cd file && rm -rf * )`	used to empty trash

Because GNOME_VFS_XFER_DEFAULT maps to 0, it will always be present. Thus, not explicitly specifying any operation at all, or just specifying GNOME_VFS_XFER_DEFAULT will both execute a copy.

If an operation other than GNOME_VFS_XFER_DEFAULT is specified, it will override the copy operation, but you may only specify one of the other operations at a time.

This unintuitive operation selection unfortunately poses an API weakness and an obstacle in client development, and will be modified in a later revision of this API.

Members

GNOME_VFS_XFER_DEFAULT	Default behavior, which is to do a straight one to one copy.
GNOME_VFS_XFER_UNUSED_1	Unused.
GNOME_VFS_XFER_FOLLOW_LINKS	Follow symbolic links when copying or moving, i.e. the target of symbolic links are copied rather than the symbolic links themselves. Note that this just refers to top-level items. If you also want to follow symbolic links inside directories you operate on, you also have to specify GNOME_VFS_XFER_FOLLOW_LINKS_RECURSIVE.
GNOME_VFS_XFER_UNUSED_2	Unused.
GNOME_VFS_XFER_RECURSIVE	Recursively copy source directories to the target. Equivalent to the cp -r option in GNU cp.
GNOME_VFS_XFER_SAMEFS	When copying recursively, this only picks up items on the same file system the same filesystem as their parent directory.
GNOME_VFS_XFER_DELETE_ITEMS	This is equivalent to an `rmdir()` for source directories, and an `unlink()` operation for all source files. Requires `NULL` target URIs.
GNOME_VFS_XFER_EMPTY_DIRECTORIES	Remove the whole contents of the passed-in source directories. Requires `NULL` target URIs.
GNOME_VFS_XFER_NEW_UNIQUE_DIRECTORY	This will create a directory if it doesn't exist in the destination area (i.e. `mkdir()`).
GNOME_VFS_XFER_REMOVESOURCE	This makes a copy operation equivalent to a mv, i.e. the files will be moved rather than copied. If applicable, this will use `rename()`, otherwise (i.e. across file systems), it will fall back to a copy operation followed by a source file deletion.
GNOME_VFS_XFER_USE_UNIQUE_NAMES	When this option is present, and a name collisions on the target occurs, the progress callback will be asked for a new name, until the newly provided name doesn't conflict or the request callback transfer cancellation.
GNOME_VFS_XFER_LINK_ITEMS	Executes a symlink operation for each of the source/target URI pairs, i.e. similar to GNU ln -s source target. NB: The symlink target has to be specified as source URI, and the symlink itself as target URI.
GNOME_VFS_XFER_FOLLOW_LINKS_RECURSIVE	This means that when doing a copy operation, symbolic links in subdirectories are dereferenced. This is typically used together with GNOME_VFS_XFER_FOLLOW_LINKS_RECURSIVE.
GNOME_VFS_XFER_TARGET_DEFAULT_PERMS	This means that the target file will not have the same permissions as the source file, but will instead have the default permissions of the destination location. This is useful when copying from read-only locations (CDs).

enum 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.

Members

GNOME_VFS_XFER_PROGRESS_STATUS_OK	The file transfer is progressing normally.
GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR	A VFS error was detected.
GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE	The current target file specified by the GnomeVFSXferProgressInfo's `target_name` field already exists.
GNOME_VFS_XFER_PROGRESS_STATUS_DUPLICATE	The current target file specified by the GnomeVFSXferProgressInfo's `target_name` field already exists, and the progress callback is asked to supply a new unique name.

enum 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.

Members

GNOME_VFS_XFER_OVERWRITE_MODE_ABORT	Abort the transfer when a target file already exists, returning the error GNOME_VFS_ERROR_FILEEXISTS.
GNOME_VFS_XFER_OVERWRITE_MODE_QUERY	Query the progress callback with the GnomeVFSXferProgressInfo's status field set to GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR when a target file already exists.
GNOME_VFS_XFER_OVERWRITE_MODE_REPLACE	Replace existing target files silently. Don't worry be happy.
GNOME_VFS_XFER_OVERWRITE_MODE_SKIP	Skip source files when its target already exists.

enum 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).

Members

GNOME_VFS_XFER_OVERWRITE_ACTION_ABORT	abort the transfer
GNOME_VFS_XFER_OVERWRITE_ACTION_REPLACE	replace the existing file
GNOME_VFS_XFER_OVERWRITE_ACTION_REPLACE_ALL	replace the existing file, and all future files without prompting the callback.
GNOME_VFS_XFER_OVERWRITE_ACTION_SKIP	don't copy over the existing file
GNOME_VFS_XFER_OVERWRITE_ACTION_SKIP_ALL	don't copy over the existing file, and all future files without prompting the callback.

enum GnomeVFSXferErrorMode

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

Members

GNOME_VFS_XFER_ERROR_MODE_ABORT	abort the transfer when an error occurs
GNOME_VFS_XFER_ERROR_MODE_QUERY	query the progress callback with the GnomeVFSXferProgressInfo's status field set to GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR.

enum 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.

Members

GNOME_VFS_XFER_ERROR_ACTION_ABORT	interrupt Xfer and return `GNOME_VFS_ERROR_INTERRUPTED`.
GNOME_VFS_XFER_ERROR_ACTION_RETRY	retry the failed operation.
GNOME_VFS_XFER_ERROR_ACTION_SKIP	skip the failed operation, and continue Xfer normally.

enum 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.

Members

GNOME_VFS_XFER_PHASE_INITIAL	initial phase.
GNOME_VFS_XFER_CHECKING_DESTINATION	destination is checked for being able to handle copy/move.
GNOME_VFS_XFER_PHASE_COLLECTING	source file list is collected.
GNOME_VFS_XFER_PHASE_READYTOGO	source file list has been collected (*).
GNOME_VFS_XFER_PHASE_OPENSOURCE	source file is opened for reading.
GNOME_VFS_XFER_PHASE_OPENTARGET	target file, directory or symlink is created, or opened for copying.
GNOME_VFS_XFER_PHASE_COPYING	data is copied from source file to target file (*).
GNOME_VFS_XFER_PHASE_MOVING	source file is moved to target (M).
GNOME_VFS_XFER_PHASE_READSOURCE	data is read from a source file, when copying.
GNOME_VFS_XFER_PHASE_WRITETARGET	data is written to a target file, when copying.
GNOME_VFS_XFER_PHASE_CLOSESOURCE	source file is closed, when copying
GNOME_VFS_XFER_PHASE_CLOSETARGET	target file is closed, when copying.
GNOME_VFS_XFER_PHASE_DELETESOURCE	source file is deleted.
GNOME_VFS_XFER_PHASE_SETATTRIBUTES	target file attributes are set.
GNOME_VFS_XFER_PHASE_FILECOMPLETED	one file was completed, ready for next file.
GNOME_VFS_XFER_PHASE_CLEANUP	cleanup after moving (i.e. source files deletion).
GNOME_VFS_XFER_PHASE_COMPLETED	operation finished (*).
GNOME_VFS_XFER_NUM_PHASES

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.

Members

GnomeVFSXferProgressStatus `status`;	A GnomeVFSXferProgressStatus describing the current status.
GnomeVFSResult `vfs_status`;	A GnomeVFSResult describing the current VFS status.
GnomeVFSXferPhase `phase`;	A GnomeVFSXferPhase describing the current transfer phase.
gchar *`source_name`;	The Currently processed source URI.
gchar *`target_name`;	The Currently processed target URI.
gulong `file_index`;	The index of the currently processed file.
gulong `files_total`;	The total number of processed files.
GnomeVFSFileSize `bytes_total`;	The total size of all files to transfer in bytes.
GnomeVFSFileSize `file_size`;	The size of the currently processed file in bytes.
GnomeVFSFileSize `bytes_copied`;	The number of bytes that has been transferred from the current file.
GnomeVFSFileSize `total_bytes_copied`;	The total number of bytes that has been transferred.
gchar *`duplicate_name`;	The name specifying a duplicate filename. It acts as pointer to both input and output data. It is only valid input data if `status` is GNOME_VFS_XFER_PROGRESS_STATUS_DUPLICATE, in which case `duplicate_count` and `duplicate_name` should be used by the GnomeVFSXferProgressCallback to pick a new unique target name. If the callback wants to retry with a new unique name it is supposed to free the old `duplicate_name` set it to a valid string describing the new file name.
int `duplicate_count`;	The number of conflicts that ocurred when the current `duplicate_name` was set.
gboolean `top_level_item`;	This flag signals that the currently processed file is a top level item. If it is `TRUE`, one of the files passed to `gnome_vfs_xfer_uri()`, `gnome_vfs_xfer_uri_list()`, `gnome_vfs_xfer_delete_list()` or `gnome_vfs_async_xfer()` is currently processed. If it is `FALSE`, a file or directory that is inside a directory specified by the passed in source list is currently processed.