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:

Look at info ->status to see what GnomeVFS wants.
Figure out what return codes work for the status.
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  )