The Official GNOME 2 Developers Guide

8.6 Transfers

Transfers are powerful utilities for transferring files from one place to another. You can copy anything from a single file to an entire directory tree with just a single statement, regardless of the file system type.

The API and mechanism is somewhat complicated. After you start a transfer, GnomeVFS periodically runs one of your callback functions. Your callback may need to answer a query, and that's the tricky part; you need to take a very close look at the callback parameters so that you know what kind of answer is appropriate.

The basic URI transfer function is

GnomeVFSResult gnome_vfs_xfer_uri(const GnomeVFSURI * src_uri , const GnomeVFSURI * target_uri , GnomeVFSXferOptions options , GnomeVFSXferErrorMode error_mode , GnomeVFSXferOverwriteMode overwrite_mode , GnomeVFSXferProgressCallback callback , gpointer data )

This function transfers src_uri to its corresponding location in target_uri .

Specify options as a bitwise OR of these constants:

• GNOME_VFS_XFER_DEFAULT

• GNOME_VFS_XFER_REMOVESOURCE : Moves the files; doesn't just copy.

• GNOME_VFS_XFER_LINK_ITEMS : Does not copy; creates symbolic links.

• GNOME_VFS_XFER_FOLLOW_LINKS : Follows symbolic links in the source.

• GNOME_VFS_XFER_RECURSIVE : If the source is a directory, copies the entire contents.

• GNOME_VFS_XFER_SAMEFS : Limits transfer to the same (local) file system.

• GNOME_VFS_XFER_USE_UNIQUE_NAMES : Makes sure that the transfer does not overwrite files at the target by giving new names to the source files that already exist in the target.

• GNOME_VFS_XFER_DELETE_ITEMS : Does not copy; removes the source (set target_uri to NULL ).

• GNOME_VFS_XFER_EMPTY_DIRECTORIES : Does not copy; removes the contents of the source (set target_uri to NULL ).

• GNOME_VFS_XFER_NEW_UNIQUE_DIRECTORY : Does not copy; creates a new directory at the target. If the target already exists, the callback function will have the name of another new, unique directory.

Specify error_mode as one of the following:

• GNOME_VFS_XFER_ERROR_MODE_ABORT : Terminates the transfer if errors occur.

• GNOME_VFS_XFER_ERROR_MODE_QUERY : Stops transfer and asks the callback for advice.

The overwrite_mode parameter determines what GnomeVFS does when a transfer can overwrite a file:

• GNOME_VFS_XFER_OVERWRITE_MODE_ABORT : Terminates the transfer.

• GNOME_VFS_XFER_OVERWRITE_MODE_QUERY : Asks the callback function for advice.

• GNOME_VFS_XFER_OVERWRITE_MODE_REPLACE : Replaces the file (silently).

• GNOME_VFS_XFER_OVERWRITE_MODE_SKIP : Skips the file.

Every few hundred milliseconds , or whenever interaction is necessary as noted in the preceding discussion, GnomeVFS invokes

callback ( info , data )

The full type definition for callback is

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

Note that callback must be able to answer queries from GnomeVFS. To determine the answer, use the following general procedure:

1. Look at info ->status to see what GnomeVFS wants.

2. Figure out what return codes work for the status.

3. Look at any other fields in info to make a final decision.

Detailed descriptions of each step follow.

Step 1:

The value of info ->status can be any of the following:

• GNOME_VFS_XFER_PROGRESS_STATUS_OK : No errors; a normal status report.

• GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR : The callback must react to an error.

• GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE : The callback must determine whether GnomeVFS should overwrite a file.

• GNOME_VFS_XFER_PROGRESS_STATUS_DUPLICATE : The callback must determine what to do about a duplicate filename.

Step 2:

If info ->status says that everything is going well, return 1 to continue or 0 to terminate the transfer. For an error, your callback can return one of the following:

• GNOME_VFS_XFER_ERROR_ACTION_ABORT : Terminate the transfer.

• GNOME_VFS_XFER_ERROR_ACTION_RETRY : Try again.

• GNOME_VFS_XFER_ERROR_ACTION_SKIP : Skip this operation and continue.

For overwrite questions, the return codes are

• GNOME_VFS_XFER_OVERWRITE_ACTION_ABORT : Terminate the transfer.

• GNOME_VFS_XFER_OVERWRITE_ACTION_REPLACE : Replace the file.

• GNOME_VFS_XFER_OVERWRITE_ACTION_REPLACE_ALL : Replace this and any other files with duplicate names in the future.

• GNOME_VFS_XFER_OVERWRITE_ACTION_SKIP : Skip this file.

• GNOME_VFS_XFER_OVERWRITE_ACTION_SKIP_ALL : Skip this and any other files with duplicate names in the future.

For duplicate filenames, set info ->duplicate_name (see the discussion that follows) and return 1 to continue or 0 to stop.

Step 3:

GnomeVFSXferProgressInfo is a large structure with these fields:

• status ( GnomeVFSXferProgressStatus ): See the preceding discussion.

• vfs_status ( GnomeVFSResult ): Error code from VFS operation (see Section 8.10).

• phase ( GnomeVFSXferPhase ): Current transfer phase; one of

  • GNOME_VFS_XFER_PHASE_INITIAL

  • GNOME_VFS_XFER_CHECKING_DESTINATION

  • GNOME_VFS_XFER_PHASE_COLLECTING (collecting source files)

  • GNOME_VFS_XFER_PHASE_READYTOGO

  • GNOME_VFS_XFER_PHASE_OPENSOURCE (opening the source file)

  • GNOME_VFS_XFER_PHASE_OPENTARGET (opening the target file)

  • 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 (setting the target file information)

  • GNOME_VFS_XFER_PHASE_FILECOMPLETED (ready for the next file)

  • GNOME_VFS_XFER_PHASE_CLEANUP

  • GNOME_VFS_XFER_PHASE_COMPLETED

• source_name ( gchar * ): Source URI.

• target_name ( gchar * ): Target URI.

• file_index ( gulong ): Current file number.

• files_total ( gulong ): Total number of files in the transfer.

• bytes_total ( GnomeVFSFileSize ): Total number of bytes in the transfer.

• file_size ( GnomeVFSFileSize ): Current file size .

• bytes_copied ( GnomeVFSFileSize ): Number of bytes transferred from the current file so far.

• total_bytes_copied ( GnomeVFSFileSize ): Total number of bytes copied in the transfer so far.

• duplicate_name ( gchar * ): Set this to avoid a duplicate file.

• duplicate_count ( int ): The number of copies of the file so far; helps build a unique name like copy 2 of file .

• top_level_item ( gboolean ): If TRUE , the transfer function call explicitly named the current item; it is not part of a recursively traversed subdirectory.

8.6.1 Additional Transfer Functions

Now that you've seen the particulars of transferring a single item, you are ready to see the other transfer utilities at your disposal:

• GnomeVFSResult gnome_vfs_xfer_uri_list(const GList * src_uri_list , const GList * target_uri_list , GnomeVFSXferOptions options , GnomeVFSXferErrorMode error_mode , GnomeVFSXferOverwriteMode overwrite_mode , GnomeVFSXferProgressCallback callback , gpointer data )

  Like gnome_vfs_xfer_uri() , but transfers each URI in src_uri_list to its corresponding URI in target_uri_list .

• GnomeVFSResult gnome_vfs_xfer_delete_list(const GList * src_uri_list , GnomeVFSXferErrorMode error_mode , GnomeVFSXferOptions options , GnomeVFSXferProgressCallback callback , gpointer data )

  Deletes the items in src_uri_list .

• GnomeVFSResult gnome_vfs_async_xfer(GnomeVFSAsyncHandle ** handle_addr , const GList * src_uri_list , const GList * target_uri_list , GnomeVFSXferOptions options , GnomeVFSXferErrorMode error_mode , GnomeVFSXferOverwriteMode overwrite_mode , GnomeVFSAsyncXferProgressCallback afunc , gpointer adata , GnomeVFSXferProgressCallback callback , gpointer data )

  Like gnome_vfs_xfer_uri_list() , but in asynchronous mode, so that your program can perform other tasks during a transfer. For regular status reports , GnomeVFS invokes

afunc (* handle_addr , info , adata )

The type definition for afunc is

typedef gint (* GnomeVFSAsyncXferProgressCallback) (GnomeVFSAsyncHandle * handle , GnomeVFSXferProgressInfo * info , gpointer data );

For synchronous requests that require an answer, GnomeVFS makes the usual call to

callback ( info , data )