Asynchronous File Operations

Name

Asynchronous File Operations -- POSIX-style file operations that run outside your main loop

Synopsis



#define     GNOME_VFS_PRIORITY_MIN
#define     GNOME_VFS_PRIORITY_MAX
#define     GNOME_VFS_PRIORITY_DEFAULT
void        (*GnomeVFSAsyncCallback)        (GnomeVFSAsyncHandle *handle,
                                             GnomeVFSResult result,
                                             gpointer callback_data);
typedef     GnomeVFSAsyncOpenCallback;
typedef     GnomeVFSAsyncCreateCallback;
typedef     GnomeVFSAsyncCreateAsChannelCallback;
typedef     GnomeVFSAsyncCloseCallback;
void        (*GnomeVFSAsyncReadCallback)    (GnomeVFSAsyncHandle *handle,
                                             GnomeVFSResult result,
                                             gpointer buffer,
                                             GnomeVFSFileSize bytes_requested,
                                             GnomeVFSFileSize bytes_read,
                                             gpointer callback_data);
void        (*GnomeVFSAsyncWriteCallback)   (GnomeVFSAsyncHandle *handle,
                                             GnomeVFSResult result,
                                             gconstpointer buffer,
                                             GnomeVFSFileSize bytes_requested,
                                             GnomeVFSFileSize bytes_written,
                                             gpointer callback_data);
typedef     GnomeVFSFindDirectoryResult;
void        gnome_vfs_async_set_job_limit   (int limit);
int         gnome_vfs_async_get_job_limit   (void);
void        gnome_vfs_async_cancel          (GnomeVFSAsyncHandle *handle);
void        gnome_vfs_async_open            (GnomeVFSAsyncHandle **handle_return,
                                             const gchar *text_uri,
                                             GnomeVFSOpenMode open_mode,
                                             int priority,
                                             GnomeVFSAsyncOpenCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_open_uri        (GnomeVFSAsyncHandle **handle_return,
                                             GnomeVFSURI *uri,
                                             GnomeVFSOpenMode open_mode,
                                             int priority,
                                             GnomeVFSAsyncOpenCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_open_as_channel (GnomeVFSAsyncHandle **handle_return,
                                             const gchar *text_uri,
                                             GnomeVFSOpenMode open_mode,
                                             guint advised_block_size,
                                             int priority,
                                             GnomeVFSAsyncOpenAsChannelCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_open_uri_as_channel
                                            (GnomeVFSAsyncHandle **handle_return,
                                             GnomeVFSURI *uri,
                                             GnomeVFSOpenMode open_mode,
                                             guint advised_block_size,
                                             int priority,
                                             GnomeVFSAsyncOpenAsChannelCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_create          (GnomeVFSAsyncHandle **handle_return,
                                             const gchar *text_uri,
                                             GnomeVFSOpenMode open_mode,
                                             gboolean exclusive,
                                             guint perm,
                                             int priority,
                                             GnomeVFSAsyncOpenCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_create_uri      (GnomeVFSAsyncHandle **handle_return,
                                             GnomeVFSURI *uri,
                                             GnomeVFSOpenMode open_mode,
                                             gboolean exclusive,
                                             guint perm,
                                             int priority,
                                             GnomeVFSAsyncOpenCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_create_symbolic_link
                                            (GnomeVFSAsyncHandle **handle_return,
                                             GnomeVFSURI *uri,
                                             const gchar *uri_reference,
                                             int priority,
                                             GnomeVFSAsyncOpenCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_create_as_channel
                                            (GnomeVFSAsyncHandle **handle_return,
                                             const gchar *text_uri,
                                             GnomeVFSOpenMode open_mode,
                                             gboolean exclusive,
                                             guint perm,
                                             int priority,
                                             GnomeVFSAsyncCreateAsChannelCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_create_uri_as_channel
                                            (GnomeVFSAsyncHandle **handle_return,
                                             GnomeVFSURI *uri,
                                             GnomeVFSOpenMode open_mode,
                                             gboolean exclusive,
                                             guint perm,
                                             int priority,
                                             GnomeVFSAsyncCreateAsChannelCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_close           (GnomeVFSAsyncHandle *handle,
                                             GnomeVFSAsyncCloseCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_read            (GnomeVFSAsyncHandle *handle,
                                             gpointer buffer,
                                             guint bytes,
                                             GnomeVFSAsyncReadCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_write           (GnomeVFSAsyncHandle *handle,
                                             gconstpointer buffer,
                                             guint bytes,
                                             GnomeVFSAsyncWriteCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_get_file_info   (GnomeVFSAsyncHandle **handle_return,
                                             GList *uri_list,
                                             GnomeVFSFileInfoOptions options,
                                             int priority,
                                             GnomeVFSAsyncGetFileInfoCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_set_file_info   (GnomeVFSAsyncHandle **handle_return,
                                             GnomeVFSURI *uri,
                                             GnomeVFSFileInfo *info,
                                             GnomeVFSSetFileInfoMask mask,
                                             GnomeVFSFileInfoOptions options,
                                             int priority,
                                             GnomeVFSAsyncSetFileInfoCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_load_directory  (GnomeVFSAsyncHandle **handle_return,
                                             const gchar *text_uri,
                                             GnomeVFSFileInfoOptions options,
                                             guint items_per_notification,
                                             int priority,
                                             GnomeVFSAsyncDirectoryLoadCallback callback,
                                             gpointer callback_data);
void        gnome_vfs_async_load_directory_uri
                                            (GnomeVFSAsyncHandle **handle_return,
                                             GnomeVFSURI *uri,
                                             GnomeVFSFileInfoOptions options,
                                             guint items_per_notification,
                                             int priority,
                                             GnomeVFSAsyncDirectoryLoadCallback callback,
                                             gpointer callback_data);
GnomeVFSResult gnome_vfs_async_xfer         (GnomeVFSAsyncHandle **handle_return,
                                             GList *source_uri_list,
                                             GList *target_uri_list,
                                             GnomeVFSXferOptions xfer_options,
                                             GnomeVFSXferErrorMode error_mode,
                                             GnomeVFSXferOverwriteMode overwrite_mode,
                                             int priority,
                                             GnomeVFSAsyncXferProgressCallback progress_update_callback,
                                             gpointer update_callback_data,
                                             GnomeVFSXferProgressCallback progress_sync_callback,
                                             gpointer sync_callback_data);
void        gnome_vfs_async_find_directory  (GnomeVFSAsyncHandle **handle_return,
                                             GList *near_uri_list,
                                             GnomeVFSFindDirectoryKind kind,
                                             gboolean create_if_needed,
                                             gboolean find_if_needed,
                                             guint permissions,
                                             int priority,
                                             GnomeVFSAsyncFindDirectoryCallback callback,
                                             gpointer user_data);

Description

Details

GNOME_VFS_PRIORITY_MIN

#define GNOME_VFS_PRIORITY_MIN     -10

The minimuum priority a job can have.


GNOME_VFS_PRIORITY_MAX

#define GNOME_VFS_PRIORITY_MAX     10

The maximuum priority a job can have.


GNOME_VFS_PRIORITY_DEFAULT

#define GNOME_VFS_PRIORITY_DEFAULT 0

The default job priority. Its best to use this unless you have a reason to do otherwise.


GnomeVFSAsyncCallback ()

void        (*GnomeVFSAsyncCallback)        (GnomeVFSAsyncHandle *handle,
                                             GnomeVFSResult result,
                                             gpointer callback_data);

Basic callback from an async operation that passes no data back, informing the user of the result of the operation.

handle :

handle of the operation generating the callback

result :

GNOME_VFS_OK if the operation was successful, otherwise an error code.

callback_data :

user data defined when the callback was established


GnomeVFSAsyncOpenCallback

typedef GnomeVFSAsyncCallback GnomeVFSAsyncOpenCallback;

Basic callback from an async operation that passes no data back, informing the user of the result of the operation.


GnomeVFSAsyncCreateCallback

typedef GnomeVFSAsyncCallback GnomeVFSAsyncCreateCallback;

Basic callback from an async operation that passes no data back, informing the user of the result of the operation.


GnomeVFSAsyncCreateAsChannelCallback

typedef GnomeVFSAsyncOpenAsChannelCallback GnomeVFSAsyncCreateAsChannelCallback;

Callback for the gnome_vfs_async_create_as_channel() function.


GnomeVFSAsyncCloseCallback

typedef GnomeVFSAsyncCallback GnomeVFSAsyncCloseCallback;

Basic callback from an async operation that passes no data back, informing the user of the result of the operation.


GnomeVFSAsyncReadCallback ()

void        (*GnomeVFSAsyncReadCallback)    (GnomeVFSAsyncHandle *handle,
                                             GnomeVFSResult result,
                                             gpointer buffer,
                                             GnomeVFSFileSize bytes_requested,
                                             GnomeVFSFileSize bytes_read,
                                             gpointer callback_data);

Callback for the gnome_vfs_async_read() function.

handle :

handle of the operation generating the callback

result :

GNOME_VFS_OK if the operation was successful, otherwise an error code.

buffer :

buffer containing data read from handle.

bytes_requested :

the number of bytes asked for in the call to gnome_vfs_async_read().

bytes_read :

the number of bytes actually read from handle into buffer.

callback_data :

user data defined when the callback was established


GnomeVFSAsyncWriteCallback ()

void        (*GnomeVFSAsyncWriteCallback)   (GnomeVFSAsyncHandle *handle,
                                             GnomeVFSResult result,
                                             gconstpointer buffer,
                                             GnomeVFSFileSize bytes_requested,
                                             GnomeVFSFileSize bytes_written,
                                             gpointer callback_data);

Callback for the gnome_vfs_async_write() function.

handle :

handle of the operation generating the callback

result :

GNOME_VFS_OK if the operation was successful, otherwise an error code.

buffer :

buffer containing data written to handle.

bytes_requested :

the number of bytes asked to write in the call to gnome_vfs_async_write().

bytes_written :

the number of bytes actually written to handle from buffer.

callback_data :

user data defined when the callback was established


GnomeVFSFindDirectoryResult

typedef struct {
	GnomeVFSURI *uri;
	GnomeVFSResult result;

	/* Reserved to avoid future breaks in ABI compatibility */
	void *reserved1;
	void *reserved2;
} GnomeVFSFindDirectoryResult;


gnome_vfs_async_set_job_limit ()

void        gnome_vfs_async_set_job_limit   (int limit);

Restrict the number of worker threads used by Async operations to limit.

limit :

maximuum number of allowable threads


gnome_vfs_async_get_job_limit ()

int         gnome_vfs_async_get_job_limit   (void);

Get the current maximuum allowable number of worker threads for Asynch operations.

Returns :

current maximuum number of threads


gnome_vfs_async_cancel ()

void        gnome_vfs_async_cancel          (GnomeVFSAsyncHandle *handle);

Cancel an asynchronous operation and close all its callbacks. Its possible to still receive another call or two on the callback.

handle :

handle of the async operation to be cancelled


gnome_vfs_async_open ()

void        gnome_vfs_async_open            (GnomeVFSAsyncHandle **handle_return,
                                             const gchar *text_uri,
                                             GnomeVFSOpenMode open_mode,
                                             int priority,
                                             GnomeVFSAsyncOpenCallback callback,
                                             gpointer callback_data);

Open text_uri according to mode open_mode. On return, handle_return will contain a pointer to the operation. Once the file has been successfully opened, callback will be called with the GnomeVFSResult.

handle_return :

A pointer to a pointer to a GnomeVFSHandle object

text_uri :

string of the URI to open

open_mode :

Open mode

priority :

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

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_open_uri ()

void        gnome_vfs_async_open_uri        (GnomeVFSAsyncHandle **handle_return,
                                             GnomeVFSURI *uri,
                                             GnomeVFSOpenMode open_mode,
                                             int priority,
                                             GnomeVFSAsyncOpenCallback callback,
                                             gpointer callback_data);

Open uri according to mode open_mode. On return, handle_return will contain a pointer to the operation. Once the file has been successfully opened, callback will be called with the GnomeVFSResult.

handle_return :

A pointer to a pointer to a GnomeVFSHandle object

uri :

URI to open

open_mode :

Open mode

priority :

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

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_open_as_channel ()

void        gnome_vfs_async_open_as_channel (GnomeVFSAsyncHandle **handle_return,
                                             const gchar *text_uri,
                                             GnomeVFSOpenMode open_mode,
                                             guint advised_block_size,
                                             int priority,
                                             GnomeVFSAsyncOpenAsChannelCallback callback,
                                             gpointer callback_data);

Open text_uri as a GIOChannel. Once the channel has been established callback will be called with callback_data, the result of the operation, and if the result was GNOME_VFS_OK, a reference to a GIOChannel pointing at text_uri in open_mode.

handle_return :

A pointer to a pointer to a GnomeVFSHandle object

text_uri :

string of the URI to open as a GIOChannel

open_mode :

open for reading, writing, random, etc

advised_block_size :

the preferred block size for GIOChannel to read

priority :

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

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_open_uri_as_channel ()

void        gnome_vfs_async_open_uri_as_channel
                                            (GnomeVFSAsyncHandle **handle_return,
                                             GnomeVFSURI *uri,
                                             GnomeVFSOpenMode open_mode,
                                             guint advised_block_size,
                                             int priority,
                                             GnomeVFSAsyncOpenAsChannelCallback callback,
                                             gpointer callback_data);

Open uri as a GIOChannel. Once the channel has been established callback will be called with callback_data, the result of the operation, and if the result was GNOME_VFS_OK, a reference to a GIOChannel pointing at uri in open_mode.

handle_return :

A pointer to a pointer to a GnomeVFSHandle object

uri :

URI to open as a GIOChannel

open_mode :

open for reading, writing, random, etc

advised_block_size :

the preferred block size for GIOChannel to read

priority :

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

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_create ()

void        gnome_vfs_async_create          (GnomeVFSAsyncHandle **handle_return,
                                             const gchar *text_uri,
                                             GnomeVFSOpenMode open_mode,
                                             gboolean exclusive,
                                             guint perm,
                                             int priority,
                                             GnomeVFSAsyncOpenCallback callback,
                                             gpointer callback_data);

Create a file at uri according to mode open_mode, with permissions perm (in the standard UNIX packed bit permissions format). When the create has been completed callback will be called with the result code and callback_data.

handle_return :

A pointer to a pointer to a GnomeVFSHandle object

text_uri :

String representing the URI to create

open_mode :

mode to leave the file opened in after creation (or GNOME_VFS_OPEN_MODE_NONE to leave the file closed after creation)

exclusive :

Whether the file should be created in "exclusive" mode: i.e. if this flag is nonzero, operation will fail if a file with the same name already exists.

perm :

Bitmap representing the permissions for the newly created file (Unix style).

priority :

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

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_create_uri ()

void        gnome_vfs_async_create_uri      (GnomeVFSAsyncHandle **handle_return,
                                             GnomeVFSURI *uri,
                                             GnomeVFSOpenMode open_mode,
                                             gboolean exclusive,
                                             guint perm,
                                             int priority,
                                             GnomeVFSAsyncOpenCallback callback,
                                             gpointer callback_data);

Create a file at uri according to mode open_mode, with permissions perm (in the standard UNIX packed bit permissions format). When the create has been completed callback will be called with the result code and callback_data.

handle_return :

A pointer to a pointer to a GnomeVFSHandle object

uri :

the URI to create a file at

open_mode :

mode to leave the file opened in after creation (or GNOME_VFS_OPEN_MODE_NONE to leave the file closed after creation)

exclusive :

Whether the file should be created in "exclusive" mode: i.e. if this flag is nonzero, operation will fail if a file with the same name already exists.

perm :

Bitmap representing the permissions for the newly created file (Unix style).

priority :

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

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_create_symbolic_link ()

void        gnome_vfs_async_create_symbolic_link
                                            (GnomeVFSAsyncHandle **handle_return,
                                             GnomeVFSURI *uri,
                                             const gchar *uri_reference,
                                             int priority,
                                             GnomeVFSAsyncOpenCallback callback,
                                             gpointer callback_data);

Create a symbolic link at uri pointing to uri_reference. When the operation has complete callback will be called with the result of the operation and callback_data.

handle_return :

when the function returns will point to a handle for the async operation.

uri :

location to create the link at

uri_reference :

location to point uri to (can be a URI fragment, i.e. relative)

priority :

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

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_create_as_channel ()

void        gnome_vfs_async_create_as_channel
                                            (GnomeVFSAsyncHandle **handle_return,
                                             const gchar *text_uri,
                                             GnomeVFSOpenMode open_mode,
                                             gboolean exclusive,
                                             guint perm,
                                             int priority,
                                             GnomeVFSAsyncCreateAsChannelCallback callback,
                                             gpointer callback_data);

Open text_uri as a GIOChannel, creating it as necessary. Once the channel has been established callback will be called with callback_data, the result of the operation, and if the result was GNOME_VFS_OK, a reference to a GIOChannel pointing at text_uri in open_mode.

handle_return :

A pointer to a pointer to a GnomeVFSHandle object

text_uri :

string of the URI to open as a GIOChannel, creating it as necessary

open_mode :

open for reading, writing, random, etc

exclusive :

replace the file if it already exists

perm :

standard POSIX-style permissions bitmask, permissions of created file

priority :

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

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_create_uri_as_channel ()

void        gnome_vfs_async_create_uri_as_channel
                                            (GnomeVFSAsyncHandle **handle_return,
                                             GnomeVFSURI *uri,
                                             GnomeVFSOpenMode open_mode,
                                             gboolean exclusive,
                                             guint perm,
                                             int priority,
                                             GnomeVFSAsyncCreateAsChannelCallback callback,
                                             gpointer callback_data);

handle_return :

uri :

open_mode :

exclusive :

perm :

priority :

callback :

callback_data :


gnome_vfs_async_close ()

void        gnome_vfs_async_close           (GnomeVFSAsyncHandle *handle,
                                             GnomeVFSAsyncCloseCallback callback,
                                             gpointer callback_data);

Close a handle opened with gnome_vfs_async_open(). When the close has completed, callback will be called with callback_data and the result of the operation.

handle :

async handle to close

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_read ()

void        gnome_vfs_async_read            (GnomeVFSAsyncHandle *handle,
                                             gpointer buffer,
                                             guint bytes,
                                             GnomeVFSAsyncReadCallback callback,
                                             gpointer callback_data);

Read bytes bytes from the file pointed to be handle into buffer. When the operation is complete, callback will be called with the result of the operation and callback_data.

handle :

handle for the file to be read

buffer :

allocated block of memory to read into

bytes :

number of bytes to read

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_write ()

void        gnome_vfs_async_write           (GnomeVFSAsyncHandle *handle,
                                             gconstpointer buffer,
                                             guint bytes,
                                             GnomeVFSAsyncWriteCallback callback,
                                             gpointer callback_data);

Write bytes bytes from buffer into the file pointed to be handle. When the operation is complete, callback will be called with the result of the operation and callback_data.

handle :

handle for the file to be written

buffer :

block of memory containing data to be written

bytes :

number of bytes to write

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_get_file_info ()

void        gnome_vfs_async_get_file_info   (GnomeVFSAsyncHandle **handle_return,
                                             GList *uri_list,
                                             GnomeVFSFileInfoOptions options,
                                             int priority,
                                             GnomeVFSAsyncGetFileInfoCallback callback,
                                             gpointer callback_data);

Fetch information about the files indicated in uris and return the information progressively to callback.

handle_return :

when the function returns will point to a handle for the async operation.

uri_list :

a GList of GnomeVFSURIs to fetch information about

options :

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

priority :

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

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_set_file_info ()

void        gnome_vfs_async_set_file_info   (GnomeVFSAsyncHandle **handle_return,
                                             GnomeVFSURI *uri,
                                             GnomeVFSFileInfo *info,
                                             GnomeVFSSetFileInfoMask mask,
                                             GnomeVFSFileInfoOptions options,
                                             int priority,
                                             GnomeVFSAsyncSetFileInfoCallback callback,
                                             gpointer callback_data);

Set "file info" details about the file at uri, such as permissions, name, owner, and modification time.

handle_return :

when the function returns will point to a handle for the async operation.

uri :

the URI to set the file info of

info :

the struct containing new information about the file

mask :

control which fields of info are changed about the file at uri

options :

packed boolean type providing control over various details of the set_file_info operation.

priority :

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

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_load_directory ()

void        gnome_vfs_async_load_directory  (GnomeVFSAsyncHandle **handle_return,
                                             const gchar *text_uri,
                                             GnomeVFSFileInfoOptions options,
                                             guint items_per_notification,
                                             int priority,
                                             GnomeVFSAsyncDirectoryLoadCallback callback,
                                             gpointer callback_data);

Read the contents of the directory at text_uri, passing back GnomeVFSFileInfo structs about each file in the directory to callback. items_per_notification files will be processed between each call to callback.

handle_return :

when the function returns will point to a handle for the async operation.

text_uri :

string representing the URI of the directory to be loaded

options :

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

items_per_notification :

number of files to process in a row before calling callback

priority :

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

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_load_directory_uri ()

void        gnome_vfs_async_load_directory_uri
                                            (GnomeVFSAsyncHandle **handle_return,
                                             GnomeVFSURI *uri,
                                             GnomeVFSFileInfoOptions options,
                                             guint items_per_notification,
                                             int priority,
                                             GnomeVFSAsyncDirectoryLoadCallback callback,
                                             gpointer callback_data);

Read the contents of the directory at uri, passing back GnomeVFSFileInfo structs about each file in the directory to callback. items_per_notification files will be processed between each call to callback.

handle_return :

when the function returns will point to a handle for the async operation.

uri :

string representing the URI of the directory to be loaded

options :

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

items_per_notification :

number of files to process in a row before calling callback

priority :

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

callback :

function to be called when the operation is complete

callback_data :

data to pass callback


gnome_vfs_async_xfer ()

GnomeVFSResult gnome_vfs_async_xfer         (GnomeVFSAsyncHandle **handle_return,
                                             GList *source_uri_list,
                                             GList *target_uri_list,
                                             GnomeVFSXferOptions xfer_options,
                                             GnomeVFSXferErrorMode error_mode,
                                             GnomeVFSXferOverwriteMode overwrite_mode,
                                             int priority,
                                             GnomeVFSAsyncXferProgressCallback progress_update_callback,
                                             gpointer update_callback_data,
                                             GnomeVFSXferProgressCallback progress_sync_callback,
                                             gpointer sync_callback_data);

Perform a copy operation in a seperate thread. progress_update_callback will be periodically polled with status of the operation (percent done, the current phase of operation, the current file being operated upon). If the xfer engine needs to query the caller to make a decision or report on important error it will do so on progress_sync_callback.

handle_return :

when the function returns will point to a handle for

source_uri_list :

GList of GnomeVFSURI representing the files to be transferred

target_uri_list :

GList of GnomeVFSURI, the target locations for the elements in source_uri_list

xfer_options :

various options controlling the details of the transfer. Use GNOME_VFS_XFER_REMOUVESOURCE to make the operation a move rather than a copy.

error_mode :

report errors to the progress_sync_callback, or simply abort

overwrite_mode :

controls whether the xfer engine will overwrite automatically, skip the file, abort the operation, or query progress_sync_callback

priority :

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

progress_update_callback :

called periodically to keep the client appraised of progress in completing the XFer operation, and the current phase of operation.

update_callback_data :

user data passed to progress_update_callback

progress_sync_callback :

called when the program requires responses to interactive queries (e.g. overwriting files, handling errors, etc)

sync_callback_data :

user data passed to progress_sync_callback

Returns :

GNOME_VFS_OK if the paramaters were in order, or GNOME_VFS_ERROR_BAD_PARAMETERS if something was wrong in the passed in arguments.


gnome_vfs_async_find_directory ()

void        gnome_vfs_async_find_directory  (GnomeVFSAsyncHandle **handle_return,
                                             GList *near_uri_list,
                                             GnomeVFSFindDirectoryKind kind,
                                             gboolean create_if_needed,
                                             gboolean find_if_needed,
                                             guint permissions,
                                             int priority,
                                             GnomeVFSAsyncFindDirectoryCallback callback,
                                             gpointer user_data);

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 ceate_if_needed is specified without 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 find_if_needed to avoid this and then use the 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, callback will be called with the result of the operation and user_data.

handle_return :

when the function returns will point to a handle for

near_uri_list :

a GList of GnomeVFSURIs, find a special directory on the same volume as uris

kind :

kind of special directory

create_if_needed :

If directory we are looking for does not exist, try to create it

find_if_needed :

If we don't know where the directory is yet, look for it.

permissions :

If creating, use these permissions

priority :

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

callback :

function to be called when the operation is complete

user_data :

data to pass callback * Used to return special directories such as Trash and Desktop from different file systems.