
@c %start of fragment

@deffn Function gnome-vfs-async-get-file-info  (handle_return@tie{}@code{<gnome-vfs-async-handle**>}) (uri_list@tie{}@code{glist-of}) (options@tie{}@code{<gnome-vfs-file-info-options>}) (priority@tie{}@code{int}) (callback@tie{}@code{<gnome-vfs-async-get-file-info-callback>}) (callback_data@tie{}@code{<gpointer>})
Fetch information about the files indicated in @var{uri-list} and return the
information progressively to @var{callback}.

@table @var
@item handle-return
when the function returns, will point to a handle for the async operation.

@item uri-list
a @code{<g-list>} of @code{<gnome-vfsur-is>} to fetch information about.

@item options
packed boolean type providing control over various details of the get_file_info
operation.

@item priority
a value from @samp{GNOME_VFS_PRIORITY_MIN} to @samp{GNOME_VFS_PRIORITY_MAX}
(normally should be @samp{GNOME_VFS_PRIORITY_DEFAULT}) indicating the priority
to assign this job in allocating threads from the thread pool.

@item callback
function to be called when the operation is complete.

@item callback-data
data to pass to @var{callback}.

@end table

@end deffn

@deffn Function gnome-vfs-async-xfer  (handle_return@tie{}@code{<gnome-vfs-async-handle**>}) (source_uri_list@tie{}@code{glist-of}) (target_uri_list@tie{}@code{glist-of}) (xfer_options@tie{}@code{<gnome-vfs-xfer-options>}) (error_mode@tie{}@code{<gnome-vfs-xfer-error-mode>}) (overwrite_mode@tie{}@code{<gnome-vfs-xfer-overwrite-mode>}) (priority@tie{}@code{int}) (progress_update_callback@tie{}@code{<gnome-vfs-async-xfer-progress-callback>}) (update_callback_data@tie{}@code{<gpointer>}) (progress_sync_callback@tie{}@code{<gnome-vfs-xfer-progress-callback>}) (sync_callback_data@tie{}@code{<gpointer>}) @result{}@tie{} (ret@tie{}@code{<gnome-vfs-result>})
Performs an Xfer operation in a seperate thread, otherwise like
@code{gnome-vfs-xfer-uri-list}.

See @code{<gnome-vfs-async-xfer-progress-callback>} and
@code{<gnome-vfs-xfer-progress-callback>} for details on how the callback
mechanism works.



@var{progress-sync-callback} should only be used if you want to execute
additional actions that may not wait until after the transfer, for instance
because you have to do them for each transferred file/directory, and that
require a very specific action to be taken. For instance, the Nautilus
application schedules metadata removal/moving/copying at specific phases.

Do not use @var{progress-sync-callback} if you just need user feedback, because
each invocation is expensive, and requires a context switch.

If you use both @var{progress-update-callback} and @var{progress-sync-callback},
the @var{progress-sync-callback} will always be invoked before the
@var{progress-update-callback}. It is recommended to do conflict handling in
@var{progress-update-callback}, and always return @samp{@code{#t}} in
@var{progress-sync-callback}, because if the Xfer's
@code{<gnome-vfs-xfer-progress-status>} is
@samp{GNOME_VFS_XFER_PROGRESS_STATUS_OK}, @var{progress-update-callback} will
only be invoked if it hasn't been invoked within the last 100 milliseconds, and
if @var{progress-update-callback} is not invoked, only
@var{progress-sync-callback} is authoritative for the further processing,
causing abortion if it is @samp{@code{#f}}.

@table @var
@item handle-return
when the function returns, will point to a handle for the operation.

@item source-uri-list
A @code{<g-list>} of source @code{<gnome-vfsur-is>}.

@item target-uri-list
A @code{<g-list>} of target @code{<gnome-vfsur-is>}, each corresponding to one
URI in @var{source-uri-list}.

@item xfer-options
@code{<gnome-vfs-xfer-options>} defining the desired operation and parameters.

@item error-mode
A @code{<gnome-vfs-error-mode>} specifying how to proceed if a VFS error occurs.

@item overwrite-mode
A @code{<gnome-vfs-overwrite-mode>} specifying how to proceed if a file is being
overwritten.

@item priority
A value from @samp{GNOME_VFS_PRIORITY_MIN} to @samp{GNOME_VFS_PRIORITY_MAX}
(normally should be @samp{GNOME_VFS_PRIORITY_DEFAULT}) indicating the priority
to assign this job in allocating threads from the thread pool.

@item progress-update-callback
A @code{<gnome-vfs-async-xfer-callback>} called periodically for informing the
program about progress, and when the program requires responses to interactive
queries (e.g. overwriting files, handling errors, etc).

@item update-callback-data
User data to pass to @var{progress-update-callback}.

@item progress-sync-callback
An optional @code{<gnome-vfs-xfer-callback>} called whenever some state changed.

@item sync-callback-data
User data to pass to @var{progress-sync-callback}.

@item ret
@samp{GNOME_VFS_OK} if the paramaters were in order, or
@samp{GNOME_VFS_ERROR_BAD_PARAMETERS} if something was wrong in the passed in
arguments.

@end table

@end deffn

@deffn Function gnome-vfs-async-find-directory  (handle_return@tie{}@code{<gnome-vfs-async-handle**>}) (near_uri_list@tie{}@code{glist-of}) (kind@tie{}@code{<gnome-vfs-find-directory-kind>}) (create_if_needed@tie{}@code{bool}) (find_if_needed@tie{}@code{bool}) (permissions@tie{}@code{unsigned-int}) (priority@tie{}@code{int}) (callback@tie{}@code{<gnome-vfs-async-find-directory-callback>}) (user_data@tie{}@code{<gpointer>})
Used to return special directories such as Trash and Desktop from different file
systems.

There is quite a complicated logic behind finding/creating a Trash directory and
you need to be aware of some implications: Finding the Trash the first time when
using the file method may be pretty expensive. A cache file is used to store the
location of that Trash file for next time. If @var{create-if-needed} is
specified without @var{find-if-needed}, you may end up creating a Trash file
when there already is one. Your app should start out by doing a
gnome_vfs_find_directory with the @var{find-if-needed} to avoid this and then
use the @var{create-if-needed} flag to create Trash lazily when it is needed for
throwing away an item on a given disk.

When the operation has completed, @var{callback} will be called with the result
of the operation and @var{user-data}.

@table @var
@item handle-return
when the function returns, will point to a handle for the operation.

@item near-uri-list
a @code{<g-list>} of @code{<gnome-vfsur-is>}, find a special directory on the
same volume as @var{near-uri-list}.

@item kind
kind of special directory.

@item create-if-needed
if directory we are looking for does not exist, try to create it.

@item find-if-needed
if we don't know where the directory is yet, look for it.

@item permissions
if creating, use these permissions.

@item priority
a value from @samp{GNOME_VFS_PRIORITY_MIN} to @samp{GNOME_VFS_PRIORITY_MAX}
(normally should be @samp{GNOME_VFS_PRIORITY_DEFAULT}) indicating the priority
to assign to this job in allocating threads from the thread pool.

@item callback
function to be called when the operation is complete.

@item user-data
data to pass to @var{callback}.

@end table

@end deffn


@c %end of fragment
