8.6 Transfers

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

)

typedef
gint (* GnomeVFSAsyncXferProgressCallback) (GnomeVFSAsyncHandle *

handle

,
                                            GnomeVFSXferProgressInfo *

info

,
                                            gpointer

data

);

callback

(

info

,

data

)