File Transfers

## 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;
                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;

### GnomeVFSXferProgressInfo

    typedef struct {
    	/* 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;
    } GnomeVFSXferProgressInfo;

### GnomeVFSXferProgressCallback ()

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

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

`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