The guy who was documenting this didn't have much experience with the
code, so its possible (likely even) that there are some mistakes. I
would love it if you could tell me whats wrong so I can fix it. I
don't really know the xfer API either.

GNOME_VFS_XFER_RECURSIVE does not mean "copy recursively", it just
means "whaetever we'll do, recurse when snarfing the source file list"

GNOME_VFS_XFER_DELETE_ITEM: this does *not* mean a mv; this means
"delete the source file list", and asserts that the destination list
is empty!

GNOME_VFS_XFER_REMOVESOURCE: settings this means the source files will
be removed after the operation -- this means a mv

GNOME_VFS_XFER_EMPTY_DIRECTORES: will empty the directories in the
source list, asserts destination list is empty

GNOME_VFS_XFER_USE_UNIQUE_NAMES: does not mean "transfer only unique
items" -- this means "at name collision, ask back so files won't be
overwritten, but named uniquely"

GNOME_VFS_XFER_NEW_UNIQUE_DIRECTORY: description is utter hogwash;
what this does is create exactly one unique new directory; asserts
source list has exactly 1 entry and destination list is empty

GNOME_VFS_XFER_LINK_ITEMS: means link instead of copy

BTW, the layout of that documentation page is also very broken and
hard to read. I can fix this if you want to, as soon as I'm done with
the book

Reopening. Is this still relevant to the current behaviour?

*** Bug 165739 has been marked as a duplicate of this bug. ***

Moving over the comments from bug 165739:

[From Olivier Sessink] 
the docs for gnome_vfs_async_xfer are somewhat fuzzy, I'll try to explain the
issues:

1) GnomeVFSAsyncXferProgressCallback is not linked (from the html docs), I
looked it up in the gnome-vfs-async-ops.h file. In that file it sais the
callback should always return 0, except if status is GnomeVFSXferErrorAction or
GnomeVFSOverwriteAction.

2) GnomeVFSXferProgressCallback is in the html docs, but without description

3) both callbacks return gint, it seems unlogical that both have to pass the
user descision to gnome_vfs, so what should the return value be for both of the
functions?

4) returning 0 by default (as written in gnome-vfs-async-ops.h) seems to abort
all transfer

5) it *seems* (after some debugging, and looking at nautilus code) that the
progress_sync_callback is the callback that should pass the user descision to
gnome_vfs (please check this first)

another (only slightly related) issue:
the html index does not show the async functions. You have to click 'file
operations' and click 3 times 'next' to get to those functions

Created attachment 37587 [details] [review]
patch that fixes most of the documentation issues with this function

I don't know how gtk-doc works, so I did not build the new documentation, so
this is not tested.

Created attachment 48823 [details] [review]
XferOptions patch

This is orthogonal to Olivier's stuff: it just takes care of moving all the
xfer options explanation along the enum where it belongs and also rectifies the
wrong informations pointed out in comment #2.

there is also typo in the description of the data parameter of gnome_vfs_xfer_uri()

data :	 Data to be want passed back in callbacks from the xfer engine

Is there any update on this? I need to use the Xfer API and am a little confused by the documentation and now a bit more because of this bug report.

gnome-vfs has been deprecated and superseded by gio/gvfs since GNOME 2.22, hence mass-closing many of the gnome-vfs requests/bug reports. This means that gnome-vfs is NOT actively maintained anymore, however patches are still welcome.

If your reported issue is still valid for gio/gvfs, please feel free to file a bug report against glib/gio or gvfs.

@Bugzilla mail recipients: query for gnome-vfs-mass-close to get rid of these notification emails all together.


General further information: http://en.wikipedia.org/wiki/GVFS 
Reasons behind this decision are listed at http://www.mail-archive.com/gnome-vfs-list@gnome.org/msg00899.html