![]() |
![]() |
![]() |
MateVFS - Filesystem Abstraction library | ![]() |
---|---|---|---|---|
Top | Description |
Asynchronous File OperationsAsynchronous File Operations — POSIX-style file operations that run outside your main loop |
#define MATE_VFS_PRIORITY_MIN #define MATE_VFS_PRIORITY_MAX #define MATE_VFS_PRIORITY_DEFAULT typedef MateVFSAsyncHandle; void (*MateVFSAsyncCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gpointer callback_data
); void (*MateVFSAsyncOpenCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gpointer callback_data
); void (*MateVFSAsyncOpenAsChannelCallback) (MateVFSAsyncHandle *handle
,GIOChannel *channel
,MateVFSResult result
,gpointer callback_data
); void (*MateVFSAsyncCreateCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gpointer callback_data
); void (*MateVFSAsyncCreateAsChannelCallback) (MateVFSAsyncHandle *handle
,GIOChannel *channel
,MateVFSResult result
,gpointer callback_data
); void (*MateVFSAsyncCloseCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gpointer callback_data
); void (*MateVFSAsyncReadCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gpointer buffer
,MateVFSFileSize bytes_requested
,MateVFSFileSize bytes_read
,gpointer callback_data
); void (*MateVFSAsyncWriteCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gconstpointer buffer
,MateVFSFileSize bytes_requested
,MateVFSFileSize bytes_written
,gpointer callback_data
); void (*MateVFSAsyncSeekCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gpointer callback_data
); void (*MateVFSAsyncGetFileInfoCallback) (MateVFSAsyncHandle *handle
,GList *results
,gpointer callback_data
); void (*MateVFSAsyncSetFileInfoCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,MateVFSFileInfo *file_info
,gpointer callback_data
); void (*MateVFSAsyncFileControlCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gpointer operation_data
,gpointer callback_data
); void (*MateVFSAsyncDirectoryLoadCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,GList *list
,guint entries_read
,gpointer callback_data
); void (*MateVFSAsyncFindDirectoryCallback) (MateVFSAsyncHandle *handle
,GList *results
,gpointer data
); MateVFSFindDirectoryResult; gint (*MateVFSAsyncXferProgressCallback) (MateVFSAsyncHandle *handle
,MateVFSXferProgressInfo *info
,gpointer user_data
); typedef MateVFSCancellation; typedef MateVFSContext; void mate_vfs_async_set_job_limit (int limit
); int mate_vfs_async_get_job_limit (void
); void mate_vfs_async_cancel (MateVFSAsyncHandle *handle
); void mate_vfs_async_open (MateVFSAsyncHandle **handle_return
,const gchar *text_uri
,MateVFSOpenMode open_mode
,int priority
,MateVFSAsyncOpenCallback callback
,gpointer callback_data
); void mate_vfs_async_open_uri (MateVFSAsyncHandle **handle_return
,MateVFSURI *uri
,MateVFSOpenMode open_mode
,int priority
,MateVFSAsyncOpenCallback callback
,gpointer callback_data
); void mate_vfs_async_open_as_channel (MateVFSAsyncHandle **handle_return
,const gchar *text_uri
,MateVFSOpenMode open_mode
,guint advised_block_size
,int priority
,MateVFSAsyncOpenAsChannelCallback callback
,gpointer callback_data
); void mate_vfs_async_open_uri_as_channel (MateVFSAsyncHandle **handle_return
,MateVFSURI *uri
,MateVFSOpenMode open_mode
,guint advised_block_size
,int priority
,MateVFSAsyncOpenAsChannelCallback callback
,gpointer callback_data
); void mate_vfs_async_create (MateVFSAsyncHandle **handle_return
,const gchar *text_uri
,MateVFSOpenMode open_mode
,gboolean exclusive
,guint perm
,int priority
,MateVFSAsyncOpenCallback callback
,gpointer callback_data
); void mate_vfs_async_create_uri (MateVFSAsyncHandle **handle_return
,MateVFSURI *uri
,MateVFSOpenMode open_mode
,gboolean exclusive
,guint perm
,int priority
,MateVFSAsyncOpenCallback callback
,gpointer callback_data
); void mate_vfs_async_create_symbolic_link (MateVFSAsyncHandle **handle_return
,MateVFSURI *uri
,const gchar *uri_reference
,int priority
,MateVFSAsyncOpenCallback callback
,gpointer callback_data
); void mate_vfs_async_create_as_channel (MateVFSAsyncHandle **handle_return
,const gchar *text_uri
,MateVFSOpenMode open_mode
,gboolean exclusive
,guint perm
,int priority
,MateVFSAsyncCreateAsChannelCallback callback
,gpointer callback_data
); void mate_vfs_async_create_uri_as_channel (MateVFSAsyncHandle **handle_return
,MateVFSURI *uri
,MateVFSOpenMode open_mode
,gboolean exclusive
,guint perm
,int priority
,MateVFSAsyncCreateAsChannelCallback callback
,gpointer callback_data
); void mate_vfs_async_close (MateVFSAsyncHandle *handle
,MateVFSAsyncCloseCallback callback
,gpointer callback_data
); void mate_vfs_async_read (MateVFSAsyncHandle *handle
,gpointer buffer
,guint bytes
,MateVFSAsyncReadCallback callback
,gpointer callback_data
); void mate_vfs_async_write (MateVFSAsyncHandle *handle
,gconstpointer buffer
,guint bytes
,MateVFSAsyncWriteCallback callback
,gpointer callback_data
); void mate_vfs_async_seek (MateVFSAsyncHandle *handle
,MateVFSSeekPosition whence
,MateVFSFileOffset offset
,MateVFSAsyncSeekCallback callback
,gpointer callback_data
); void mate_vfs_async_get_file_info (MateVFSAsyncHandle **handle_return
,GList *uri_list
,MateVFSFileInfoOptions options
,int priority
,MateVFSAsyncGetFileInfoCallback callback
,gpointer callback_data
); void mate_vfs_async_set_file_info (MateVFSAsyncHandle **handle_return
,MateVFSURI *uri
,MateVFSFileInfo *info
,MateVFSSetFileInfoMask mask
,MateVFSFileInfoOptions options
,int priority
,MateVFSAsyncSetFileInfoCallback callback
,gpointer callback_data
); void mate_vfs_async_load_directory (MateVFSAsyncHandle **handle_return
,const gchar *text_uri
,MateVFSFileInfoOptions options
,guint items_per_notification
,int priority
,MateVFSAsyncDirectoryLoadCallback callback
,gpointer callback_data
); void mate_vfs_async_load_directory_uri (MateVFSAsyncHandle **handle_return
,MateVFSURI *uri
,MateVFSFileInfoOptions options
,guint items_per_notification
,int priority
,MateVFSAsyncDirectoryLoadCallback callback
,gpointer callback_data
); MateVFSResult mate_vfs_async_xfer (MateVFSAsyncHandle **handle_return
,GList *source_uri_list
,GList *target_uri_list
,MateVFSXferOptions xfer_options
,MateVFSXferErrorMode error_mode
,MateVFSXferOverwriteMode overwrite_mode
,int priority
,MateVFSAsyncXferProgressCallback progress_update_callback
,gpointer update_callback_data
,MateVFSXferProgressCallback progress_sync_callback
,gpointer sync_callback_data
); void mate_vfs_async_find_directory (MateVFSAsyncHandle **handle_return
,GList *near_uri_list
,MateVFSFindDirectoryKind kind
,gboolean create_if_needed
,gboolean find_if_needed
,guint permissions
,int priority
,MateVFSAsyncFindDirectoryCallback callback
,gpointer user_data
); void mate_vfs_async_file_control (MateVFSAsyncHandle *handle
,const char *operation
,gpointer operation_data
,GDestroyNotify operation_data_destroy_func
,MateVFSAsyncFileControlCallback callback
,gpointer callback_data
); MateVFSFindDirectoryResult * mate_vfs_find_directory_result_dup (MateVFSFindDirectoryResult *result
); void mate_vfs_find_directory_result_free (MateVFSFindDirectoryResult *result
);
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.
#define MATE_VFS_PRIORITY_DEFAULT 0
The default job priority. Its best to use this unless you have a reason to do otherwise.
void (*MateVFSAsyncCallback) (MateVFSAsyncHandle *handle
,MateVFSResult 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 of the operation generating the callback |
|
MATE_VFS_OK if the operation was successful, otherwise
an error code. |
|
user data defined when the callback was established |
void (*MateVFSAsyncOpenCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gpointer callback_data
);
Callback for the mate_vfs_async_open()
function,
informing the user of the result
of the operation.
|
handle of the operation generating the callback |
|
MATE_VFS_OK if the operation was successful, otherwise
an error code. |
|
user data defined when the callback was established |
void (*MateVFSAsyncOpenAsChannelCallback) (MateVFSAsyncHandle *handle
,GIOChannel *channel
,MateVFSResult result
,gpointer callback_data
);
MateVFSAsyncOpenAsChannelCallback
is deprecated and should not be used in newly-written code.
Callback for the mate_vfs_async_open_as_channel()
function,
informing the user of the result
of the operation.
|
handle of the operation generating the callback. |
|
a GIOChannel corresponding to the file opened |
|
MATE_VFS_OK if the operation was successful, otherwise
an error code. |
|
user data defined when the callback was established. |
void (*MateVFSAsyncCreateCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gpointer callback_data
);
Callback for the mate_vfs_async_create()
function,
informing the user of the result
of the operation.
|
handle of the operation generating the callback |
|
MATE_VFS_OK if the operation was successful, otherwise
an error code. |
|
user data defined when the callback was established |
void (*MateVFSAsyncCreateAsChannelCallback) (MateVFSAsyncHandle *handle
,GIOChannel *channel
,MateVFSResult result
,gpointer callback_data
);
MateVFSAsyncCreateAsChannelCallback
is deprecated and should not be used in newly-written code.
Callback for the mate_vfs_async_create_as_channel()
function,
informing the user of the result
of the operation.
|
handle of the operation generating the callback. |
|
a GIOChannel corresponding to the file created |
|
MATE_VFS_OK if the operation was successful, otherwise
an error code. |
|
user data defined when the callback was established. |
void (*MateVFSAsyncCloseCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gpointer callback_data
);
Callback for the mate_vfs_async_close()
function,
informing the user of the result
of the operation.
|
handle of the operation generating the callback |
|
MATE_VFS_OK if the operation was successful, otherwise
an error code. |
|
user data defined when the callback was established |
void (*MateVFSAsyncReadCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gpointer buffer
,MateVFSFileSize bytes_requested
,MateVFSFileSize bytes_read
,gpointer callback_data
);
Callback for the mate_vfs_async_read()
function,
informing the user of the result
of the operation.
|
handle of the operation generating the callback |
|
MATE_VFS_OK if the operation was successful, otherwise
an error code. |
|
buffer containing data read from handle . |
|
the number of bytes asked for in the call to
mate_vfs_async_read() . |
|
the number of bytes actually read from handle into buffer . |
|
user data defined when the callback was established |
void (*MateVFSAsyncWriteCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gconstpointer buffer
,MateVFSFileSize bytes_requested
,MateVFSFileSize bytes_written
,gpointer callback_data
);
Callback for the mate_vfs_async_write()
function,
informing the user of the result
of the operation.
|
handle of the operation generating the callback |
|
MATE_VFS_OK if the operation was successful, otherwise
an error code. |
|
buffer containing data written to handle . |
|
the number of bytes asked to write in the call to
mate_vfs_async_write() . |
|
the number of bytes actually written to handle from buffer . |
|
user data defined when the callback was established. |
void (*MateVFSAsyncSeekCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gpointer callback_data
);
Callback for the mate_vfs_async_seek()
function,
informing the user of the result
of the operation.
|
handle of the operation generating the callback |
|
MATE_VFS_OK if the operation was successful, otherwise
an error code. |
|
user data defined when the callback was established. |
void (*MateVFSAsyncGetFileInfoCallback) (MateVFSAsyncHandle *handle
,GList *results
,gpointer callback_data
);
Callback for the mate_vfs_async_get_file_info()
function,
informing the user of the results
of the operation.
|
handle of the operation generating the callback |
|
GList of MateVFSFileInfoResult * items representing
the success of each mate_vfs_get_file_info() and the data retrieved. |
|
user data defined when the callback was established. |
void (*MateVFSAsyncSetFileInfoCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,MateVFSFileInfo *file_info
,gpointer callback_data
);
Callback for the mate_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 MateVFSFileInfoOptions passed here are those used
for the returned file info; they are not used when setting.
|
handle of the operation generating the callback |
|
MATE_VFS_OK if the operation was successful, otherwise a
MateVFSResult error code. |
|
if result is MATE_VFS_OK , a MateVFSFileInfo struct containing
information about the file. |
|
user data defined when the callback was established |
void (*MateVFSAsyncFileControlCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,gpointer operation_data
,gpointer callback_data
);
Callback for the mate_vfs_async_find_directory()
function.
informing the user of the result
of the operation, and
providing the requested operation_data
.
|
handle of the operation generating the callback |
|
MATE_VFS_OK if the operation was successful, otherwise a
MateVFSResult error code. |
|
The data requested from the module if result
is MATE_VFS_OK . |
|
User data defined when the operation was established. |
void (*MateVFSAsyncDirectoryLoadCallback) (MateVFSAsyncHandle *handle
,MateVFSResult result
,GList *list
,guint entries_read
,gpointer callback_data
);
Callback for the mate_vfs_async_directory_load()
function.
informing the user of the result
of the operation and
providing a file list
if the result
is MATE_VFS_OK
.
|
handle of the operation generating the callback. |
|
MATE_VFS_OK if the operation was sucessful,
MATE_VFS_ERROR_EOF if the last file in the directory
has been read, otherwise a MateVFSResult error code |
|
a GList of MateVFSFileInfo structs representing information about the files just loaded. |
|
number of entries read from handle for this instance of
the callback. |
|
user data defined when the callback was established. |
void (*MateVFSAsyncFindDirectoryCallback) (MateVFSAsyncHandle *handle
,GList *results
,gpointer data
);
Callback for the mate_vfs_async_find_directory()
function,
informing the user of the results
of the operation.
|
handle of the operation generating the callback |
|
GList of MateVFSFindDirectoryResult *s containing special directories matching the find criteria. |
|
user data defined when the operation was established |
typedef struct { MateVFSURI *uri; MateVFSResult result; } MateVFSFindDirectoryResult;
This structure is passed to a MateVFSAsyncFindDirectoryCallback
by mate_vfs_async_find_directory()
and contains the information
associated with a single MateVFSURI matching the specified
find request.
MateVFSURI * |
The MateVFSURI that was found. |
MateVFSResult |
The MateVFSResult that was obtained when finding uri . |
gint (*MateVFSAsyncXferProgressCallback) (MateVFSAsyncHandle *handle
,MateVFSXferProgressInfo *info
,gpointer user_data
);
This callback is passed to mate_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 MATE_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 MATE_VFS_XFER_PROGRESS_STATUS_OK
.
Either way, it acts like MateVFSXferProgressCallback
would act in non-asynchronous mode. The differences in
invocation are explained in the mate_vfs_async_xfer()
documentation.
|
Handle of the Xfer operation generating the callback. |
|
Information on the current progress in the transfer. |
|
The user data that was passed to mate_vfs_async_xfer() . |
Returns : |
gint depending on the MateVFSXferProgressInfo.
Please consult MateVFSXferProgressCallback for details. |
void mate_vfs_async_set_job_limit (int limit
);
Restrict the number of worker threads used by async operations
to limit
.
|
maximum number of allowable threads. |
int mate_vfs_async_get_job_limit (void
);
Get the current maximum allowable number of worker threads for async operations.
Returns : |
current maximum number of threads. |
void mate_vfs_async_cancel (MateVFSAsyncHandle *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 mate_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.
|
handle of the async operation to be cancelled. |
void mate_vfs_async_open (MateVFSAsyncHandle **handle_return
,const gchar *text_uri
,MateVFSOpenMode open_mode
,int priority
,MateVFSAsyncOpenCallback 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 MateVFSResult.
|
pointer to a pointer to a MateVFSHandle object. |
|
string of the uri to open. |
|
open mode. |
|
a value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign to this job
in allocating threads from the thread pool. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_open_uri (MateVFSAsyncHandle **handle_return
,MateVFSURI *uri
,MateVFSOpenMode open_mode
,int priority
,MateVFSAsyncOpenCallback 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 MateVFSResult.
|
pointer to a pointer to a MateVFSHandle object. |
|
uri to open. |
|
open mode. |
|
a value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign to this job
in allocating threads from the thread pool. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_open_as_channel (MateVFSAsyncHandle **handle_return
,const gchar *text_uri
,MateVFSOpenMode open_mode
,guint advised_block_size
,int priority
,MateVFSAsyncOpenAsChannelCallback callback
,gpointer callback_data
);
mate_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 MATE_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 MATE Bugzilla. If the *_as_channel functions are needed they should be fixed and undeprecated.
|
pointer to a pointer to a MateVFSHandle object. |
|
string of the uri to open as a GIOChannel. |
|
open mode i.e. for reading, writing, random, etc. |
|
the preferred block size for GIOChannel to read. |
|
a value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign this job
in allocating threads from the thread pool. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_open_uri_as_channel (MateVFSAsyncHandle **handle_return
,MateVFSURI *uri
,MateVFSOpenMode open_mode
,guint advised_block_size
,int priority
,MateVFSAsyncOpenAsChannelCallback callback
,gpointer callback_data
);
mate_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 MATE 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 MATE_VFS_OK
, a reference to a GIOChannel pointing
at uri
in open_mode
.
|
pointer to a pointer to a MateVFSHandle object. |
|
uri to open as a GIOChannel. |
|
open mode i.e. for reading, writing, random, etc. |
|
the preferred block size for GIOChannel to read. |
|
a value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign this job
in allocating threads from the thread pool. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_create (MateVFSAsyncHandle **handle_return
,const gchar *text_uri
,MateVFSOpenMode open_mode
,gboolean exclusive
,guint perm
,int priority
,MateVFSAsyncOpenCallback 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
.
|
pointer to a pointer to a MateVFSHandle object. |
|
string representing the uri to create. |
|
mode to leave the file opened in after creation (or MATE_VFS_OPEN_MODE_NONE
to leave the file closed after creation). |
|
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. |
|
bitmap representing the permissions for the newly created file (Unix style). |
|
a value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign this job
in allocating threads from the thread pool. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_create_uri (MateVFSAsyncHandle **handle_return
,MateVFSURI *uri
,MateVFSOpenMode open_mode
,gboolean exclusive
,guint perm
,int priority
,MateVFSAsyncOpenCallback 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
.
|
pointer to a pointer to a MateVFSHandle object. |
|
uri to create a file at. |
|
mode to leave the file opened in after creation (or MATE_VFS_OPEN_MODE_NONE
to leave the file closed after creation). |
|
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. |
|
bitmap representing the permissions for the newly created file (Unix style). |
|
a value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign this job
in allocating threads from the thread pool. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_create_symbolic_link (MateVFSAsyncHandle **handle_return
,MateVFSURI *uri
,const gchar *uri_reference
,int priority
,MateVFSAsyncOpenCallback 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
.
|
when the function returns, will point to a handle for the async operation. |
|
location to create the link at. |
|
location to point uri to (can be a uri fragment, i.e. relative). |
|
a value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign to this job
in allocating threads from the thread pool. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_create_as_channel (MateVFSAsyncHandle **handle_return
,const gchar *text_uri
,MateVFSOpenMode open_mode
,gboolean exclusive
,guint perm
,int priority
,MateVFSAsyncCreateAsChannelCallback callback
,gpointer callback_data
);
mate_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 MATE_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 MATE Bugzilla. If the *_as_channel functions are needed they should be fixed and undeprecated.
|
pointer to a pointer to a MateVFSHandle object. |
|
string of the uri to open as a GIOChannel, creating it as necessary. |
|
open mode i.e. for reading, writing, random, etc. |
|
replace the file if it already exists. |
|
standard POSIX-style permissions bitmask, permissions of created file. |
|
a value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign this job
in allocating threads from the thread pool. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_create_uri_as_channel (MateVFSAsyncHandle **handle_return
,MateVFSURI *uri
,MateVFSOpenMode open_mode
,gboolean exclusive
,guint perm
,int priority
,MateVFSAsyncCreateAsChannelCallback callback
,gpointer callback_data
);
mate_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 MATE_VFS_OK
, a reference to a GIOChannel pointing
at text_uri
in open_mode
.
|
pointer to a pointer to a MateVFSHandle object. |
|
uri to open as a GIOChannel, creating it as necessary. |
|
open mode i.e. for reading, writing, random, etc. |
|
replace the file if it already exists. |
|
standard POSIX-style permissions bitmask, permissions of created file. |
|
a value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign this job
in allocating threads from the thread pool. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
Since 2.12
void mate_vfs_async_close (MateVFSAsyncHandle *handle
,MateVFSAsyncCloseCallback callback
,gpointer callback_data
);
Close handle
opened with mate_vfs_async_open()
. When the close
has completed, callback
will be called with callback_data
and
the result of the operation.
|
async handle to close. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_read (MateVFSAsyncHandle *handle
,gpointer buffer
,guint bytes
,MateVFSAsyncReadCallback 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 for the file to be read. |
|
allocated block of memory to read into. |
|
number of bytes to read. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_write (MateVFSAsyncHandle *handle
,gconstpointer buffer
,guint bytes
,MateVFSAsyncWriteCallback 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 for the file to be written. |
|
block of memory containing data to be written. |
|
number of bytes to write. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_seek (MateVFSAsyncHandle *handle
,MateVFSSeekPosition whence
,MateVFSFileOffset offset
,MateVFSAsyncSeekCallback 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 for which the current position must be changed. |
|
integer value representing the starting position. |
|
number of bytes to skip from the position specified by whence .
(a positive value means to move forward; a negative one to move backwards). |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_get_file_info (MateVFSAsyncHandle **handle_return
,GList *uri_list
,MateVFSFileInfoOptions options
,int priority
,MateVFSAsyncGetFileInfoCallback callback
,gpointer callback_data
);
Fetch information about the files indicated in uri_list
and return the
information progressively to callback
.
|
when the function returns, will point to a handle for the async operation. |
|
a GList of MateVFSURIs to fetch information about. |
|
packed boolean type providing control over various details of the get_file_info operation. |
|
a value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign this job
in allocating threads from the thread pool. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_set_file_info (MateVFSAsyncHandle **handle_return
,MateVFSURI *uri
,MateVFSFileInfo *info
,MateVFSSetFileInfoMask mask
,MateVFSFileInfoOptions options
,int priority
,MateVFSAsyncSetFileInfoCallback callback
,gpointer callback_data
);
Set file info details about the file at uri
, such as permissions, name,
owner, and modification time.
|
when the function returns, will point to a handle for the async operation. |
|
uri to set the file info of. |
|
the struct containing new information about the file. |
|
control which fields of info are to be changed about the file at uri . |
|
packed boolean type providing control over various details of the set_file_info operation. |
|
a value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign this job
in allocating threads from the thread pool. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_load_directory (MateVFSAsyncHandle **handle_return
,const gchar *text_uri
,MateVFSFileInfoOptions options
,guint items_per_notification
,int priority
,MateVFSAsyncDirectoryLoadCallback callback
,gpointer callback_data
);
Read the contents of the directory at text_uri
, passing back MateVFSFileInfo
structs about each file in the directory to callback
. items_per_notification
files will be processed between each call to callback
.
|
when the function returns, will point to a handle for the async operation. |
|
string representing the uri of the directory to be loaded. |
|
packed boolean type providing control over various details of the get_file_info operation. |
|
number of files to process in a row before calling callback
|
|
a value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign to this job
in allocating threads from the thread pool. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_load_directory_uri (MateVFSAsyncHandle **handle_return
,MateVFSURI *uri
,MateVFSFileInfoOptions options
,guint items_per_notification
,int priority
,MateVFSAsyncDirectoryLoadCallback callback
,gpointer callback_data
);
Read the contents of the directory at uri
, passing back MateVFSFileInfo structs
about each file in the directory to callback
. items_per_notification
files will be processed between each call to callback
.
|
when the function returns, will point to a handle for the async operation. |
|
uri of the directory to be loaded. |
|
packed boolean type providing control over various details of the get_file_info operation. |
|
number of files to process in a row before calling callback
|
|
a value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign this job
in allocating threads from the thread pool. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
MateVFSResult mate_vfs_async_xfer (MateVFSAsyncHandle **handle_return
,GList *source_uri_list
,GList *target_uri_list
,MateVFSXferOptions xfer_options
,MateVFSXferErrorMode error_mode
,MateVFSXferOverwriteMode overwrite_mode
,int priority
,MateVFSAsyncXferProgressCallback progress_update_callback
,gpointer update_callback_data
,MateVFSXferProgressCallback progress_sync_callback
,gpointer sync_callback_data
);
Performs an Xfer operation in a seperate thread, otherwise like
mate_vfs_xfer_uri_list()
.
See MateVFSAsyncXferProgressCallback and MateVFSXferProgressCallback 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 Caja 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
MateVFSXferProgressStatus is MATE_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
.
|
when the function returns, will point to a handle for the operation. |
|
A GList of source MateVFSURIs. |
|
A GList of target MateVFSURIs, each corresponding to one URI in
source_uri_list . |
|
MateVFSXferOptions defining the desired operation and parameters. |
|
A MateVFSErrorMode specifying how to proceed if a VFS error occurs. |
|
A MateVFSOverwriteMode specifying how to proceed if a file is being overwritten. |
|
A value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign this job
in allocating threads from the thread pool. |
|
A MateVFSAsyncXferCallback called periodically for informing the program about progress, and when the program requires responses to interactive queries (e.g. overwriting files, handling errors, etc). |
|
User data to pass to progress_update_callback . |
|
An optional MateVFSXferCallback called whenever some state changed. |
|
User data to pass to progress_sync_callback . |
Returns : |
MATE_VFS_OK if the paramaters were in order,
or MATE_VFS_ERROR_BAD_PARAMETERS if something was wrong in the passed in arguments. |
void mate_vfs_async_find_directory (MateVFSAsyncHandle **handle_return
,GList *near_uri_list
,MateVFSFindDirectoryKind kind
,gboolean create_if_needed
,gboolean find_if_needed
,guint permissions
,int priority
,MateVFSAsyncFindDirectoryCallback 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 mate_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
.
|
when the function returns, will point to a handle for the operation. |
|
a GList of MateVFSURIs, find a special directory on the same
volume as near_uri_list . |
|
kind of special directory. |
|
if directory we are looking for does not exist, try to create it. |
|
if we don't know where the directory is yet, look for it. |
|
if creating, use these permissions. |
|
a value from MATE_VFS_PRIORITY_MIN to MATE_VFS_PRIORITY_MAX (normally
should be MATE_VFS_PRIORITY_DEFAULT ) indicating the priority to assign to this job
in allocating threads from the thread pool. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
void mate_vfs_async_file_control (MateVFSAsyncHandle *handle
,const char *operation
,gpointer operation_data
,GDestroyNotify operation_data_destroy_func
,MateVFSAsyncFileControlCallback 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 mate-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 of the file to affect. |
|
operation to execute. |
|
data needed to execute the operation. |
|
callback to destroy operation_data when its no longer needed. |
|
function to be called when the operation is complete. |
|
data to pass to callback . |
Since 2.2
MateVFSFindDirectoryResult * mate_vfs_find_directory_result_dup
(MateVFSFindDirectoryResult *result
);
Duplicates result
.
Note: The internal uri is not duplicated but its refcount is incremented.
|
a MateVFSFindDirectoryResult. |
Returns : |
A 1:1 copy of result . |
Since 2.12
void mate_vfs_find_directory_result_free (MateVFSFindDirectoryResult *result
);
Unrefs the inner uri object and frees the memory
allocated for result
.
|
a MateVFSFindDirectoryResult. |
Since 2.12