GnomeVFS - Filesystem Abstraction library
<<< Previous Page | Home | Up | Next Page >>>

# Asynchronous File I/O

## Name

Asynchronous File I/O -- allows for non-blocking file operations

## Synopsis

    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

The number of concurrent asynchronous jobs is limited. When the limit is reached jobs are put into a queue. The priority parameter determines which job is taken from the queue first and when.

Priority values range from -10 to 10, lower priority values mean higher priority.

How to decide the priority of a job?

Generally speaking jobs that can wait should be low priority, jobs that are urgent should be high priority.

Another possible approach is that jobs that potentially take long to finish should be low priority, jobs that finish quickly should be high priority.

For example, if your application is doing something in the background (e.g. looking for a directory) it can wait: choose low priority like 10. If you need update the user interface with the contents of a directory it should happen quickly: use a -10 priority job.

How to choose the priority value?

The scheduling algorithm reserves threads for high priority jobs so that running low priority jobs can't block high priority ones. The priority value of a job determines the maximum number of running jobs so that the job can start. E.g. if a job has a priority of -7 then it can start if there are less then 8 jobs running (using the default thread limit of 10).

## Details

### gnome_vfs_async_cancel ()

    void        gnome_vfs_async_cancel          (GnomeVFSAsyncHandle *handle);

Cancels an operation

`handle` : | the handle to cancel

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

Opens a text-based URI according to `open_mode`

`handle_return` : | a reference to where the newly created handle pointer should be stored
`text_uri` : | string representation of the URI
`open_mode` : | open mode
`priority` : | job priority
`callback` : | a callback for when the URI is opened or an error occured
`callback_data` : | data to be passed to the callback function

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

Opens a GnomeVFSURI according to `open_mode`. This function exposes a public `GnomeVFSURI` object, which may be deprecated eventually. Therefore, use of `gnome_vfs_async_open` is encouraged instead of this function to minimize breakage.

`handle_return` : | a reference to where the newly created handle pointer should be stored
`uri` : | `GnomeVFSURI` to open
`open_mode` : | open mode
`priority` : | job priority
`callback` : | a callback for when the URI is opened or an error occured
`callback_data` : | data to be passed to the callback function

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

`handle_return` : | a reference to where the newly created handle pointer should be stored
`text_uri` : |
`open_mode` : |
`advised_block_size` : |
`priority` : | job priority
`callback` : |
`callback_data` : | data to be passed to the callback function

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

`handle_return` : | a reference to where the newly created handle pointer should be stored
`uri` : |
`open_mode` : |
`advised_block_size` : |
`priority` : | job priority
`callback` : |
`callback_data` : | data to be passed to the callback function

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

`handle_return` : | a reference to where the newly created handle pointer should be stored
`text_uri` : |
`open_mode` : |
`exclusive` : |
`perm` : |
`priority` : | job priority
`callback` : |
`callback_data` : | data to be passed to the callback function

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

`handle_return` : | a reference to where the newly created handle pointer should be stored
`uri` : |
`open_mode` : |
`exclusive` : |
`perm` : |
`priority` : | job priority
`callback` : |
`callback_data` : | data to be passed to the callback function

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

`handle_return` : | a reference to where the newly created handle pointer should be stored
`uri` : |
`uri_reference` : |
`priority` : | job priority
`callback` : |
`callback_data` : | data to be passed to the callback function

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

`handle_return` : | a reference to where the newly created handle pointer should be stored
`text_uri` : |
`open_mode` : |
`exclusive` : |
`perm` : |
`priority` : | job priority
`callback` : |
`callback_data` : | data to be passed to the callback function

### 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` : | a reference to where the newly created handle pointer should be stored
`uri` : |
`open_mode` : |
`exclusive` : |
`perm` : |
`priority` : | job priority
`callback` : |
`callback_data` : | data to be passed to the callback function

### gnome_vfs_async_close ()

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

`handle` : | GnomeVFSHandle to close
`callback` : | a callback for when the `handle` is closed or an error has occured
`callback_data` : | data to be passed to the callback function

### gnome_vfs_async_read ()

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

`handle` : |
`buffer` : |
`bytes` : |
`callback` : |
`callback_data` : | data to be passed to the callback function

### gnome_vfs_async_write ()

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

`handle` : |
`buffer` : |
`bytes` : |
`callback` : |
`callback_data` : | data to be passed to the callback function

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

`handle_return` : | a reference to where the newly created handle pointer should be stored
`uri_list` : |
`options` : |
`priority` : | job priority
`callback` : |
`callback_data` : | data to be passed to the callback function

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

`handle_return` : | a reference to where the newly created handle pointer should be stored
`uri` : |
`info` : |
`mask` : |
`options` : |
`priority` : | job priority
`callback` : |
`callback_data` : | data to be passed to the callback function

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

`handle_return` : | a reference to where the newly created handle pointer should be stored
`text_uri` : |
`options` : |
`items_per_notification` : |
`priority` : | job priority
`callback` : |
`callback_data` : | data to be passed to the callback function

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

`handle_return` : | a reference to where the newly created handle pointer should be stored
`uri` : |
`options` : |
`items_per_notification` : |
`priority` : | job priority
`callback` : |
`callback_data` : | data to be passed to the callback function

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

Transfers file(s) from one location to another

`handle_return` : | a reference to where the newly created handle pointer should be stored
`source_uri_list` : | a `GList`. Each element should be a pointer to a GnomeVFSURI object
`target_uri_list` : | a `GList`. Each element should be a pointer to a GnomeVFSURI object
`xfer_options` : |
`error_mode` : |
`overwrite_mode` : |
`priority` : | job priority
`progress_update_callback` : |
`update_callback_data` : | data to be passed to the progress update callback function
`progress_sync_callback` : |
`sync_callback_data` : | data to be passed to the progress sync callback function
Returns : |

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

`handle_return` : | a reference to where the newly created handle pointer should be stored
`near_uri_list` : |
`kind` : |
`create_if_needed` : |
`find_if_needed` : |
`permissions` : |
`priority` : | job priority
`callback` : |
`user_data` : | data to be passed to the callback function

<<< Previous Page | Home | Up | Next Page >>>
Finding Special Directories | Copy Engine