Asynchronous File Operations

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

Functions

void (*GnomeVFSAsyncCallback) ()
void (*GnomeVFSAsyncOpenCallback) ()
void (*GnomeVFSAsyncOpenAsChannelCallback) ()
void (*GnomeVFSAsyncCreateCallback) ()
void (*GnomeVFSAsyncCreateAsChannelCallback) ()
void (*GnomeVFSAsyncCloseCallback) ()
void (*GnomeVFSAsyncReadCallback) ()
void (*GnomeVFSAsyncWriteCallback) ()
void (*GnomeVFSAsyncSeekCallback) ()
void (*GnomeVFSAsyncGetFileInfoCallback) ()
void (*GnomeVFSAsyncSetFileInfoCallback) ()
void (*GnomeVFSAsyncFileControlCallback) ()
void (*GnomeVFSAsyncDirectoryLoadCallback) ()
void (*GnomeVFSAsyncFindDirectoryCallback) ()
gint (*GnomeVFSAsyncXferProgressCallback) ()
void gnome_vfs_async_set_job_limit ()
int gnome_vfs_async_get_job_limit ()
void gnome_vfs_async_cancel ()
void gnome_vfs_async_open ()
void gnome_vfs_async_open_uri ()
void gnome_vfs_async_open_as_channel ()
void gnome_vfs_async_open_uri_as_channel ()
void gnome_vfs_async_create ()
void gnome_vfs_async_create_uri ()
void gnome_vfs_async_create_symbolic_link ()
void gnome_vfs_async_create_as_channel ()
void gnome_vfs_async_create_uri_as_channel ()
void gnome_vfs_async_close ()
void gnome_vfs_async_read ()
void gnome_vfs_async_write ()
void gnome_vfs_async_seek ()
void gnome_vfs_async_get_file_info ()
void gnome_vfs_async_set_file_info ()
void gnome_vfs_async_load_directory ()
void gnome_vfs_async_load_directory_uri ()
GnomeVFSResult gnome_vfs_async_xfer ()
void gnome_vfs_async_find_directory ()
void gnome_vfs_async_file_control ()
GnomeVFSFindDirectoryResult * gnome_vfs_find_directory_result_dup ()
void gnome_vfs_find_directory_result_free ()

Types and Values

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.

Functions

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.

Parameters

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

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

Callback for the gnome_vfs_async_open() function, informing the user of the result of the operation.

Parameters

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

 

GnomeVFSAsyncOpenAsChannelCallback ()

void
(*GnomeVFSAsyncOpenAsChannelCallback) (GnomeVFSAsyncHandle *handle,
                                       GIOChannel *channel,
                                       GnomeVFSResult result,
                                       gpointer callback_data);

GnomeVFSAsyncOpenAsChannelCallback is deprecated and should not be used in newly-written code.

Callback for the gnome_vfs_async_open_as_channel() function, informing the user of the result of the operation.

Parameters

handle

handle of the operation generating the callback.

 

channel

a GIOChannel corresponding to the file opened

 

result

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

 

callback_data

user data defined when the callback was established.

 

GnomeVFSAsyncCreateCallback ()

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

Callback for the gnome_vfs_async_create() function, informing the user of the result of the operation.

Parameters

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

 

GnomeVFSAsyncCreateAsChannelCallback ()

void
(*GnomeVFSAsyncCreateAsChannelCallback)
                               (GnomeVFSAsyncHandle *handle,
                                GIOChannel *channel,
                                GnomeVFSResult result,
                                gpointer callback_data);

GnomeVFSAsyncCreateAsChannelCallback is deprecated and should not be used in newly-written code.

Callback for the gnome_vfs_async_create_as_channel() function, informing the user of the result of the operation.

Parameters

handle

handle of the operation generating the callback.

 

channel

a GIOChannel corresponding to the file created

 

result

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

 

callback_data

user data defined when the callback was established.

 

GnomeVFSAsyncCloseCallback ()

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

Callback for the gnome_vfs_async_close() function, informing the user of the result of the operation.

Parameters

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

 

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, informing the user of the result of the operation.

Parameters

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, informing the user of the result of the operation.

Parameters

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.

 

GnomeVFSAsyncSeekCallback ()

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

Callback for the gnome_vfs_async_seek() function, informing the user of the result of the operation.

Parameters

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.

 

GnomeVFSAsyncGetFileInfoCallback ()

void
(*GnomeVFSAsyncGetFileInfoCallback) (GnomeVFSAsyncHandle *handle,
                                     GList *results,
                                     gpointer callback_data);

Callback for the gnome_vfs_async_get_file_info() function, informing the user of the results of the operation.

Parameters

handle

handle of the operation generating the callback

 

results

GList of GnomeVFSFileInfoResult * items representing the success of each gnome_vfs_get_file_info() and the data retrieved.

 

callback_data

user data defined when the callback was established.

 

GnomeVFSAsyncSetFileInfoCallback ()

void
(*GnomeVFSAsyncSetFileInfoCallback) (GnomeVFSAsyncHandle *handle,
                                     GnomeVFSResult result,
                                     GnomeVFSFileInfo *file_info,
                                     gpointer callback_data);

Callback for the gnome_vfs_async_set_file_info() function, informing the user of the result of the operation and returning the new file_info .

Setting the file info sometimes changes more information than the caller specified; for example, if the name changes the MIME type might change, and if the owner changes the SUID & SGID bits might change. Therefore the callback returns the new file_info for the caller's convenience. The GnomeVFSFileInfoOptions passed here are those used for the returned file info; they are not used when setting.

Parameters

handle

handle of the operation generating the callback

 

result

GNOME_VFS_OK if the operation was successful, otherwise a GnomeVFSResult error code.

 

file_info

if result is GNOME_VFS_OK, a GnomeVFSFileInfo struct containing information about the file.

 

callback_data

user data defined when the callback was established

 

GnomeVFSAsyncFileControlCallback ()

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

Callback for the gnome_vfs_async_find_directory() function. informing the user of the result of the operation, and providing the requested operation_data .

Parameters

handle

handle of the operation generating the callback

 

result

GNOME_VFS_OK if the operation was successful, otherwise a GnomeVFSResult error code.

 

operation_data

The data requested from the module if result is GNOME_VFS_OK.

 

callback_data

User data defined when the operation was established.

 

GnomeVFSAsyncDirectoryLoadCallback ()

void
(*GnomeVFSAsyncDirectoryLoadCallback) (GnomeVFSAsyncHandle *handle,
                                       GnomeVFSResult result,
                                       GList *list,
                                       guint entries_read,
                                       gpointer callback_data);

Callback for the gnome_vfs_async_directory_load() function. informing the user of the result of the operation and providing a file list if the result is GNOME_VFS_OK.

Parameters

handle

handle of the operation generating the callback.

 

result

GNOME_VFS_OK if the operation was sucessful, GNOME_VFS_ERROR_EOF if the last file in the directory has been read, otherwise a GnomeVFSResult error code

 

list

a GList of GnomeVFSFileInfo structs representing information about the files just loaded.

 

entries_read

number of entries read from handle for this instance of the callback.

 

callback_data

user data defined when the callback was established.

 

GnomeVFSAsyncFindDirectoryCallback ()

void
(*GnomeVFSAsyncFindDirectoryCallback) (GnomeVFSAsyncHandle *handle,
                                       GList *results,
                                       gpointer data);

Callback for the gnome_vfs_async_find_directory() function, informing the user of the results of the operation.

Parameters

handle

handle of the operation generating the callback

 

results

GList of GnomeVFSFindDirectoryResult *s containing special directories matching the find criteria.

 

data

user data defined when the operation was established

 

GnomeVFSAsyncXferProgressCallback ()

gint
(*GnomeVFSAsyncXferProgressCallback) (GnomeVFSAsyncHandle *handle,
                                      GnomeVFSXferProgressInfo *info,
                                      gpointer user_data);

This callback is passed to gnome_vfs_async_xfer() and should be used for user interaction. That said, it serves two purposes: Informing the user about the progress of the operation, and making decisions.

On the one hand, when the transfer progresses normally, i.e. when the info 's status is GNOME_VFS_XFER_PROGRESS_STATUS_OK it is called periodically whenever new progress information is available, and it wasn't called already within the last 100 milliseconds.

On the other hand, it is called whenever a decision is requested from the user, i.e. whenever the info 's status is not GNOME_VFS_XFER_PROGRESS_STATUS_OK.

Either way, it acts like GnomeVFSXferProgressCallback would act in non-asynchronous mode. The differences in invocation are explained in the gnome_vfs_async_xfer() documentation.

Parameters

handle

Handle of the Xfer operation generating the callback.

 

info

Information on the current progress in the transfer.

 

user_data

The user data that was passed to gnome_vfs_async_xfer().

 

Returns

gint depending on the GnomeVFSXferProgressInfo. Please consult GnomeVFSXferProgressCallback for details.


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 .

Parameters

limit

maximum number of allowable threads.

 

gnome_vfs_async_get_job_limit ()

int
gnome_vfs_async_get_job_limit (void);

Get the current maximum allowable number of worker threads for async operations.

Returns

current maximum 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 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.

Parameters

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.

Parameters

handle_return

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 to this job in allocating threads from the thread pool.

 

callback

function to be called when the operation is complete.

 

callback_data

data to pass to 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.

Parameters

handle_return

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 to this job in allocating threads from the thread pool.

 

callback

function to be called when the operation is complete.

 

callback_data

data to pass to 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);

gnome_vfs_async_open_as_channel is deprecated and should not be used in newly-written code.

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 .

This function has been deprecated due to behaving weirdly which suggests that it hasn't been used. See bugs 157266, 157265, 157261, 138398 in the GNOME Bugzilla. If the *_as_channel functions are needed they should be fixed and undeprecated.

Parameters

handle_return

pointer to a pointer to a GnomeVFSHandle object.

 

text_uri

string of the uri to open as a GIOChannel.

 

open_mode

open mode i.e. 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 to 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);

gnome_vfs_async_open_uri_as_channel is deprecated and should not be used in newly-written code.

This function has been deprecated due to behaving weirdly which suggests that it shouldn't be used. See bugs 157266, 157265, 157261, 138398 in the GNOME Bugzilla. If the *_as_channel functions are needed they should be fixed and undeprecated.

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 .

Parameters

handle_return

pointer to a pointer to a GnomeVFSHandle object.

 

uri

uri to open as a GIOChannel.

 

open_mode

open mode i.e. 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 to 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);

gnome_vfs_async_create is deprecated and should not be used in newly-written code.

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 .

Parameters

handle_return

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

Parameters

handle_return

pointer to a pointer to a GnomeVFSHandle object.

 

uri

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 to 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 completed callback will be called with the result of the operation and callback_data .

Parameters

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 to this job in allocating threads from the thread pool.

 

callback

function to be called when the operation is complete.

 

callback_data

data to pass to 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);

gnome_vfs_async_create_as_channel is deprecated and should not be used in newly-written code.

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 .

This function has been deprecated due to behaving weirdly which suggests that it hasn't been used. See bugs 157266, 157265, 157261, 138398 in the GNOME Bugzilla. If the *_as_channel functions are needed they should be fixed and undeprecated.

Parameters

handle_return

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 mode i.e. 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 to 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);

gnome_vfs_async_create_uri_as_channel is deprecated and should not be used in newly-written code.

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

Parameters

handle_return

pointer to a pointer to a GnomeVFSHandle object.

 

uri

uri to open as a GIOChannel, creating it as necessary.

 

open_mode

open mode i.e. 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 to callback .

 

Since: 2.12


gnome_vfs_async_close ()

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

gnome_vfs_async_close is deprecated and should not be used in newly-written code.

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

Parameters

handle

async handle to close.

 

callback

function to be called when the operation is complete.

 

callback_data

data to pass to 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 .

Parameters

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

Parameters

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

Parameters

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 to 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 uri_list and return the information progressively to callback .

Parameters

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

Parameters

handle_return

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

 

uri

uri to set the file info of.

 

info

the struct containing new information about the file.

 

mask

control which fields of info are to be 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 to 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 .

Parameters

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 to this job in allocating threads from the thread pool.

 

callback

function to be called when the operation is complete.

 

callback_data

data to pass to 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 .

Parameters

handle_return

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

 

uri

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

Performs an Xfer operation in a seperate thread, otherwise like gnome_vfs_xfer_uri_list().

See GnomeVFSAsyncXferProgressCallback and GnomeVFSXferProgressCallback for details on how the callback mechanism works.

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

Do not use progress_sync_callback if you just need user feedback, because each invocation is expensive, and requires a context switch.

If you use both progress_update_callback and progress_sync_callback, the progress_sync_callback will always be invoked before the progress_update_callback. It is recommended to do conflict handling in progress_update_callback, and always return TRUE in progress_sync_callback, because if the Xfer's GnomeVFSXferProgressStatus is GNOME_VFS_XFER_PROGRESS_STATUS_OK, progress_update_callback will only be invoked if it hasn't been invoked within the last 100 milliseconds, and if progress_update_callback is not invoked, only progress_sync_callback is authoritative for the further processing, causing abortion if it is FALSE.

Parameters

handle_return

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

 

source_uri_list

A GList of source GnomeVFSURIs.

 

target_uri_list

A GList of target GnomeVFSURIs, each corresponding to one URI in source_uri_list .

 

xfer_options

GnomeVFSXferOptions defining the desired operation and parameters.

 

error_mode

A GnomeVFSErrorMode specifying how to proceed if a VFS error occurs.

 

overwrite_mode

A GnomeVFSOverwriteMode specifying how to proceed if a file is being overwritten.

 

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

A GnomeVFSAsyncXferCallback called periodically for informing the program about progress, and when the program requires responses to interactive queries (e.g. overwriting files, handling errors, etc).

 

update_callback_data

User data to pass to progress_update_callback .

 

progress_sync_callback

An optional GnomeVFSXferCallback called whenever some state changed.

 

sync_callback_data

User data to pass 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);

Used to return special directories such as Trash and Desktop from different file systems.

There is quite a complicated logic behind finding/creating a Trash directory and you need to be aware of some implications: Finding the Trash the first time when using the file method may be pretty expensive. A cache file is used to store the location of that Trash file for next time. If create_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 .

Parameters

handle_return

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

 

near_uri_list

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

 

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 to this job in allocating threads from the thread pool.

 

callback

function to be called when the operation is complete.

 

user_data

data to pass to callback .

 

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 .

Parameters

handle

handle of the file to affect.

 

operation

operation to execute.

 

operation_data

data needed to execute the operation.

 

operation_data_destroy_func

callback to destroy operation_data when its no longer needed.

 

callback

function to be called when the operation is complete.

 

callback_data

data to pass to callback .

 

Since: 2.2


gnome_vfs_find_directory_result_dup ()

GnomeVFSFindDirectoryResult *
gnome_vfs_find_directory_result_dup (GnomeVFSFindDirectoryResult *result);

Duplicates result .

Note: The internal uri is not duplicated but its refcount is incremented.

Parameters

Returns

A 1:1 copy of result .

Since: 2.12


gnome_vfs_find_directory_result_free ()

void
gnome_vfs_find_directory_result_free (GnomeVFSFindDirectoryResult *result);

Unrefs the inner uri object and frees the memory allocated for result .

Parameters

Since: 2.12

Types and Values

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.


GnomeVFSAsyncHandle

typedef struct GnomeVFSAsyncHandle GnomeVFSAsyncHandle;


GnomeVFSFindDirectoryResult

typedef struct {
	GnomeVFSURI *uri;
	GnomeVFSResult result;
} GnomeVFSFindDirectoryResult;

This structure is passed to a GnomeVFSAsyncFindDirectoryCallback by gnome_vfs_async_find_directory() and contains the information associated with a single GnomeVFSURI matching the specified find request.

Members

GnomeVFSURI *uri;

The GnomeVFSURI that was found.

 

GnomeVFSResult result;

The GnomeVFSResult that was obtained when finding uri .

 

GnomeVFSCancellation

typedef struct GnomeVFSCancellation GnomeVFSCancellation;


GnomeVFSContext

typedef struct GnomeVFSContext GnomeVFSContext;