File Transfers

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

Synopsis




enum        GnomeVFSXferOptions;
enum        GnomeVFSXferProgressStatus;
enum        GnomeVFSXferOverwriteMode;
enum        GnomeVFSXferOverwriteAction;
enum        GnomeVFSXferErrorMode;
enum        GnomeVFSXferErrorAction;
enum        GnomeVFSXferPhase;
struct      GnomeVFSXferProgressInfo;
gint        (*GnomeVFSXferProgressCallback) (GnomeVFSXferProgressInfo *info,
                                             gpointer data);
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);
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);
GnomeVFSResult gnome_vfs_xfer_delete_list   (const GList *source_uri_list,
                                             GnomeVFSXferErrorMode error_mode,
                                             GnomeVFSXferOptions xfer_options,
                                             GnomeVFSXferProgressCallback progress_callback,
                                             gpointer data);

Description

Details

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
} GnomeVFSXferOptions;

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,
	/* during the duplicate status the progress callback is asked to
	   supply a new unique name */
	GNOME_VFS_XFER_PROGRESS_STATUS_DUPLICATE = 3
} GnomeVFSXferProgressStatus;

enum GnomeVFSXferOverwriteMode

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;

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

`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

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
} GnomeVFSXferErrorMode;

enum GnomeVFSXferErrorAction

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;

enum GnomeVFSXferPhase

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;

struct GnomeVFSXferProgressInfo

struct GnomeVFSXferProgressInfo {

	/* Progress status (see above for a description).  */
	GnomeVFSXferProgressStatus status;

	/* VFS status code.  If `status' is
           `GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR', you should look at this
           member to know what has happened.  */
	GnomeVFSResult vfs_status;

	/* Current phase in the transferring process.  */
	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;

	/* Index of file being copied. */
	gulong file_index;

	/* Total number of files to be copied.  */
	gulong files_total;

	/* Total number of bytes to be copied.  */
	GnomeVFSFileSize bytes_total;

	/* Total size of this file (in bytes).  */
	GnomeVFSFileSize file_size;

	/* Bytes copied for this file so far.  */
	GnomeVFSFileSize bytes_copied;

	/* Total amount of data copied from the beginning.  */
	GnomeVFSFileSize total_bytes_copied;
	
	/* Target unique name used when duplicating, etc. to avoid collisions */ 
	gchar *duplicate_name;

	/* Count used in the unique name e.g. (copy 2), etc. */
	int duplicate_count;

	gboolean top_level_item;
	/* indicates that the copied/moved/deleted item is an actual item
	 * passed in the uri list rather than one encountered by recursively
	 * traversing directories. Used by metadata copying.
	 */

	/* Reserved for future expansions to GnomeVFSXferProgressInfo
	 * without having to break ABI compatibility */
	void *reserved1;
	void *reserved2;

};

GnomeVFSXferProgressCallback ()

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

`info` :
`data` :
Returns :

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 a multiple targets. Given a a source uri(s) and a destination uri(s). There are a list of options that your application can use to control how the transfer is done.

`source_uri_list` :	A Glist of uris (ie file;//)
`target_uri_list` :	A GList of uris
`xfer_options` :	These are options you wish to set for the transfer. For instance by setting the xfer behavior you can either make a copy or a move.
`error_mode` :	Decide how to behave if the xfer is interrupted. For instance you could set your application to return an error code in case of an interuption.
`overwrite_mode` :	How to react if a file your copying is being overwritten.
`progress_callback` :	This is used to monitor the progress of a transfer. Common use would be to check to see if the transfer is asking for permission to overwrite a file.
`data` :	Data to be want 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 will allow a person to copy data from one location to another. The location is specified using a URIs as the means to describe the location of the data. Like any copy there are several options that can be set. These can be set using the xfer_options. In addition there are callback mechanisms and error codes to provide feedback in the copy process.

`source_uri` :	This is the location of where your data resides.
`target_uri` :	This is the location of where you want your data to go.
`xfer_options` :	Set the kind of transfers you want. These are: GNOME_VFS_XFER_DEFAULT: Default behavior. Which is to do a straight one to one copy. 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_RECURSIVE: Do a recursive copy of the source to the destination. Equivalent to the cp -r option in GNU cp. GNOME_VFS_XFER_SAME_FS: This only allows copying onto the same filesystem. GNOME_VFS_DELETE_ITEM: This is 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: <TBA> GNOME_VFS_XFER_NEW_UNIQUE_DIRECTORY: This will 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: This option will remove the source data after whatever xfer option has been taken. GNOME_VFS_USE_UNIQUE_NAMES: This is a check ot make sure that what you copy onto the destination is not overwritten. It will only copy the unique items from the source to the destjnation. GNOME_VFS_XFER_LINK_ITEMS: <TBA>
`error_mode` :	When this function returns you need to check the error code for the results of the copy. The results are generally: GNOME_VFS_XFER_ERROR_MODE_ABORT: This means that the operation was aborted by some sort of signal that interrupted the transfer. GNOME_VFS_ERROR_MODE_QUERY: This means that no error has occured and that you should query with the GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR. See
`overwrite_mode` :	This sets the options to deal with data that are duplicate between the source and the destination. Your choices are: GNOME_VFS_XFER_OVERWRITE_MODE_ABORT: This means abort the transfer if you see duplicate data. GNOME_VFS_XFER_OVERWRITE_MODE_REPLACE: Replace the files silently. Don't worry be happy. GNOME_VFS_XFER_OVERWRITE_MODE_SKIP: Skip duplicate files silenty. target.
`progress_callback` :	This is an important call back because this is how you communicate with your copy process.
`data` :	Data to be want 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);

Unlink items in the list source_uri_list from their filesystems.

`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 want passed back in callbacks from the xfer engine
Returns :	`GNOME_VFS_OK` if successful, or the appropriate error code otherwise