## gnome-vfs-module-callback

gnome-vfs-module-callback — functions used by apps if they want to answer to callback invocations by gnome-vfs modules

## Synopsis

    void                (*GnomeVFSModuleCallback)           (gconstpointer in,
                                                             gsize in_size,
                                                             gpointer out,
                                                             gsize out_size,
                                                             gpointer callback_data);
    void                (*GnomeVFSModuleCallbackResponse)   (gpointer response_data);
    void                (*GnomeVFSAsyncModuleCallback)      (gconstpointer in,
                                                             gsize in_size,
                                                             gpointer out,
                                                             gsize out_size,
                                                             gpointer callback_data,
                                                             GnomeVFSModuleCallbackResponse response,
                                                             gpointer response_data);
    void                gnome_vfs_module_callback_set_default
                                                            (const char *callback_name,
                                                             GnomeVFSModuleCallback callback,
                                                             gpointer callback_data,
                                                             GDestroyNotify destroy_notify);
    void                gnome_vfs_module_callback_push      (const char *callback_name,
                                                             GnomeVFSModuleCallback callback,
                                                             gpointer callback_data,
                                                             GDestroyNotify destroy_notify);
    void                gnome_vfs_module_callback_pop       (const char *callback_name);
    void                gnome_vfs_async_module_callback_set_default
                                                            (const char *callback_name,
                                                             GnomeVFSAsyncModuleCallback callback,
                                                             gpointer callback_data,
                                                             GDestroyNotify destroy_notify);
    void                gnome_vfs_async_module_callback_push
                                                            (const char *callback_name,
                                                             GnomeVFSAsyncModuleCallback callback,
                                                             gpointer callback_data,
                                                             GDestroyNotify destroy_notify);
    void                gnome_vfs_async_module_callback_pop (const char *callback_name);

## Description

## Details

### GnomeVFSModuleCallback ()

    void                (*GnomeVFSModuleCallback)           (gconstpointer in,
                                                             gsize in_size,
                                                             gpointer out,
                                                             gsize out_size,
                                                             gpointer callback_data);

Modules use a GnomeVFSModuleCallback to send data to client applications and request data from them synchronously.

The format of `in` and `out` is determined by the callback name.

`in` : | data passed from module to application.
`in_size` : | size of `in` bytes.
`out` : | data passed from application to module.
`out_size` : | size of `out` in bytes.
`callback_data` : | user data passed when connecting the callback.

### GnomeVFSModuleCallbackResponse ()

    void                (*GnomeVFSModuleCallbackResponse)   (gpointer response_data);

This is the type of the response function passed to a `GnomeVFSAsyncModuleCallback()`. It should be called when the async callback has completed.

`response_data` : | pass the response data argument originally passed to the async callback.

### GnomeVFSAsyncModuleCallback ()

    void                (*GnomeVFSAsyncModuleCallback)      (gconstpointer in,
                                                             gsize in_size,
                                                             gpointer out,
                                                             gsize out_size,
                                                             gpointer callback_data,
                                                             GnomeVFSModuleCallbackResponse response,
                                                             gpointer response_data);

Modules use a GnomeVFSModuleCallback to send data to client applications and request data from them asynchronously.

The application is expected to invoke the `response` with `response_data` when it is able to satisfy the request.

The format of `in` and `out` is determined by the callback name.

`in` : | data passed from module to application.
`in_size` : | size of `in` bytes.
`out` : | data passed from application to module.
`out_size` : | size of `out` in bytes.
`callback_data` : | user data passed when connecting the callback.
`response` : | GnomeVFSModuleCallbackResponse that must be invoked when the request is satisfied.
`response_data` : | data that must be passed to `response` when the request is satisfied.

### gnome_vfs_module_callback_set_default ()

    void                gnome_vfs_module_callback_set_default
                                                            (const char *callback_name,
                                                             GnomeVFSModuleCallback callback,
                                                             gpointer callback_data,
                                                             GDestroyNotify destroy_notify);

Set the default callback for `callback_name` to `callback`. `callback` will be called with `callback_data` on the same thread as the gnome-vfs operation that invokes it. The default value is shared for all threads, but setting it is thread-safe.

Use this function if you want to set a handler to be used by your whole application. You can use `gnome_vfs_module_callback_push()` to set a callback function that will temporarily override the default on the current thread instead. Or you can also use `gnome_vfs_async_module_callback_set_default()` to set an async callback function.

Note: `destroy_notify` may be called on any thread - it is not guaranteed to be called on the main thread.

`callback_name` : | name of the module callback to set.
`callback` : | function to call when the `callback` is invoked.
`callback_data` : | data to pass to `callback`.
`destroy_notify` : | function to call when `callback_data` is to be freed.

### gnome_vfs_module_callback_push ()

    void                gnome_vfs_module_callback_push      (const char *callback_name,
                                                             GnomeVFSModuleCallback callback,
                                                             gpointer callback_data,
                                                             GDestroyNotify destroy_notify);

Set `callback` as a temprary handler for `callback_name`. `callback` will be called with `callback_data` on the same thread as the gnome-vfs operation that invokes it. The temporary handler is set per-thread.

`gnome_vfs_module_callback_pop()` removes the most recently set temporary handler. The temporary handlers are treated as a first-in first-out stack.

Use this function to set a temporary callback handler for a single call or a few calls. You can use `gnome_vfs_module_callback_set_default()` to set a callback function that will establish a permanent global setting for all threads instead.

Note: `destroy_notify` may be called on any thread - it is not guaranteed to be called on the main thread.

`callback_name` : | name of the module callback to set temporarily.
`callback` : | function to call when the `callback` is invoked.
`callback_data` : | data to pass to `callback`.
`destroy_notify` : | function to call when `callback_data` is to be freed.

### gnome_vfs_module_callback_pop ()

    void                gnome_vfs_module_callback_pop       (const char *callback_name);

Remove the temporary handler for `callback_name` most recently set with `gnome_vfs_module_callback_push()`. If another temporary handler was previously set on the same thread, it becomes the current handler. Otherwise, the default handler, if any, becomes current.

The temporary handlers are treated as a first-in first-out stack.

`callback_name` : | name of the module callback to remove a temporary handler for.

### gnome_vfs_async_module_callback_set_default ()

    void                gnome_vfs_async_module_callback_set_default
                                                            (const char *callback_name,
                                                             GnomeVFSAsyncModuleCallback callback,
                                                             gpointer callback_data,
                                                             GDestroyNotify destroy_notify);

Set the default async callback for `callback_name` to `callback`. `callback` will be called with `callback_data` from a callback on the main thread. It will be passed a response function which should be called to signal completion of the callback. The callback function itself may return in the meantime.

The default value is shared for all threads, but setting it is thread-safe.

Use this function if you want to globally set a callback handler for use with async operations.

You can use `gnome_vfs_async_module_callback_push()` to set an async callback function that will temporarily override the default on the current thread instead. Or you can also use `gnome_vfs_module_callback_set_default()` to set a regular callback function.

Note: `destroy_notify` may be called on any thread - it is not guaranteed to be called on the main thread.

`callback_name` : | name of the async module callback to set.
`callback` : | function to call when `callback` is invoked.
`callback_data` : | data to pass to `callback`.
`destroy_notify` : | function to call when `callback_data` is to be freed.

### gnome_vfs_async_module_callback_push ()

    void                gnome_vfs_async_module_callback_push
                                                            (const char *callback_name,
                                                             GnomeVFSAsyncModuleCallback callback,
                                                             gpointer callback_data,
                                                             GDestroyNotify destroy_notify);

Set `callback` as a temprary async handler for `callback_name`. `callback` will be called with `callback_data` from a callback on the main thread. It will be passed a response function which should be called to signal completion of the callback. The callback function itself may return in the meantime.

The temporary async handler is set per-thread.

`gnome_vfs_async_module_callback_pop()` removes the most recently set temporary handler. The temporary async handlers are treated as a first-in first-out stack.

Use this function to set a temporary async callback handler for a single call or a few calls. You can use `gnome_vfs_async_module_callback_set_default()` to set an async callback function that will establish a permanent global setting for all threads instead.

Note: `destroy_notify` may be called on any thread - it is not guaranteed to be called on the main thread.

`callback_name` : | name of the module callback to set temporarily.
`callback` : | function to call when `callback` is invoked.
`callback_data` : | data to pass to `callback`.
`destroy_notify` : | function to call when `callback_data` is to be freed.

### gnome_vfs_async_module_callback_pop ()

    void                gnome_vfs_async_module_callback_pop (const char *callback_name);

Remove the temporary async handler for `callback_name` most recently set with `gnome_vfs_async_module_callback_push()`. If another temporary async handler was previously set on the same thread, it becomes the current handler. Otherwise, the default async handler, if any, becomes current.

The temporary async handlers are treated as a first-in first-out stack.

`callback_name` : | name of the module callback to remove a temporary handler for.