Asynchronous File Operations

## Asynchronous File Operations 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);
                GnomeVFSFindDirectoryResult;
    void        (*GnomeVFSAsyncFileControlCallback)
                                                (GnomeVFSAsyncHandle *handle,
                                                 GnomeVFSResult result,
                                                 gpointer operation_data,
                                                 gpointer callback_data);
    typedef     GnomeVFSAsyncSeekCallback;
    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_seek            (GnomeVFSAsyncHandle *handle,
                                                 GnomeVFSSeekPosition whence,
                                                 GnomeVFSFileOffset offset,
                                                 GnomeVFSAsyncSeekCallback 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);
    void        gnome_vfs_async_file_control    (GnomeVFSAsyncHandle *handle,
                                                 const char *operation,
                                                 gpointer operation_data,
                                                 GDestroyNotify operation_data_destroy_func,
                                                 GnomeVFSAsyncFileControlCallback callback,
                                                 gpointer callback_data);

## Description

When executing an asynchornous operation on a file the program does not block waiting for the operation to finish, instead it keeps on running, which means that the process and the I/O operation can be both running concurrently. Once the I/O operation has been completed the process is notified using a callback.

Asynchronous operations are particularly good when long I/O operations are expected, in this case the program can continue normaly, the I/O will be performed in the background. On the other hand when operations are expected to be short (creating a file, writing/reading small amounts of data, etc.) synchronous operations are prefered.

Within a graphical desktop asynchornous I/O operations can be used to avoid blocking the UI (User Interface) during a long operation, and to be able to provide some kind of feedback to the user.

## 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;

### GnomeVFSAsyncFileControlCallback ()

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

`handle` : |
`result` : |
`operation_data` : |
`callback_data` : |

### GnomeVFSAsyncSeekCallback

    typedef GnomeVFSAsyncCallback GnomeVFSAsyncSeekCallback;

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

### 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.

In a single-threaded application, its guaranteed that if you call this before the operation finished callback has been called the callback will never be called.

However, in a multithreaded application, or to be more specific, if you call gnome_vfs_async_cancel from another thread than the thread handling the glib mainloop, there is a race condition where if the the operation finished callback was just dispatched, you might still cancel the operation. So, in this case you need to handle the fact that the operation callback might still run even though another thread has cancelled the operation.

One way to avoid problems from this is to mark the data structure you're using as callback_data as destroyed, and then queue an idle and do the actual freeing in an idle handler. The idle handler is guaranteed to run after the callback has been exectuted, so by then it is safe to destroy the callback_data. The callback handler must handle the case where the callback_data is marked destroyed by doing nothing.

This is clearly not ideal for multithreaded applications, but as good as we can with the current API. Eventually we'll have to change the API to make this work better.

`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_seek ()

    void        gnome_vfs_async_seek            (GnomeVFSAsyncHandle *handle,
                                                 GnomeVFSSeekPosition whence,
                                                 GnomeVFSFileOffset offset,
                                                 GnomeVFSAsyncSeekCallback callback,
                                                 gpointer callback_data);

Set the current position for reading/writing through `handle`. When the operation is complete, `callback` will be called with the result of the operation and `callback_data`.

`handle` : | Handle for which the current position must be changed
`whence` : | Integer value representing the starting position
`offset` : | Number of bytes to skip from the position specified by `whence` (a positive value means to move forward; a negative one to move backwards)
`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.

### gnome_vfs_async_file_control ()

    void        gnome_vfs_async_file_control    (GnomeVFSAsyncHandle *handle,
                                                 const char *operation,
                                                 gpointer operation_data,
                                                 GDestroyNotify operation_data_destroy_func,
                                                 GnomeVFSAsyncFileControlCallback callback,
                                                 gpointer callback_data);

Execute a backend dependent operation specified by the string `operation`. This is typically used for specialized vfs backends that need additional operations that gnome-vfs doesn't have. Compare it to the unix call `ioctl()`. The format of `operation_data` depends on the operation. Operation that are backend specific are normally namespaced by their module name.

When the operation is complete, `callback` will be called with the result of the operation, `operation_data` and `callback_data`.

`handle` : | handle of the file to affect
`operation` : | The operation to execute
`operation_data` : | The data needed to execute the operation
`operation_data_destroy_func` : | Called to destroy operation_data when its no longer needed
`callback` : | function to be called when the operation is complete
`callback_data` : | data to pass `callback`

Since 2.2