Module Callbacks

Name

Module Callbacks -- registering for special callbacks from gnome-vfs module operations

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

Sometimes, a module operation will want to call back to the application before completing. For example, it may want to request that the application prompt the user for a username and password to access a particular URI. Or it may want to provide a status message that the application can display.

Such callbacks are handled using the module callback mechanism.

Module callbacks may be set globally for all threads, or they may be temporarilly overridden using a per-thread stack. Normally the stack is not inherited by new threads; however, async operations are run with a set of callbacks that corresponds to when the operation was tarted.

There are also special async module callbacks. Async callbacks are only invoked from async module operations, and take precedence over sync callbacks in this case, if set. They are dispatched on the main thread. Also, unlike regular callbacks, they do not need to provide the answer right away. Instead, they can arrange to have a response function called at any later time. This enables async callbacks to pop up non-modal dialogs or schedule other async work before providing a response.

Details

GnomeVFSModuleCallback ()

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

This is the type of a callback function that gets set for a module callback.

When the callback is invoked, the user function is called with an in argument, the exact type of which depends on the specific callback. It is generally a pointer to a struct with several fields that provide information to the callback.

The out argument is used to return a values from the callback. Once again the exact type depends on the specific callback. It is generally a pointer to a pre-allocated struct with several fields that the callback function should fill in before returning.

in : The in argument for this callback; the exact type depends on the specific callback
in_size : Size of the in argument; useful for sanity-checking
out : The out argument for this callback; the exact type depends on the specific callback
out_size : Size of the out argument; useful for sanity-checking
callback_data : The callback_data specified when this callback was set


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

This is the type of a callback function that gets set for an async module callback.

Such callbacks are useful when you are using the API and want callbacks to be handled from the main thread, for instance if they need to put up a dialog.

Like a GnomeVFSModuleCallback(), an async callback has in and out arguments for passing data into and out of the callback. However, an async callback does not need to fill in the out argument before returning. Instead, it can arrange to have the work done from a callback on the main loop, from another thread, etc. The response function should be called by whatever code finishes the work of the callback with response_data as an argument once the out argument is filled in and the callback is done.

The in and out arguments are guaranteed to remain valid until the response function is called.

in : The in argument for this callback; the exact type depends on the specific callback
in_size : Size of the in argument; useful for sanity-checking
out : The out argument for this callback; the exact type depends on the specific callback
out_size : Size of the out argument; useful for sanity-checking
callback_data : The callback_data specified when this callback was set
response : Response function to call when the callback is completed
response_data : Argument to pass to response


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 : The name of the module callback to set
callback : The function to call when the callback is invoked
callback_data : Pointer to pass as the callback_data argument 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 : The name of the module callback to set temporarily
callback : The function to call when the callback is invoked
callback_data : Pointer to pass as the callback_data argument 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 : The 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 : The name of the async module callback to set
callback : The function to call when the callback is invoked
callback_data : Pointer to pass as the callback_data argument 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_func 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 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 : The name of the module callback to set temporarily
callback : The function to call when the callback is invoked
callback_data : Pointer to pass as the callback_data argument 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 : The name of the module callback to remove a temporary handler for

See Also

Standard Callbacks