<refentry id="gnome-vfs-20-gnome-vfs-module-callback">
<refmeta>
<refentrytitle id="top_of_page">gnome-vfs-module-callback</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GNOME-VFS-2.0 Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>gnome-vfs-module-callback</refname>
<refpurpose>functions used by apps if they want to answer to callback invocations by gnome-vfs modules</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="synopsis">
<title id="synopsis.title">Synopsis</title>

<synopsis>



<link linkend="void">void</link>        (<link linkend="GnomeVFSModuleCallback">*GnomeVFSModuleCallback</link>)       (<link linkend="gconstpointer">gconstpointer</link> in,
                                             <link linkend="gsize">gsize</link> in_size,
                                             <link linkend="gpointer">gpointer</link> out,
                                             <link linkend="gsize">gsize</link> out_size,
                                             <link linkend="gpointer">gpointer</link> callback_data);
<link linkend="void">void</link>        (<link linkend="GnomeVFSModuleCallbackResponse">*GnomeVFSModuleCallbackResponse</link>)
                                            (<link linkend="gpointer">gpointer</link> response_data);
<link linkend="void">void</link>        (<link linkend="GnomeVFSAsyncModuleCallback">*GnomeVFSAsyncModuleCallback</link>)  (<link linkend="gconstpointer">gconstpointer</link> in,
                                             <link linkend="gsize">gsize</link> in_size,
                                             <link linkend="gpointer">gpointer</link> out,
                                             <link linkend="gsize">gsize</link> out_size,
                                             <link linkend="gpointer">gpointer</link> callback_data,
                                             <link linkend="GnomeVFSModuleCallbackResponse">GnomeVFSModuleCallbackResponse</link> response,
                                             <link linkend="gpointer">gpointer</link> response_data);
<link linkend="void">void</link>        <link linkend="gnome-vfs-module-callback-set-default">gnome_vfs_module_callback_set_default</link>
                                            (const <link linkend="char">char</link> *callback_name,
                                             <link linkend="GnomeVFSModuleCallback">GnomeVFSModuleCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> callback_data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_notify);
<link linkend="void">void</link>        <link linkend="gnome-vfs-module-callback-push">gnome_vfs_module_callback_push</link>  (const <link linkend="char">char</link> *callback_name,
                                             <link linkend="GnomeVFSModuleCallback">GnomeVFSModuleCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> callback_data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_notify);
<link linkend="void">void</link>        <link linkend="gnome-vfs-module-callback-pop">gnome_vfs_module_callback_pop</link>   (const <link linkend="char">char</link> *callback_name);
<link linkend="void">void</link>        <link linkend="gnome-vfs-async-module-callback-set-default">gnome_vfs_async_module_callback_set_default</link>
                                            (const <link linkend="char">char</link> *callback_name,
                                             <link linkend="GnomeVFSAsyncModuleCallback">GnomeVFSAsyncModuleCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> callback_data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_notify);
<link linkend="void">void</link>        <link linkend="gnome-vfs-async-module-callback-push">gnome_vfs_async_module_callback_push</link>
                                            (const <link linkend="char">char</link> *callback_name,
                                             <link linkend="GnomeVFSAsyncModuleCallback">GnomeVFSAsyncModuleCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> callback_data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_notify);
<link linkend="void">void</link>        <link linkend="gnome-vfs-async-module-callback-pop">gnome_vfs_async_module_callback_pop</link>
                                            (const <link linkend="char">char</link> *callback_name);
</synopsis>
</refsynopsisdiv>









<refsect1 id="desc">
<title id="desc.title">Description</title>
<para>

</para>
</refsect1>

<refsect1 id="details">
<title id="details.title">Details</title>
<refsect2>
<title><anchor id="GnomeVFSModuleCallback" role="function"/>GnomeVFSModuleCallback ()</title>
<indexterm><primary>GnomeVFSModuleCallback</primary></indexterm><programlisting><link linkend="void">void</link>        (*GnomeVFSModuleCallback)       (<link linkend="gconstpointer">gconstpointer</link> in,
                                             <link linkend="gsize">gsize</link> in_size,
                                             <link linkend="gpointer">gpointer</link> out,
                                             <link linkend="gsize">gsize</link> out_size,
                                             <link linkend="gpointer">gpointer</link> callback_data);</programlisting>
<para>
This is the type of a callback function that gets set for a module
callback. 
</para>
<para>
When the callback is invoked, the user function is called with an
<parameter>in</parameter> 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.
</para>
<para>
The <parameter>out</parameter> argument is used to return a value 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.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>in</parameter>&nbsp;:</term>
<listitem><simpara> in argument for this callback; the exact type depends on the specific callback.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>in_size</parameter>&nbsp;:</term>
<listitem><simpara> size of the in argument; useful for sanity-checking.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>out</parameter>&nbsp;:</term>
<listitem><simpara> out argument for this callback; the exact type depends on the specific callback.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>out_size</parameter>&nbsp;:</term>
<listitem><simpara> size of the out argument; useful for sanity-checking.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
<listitem><simpara> callback data specified when this callback was set.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GnomeVFSModuleCallbackResponse" role="function"/>GnomeVFSModuleCallbackResponse ()</title>
<indexterm><primary>GnomeVFSModuleCallbackResponse</primary></indexterm><programlisting><link linkend="void">void</link>        (*GnomeVFSModuleCallbackResponse)
                                            (<link linkend="gpointer">gpointer</link> response_data);</programlisting>
<para>
This is the type of the response function passed to a
<link linkend="GnomeVFSAsyncModuleCallback"><function>GnomeVFSAsyncModuleCallback()</function></link>. It should be called when the async
callback has completed.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>response_data</parameter>&nbsp;:</term>
<listitem><simpara> pass the response data argument originally passed to the async callback.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GnomeVFSAsyncModuleCallback" role="function"/>GnomeVFSAsyncModuleCallback ()</title>
<indexterm><primary>GnomeVFSAsyncModuleCallback</primary></indexterm><programlisting><link linkend="void">void</link>        (*GnomeVFSAsyncModuleCallback)  (<link linkend="gconstpointer">gconstpointer</link> in,
                                             <link linkend="gsize">gsize</link> in_size,
                                             <link linkend="gpointer">gpointer</link> out,
                                             <link linkend="gsize">gsize</link> out_size,
                                             <link linkend="gpointer">gpointer</link> callback_data,
                                             <link linkend="GnomeVFSModuleCallbackResponse">GnomeVFSModuleCallbackResponse</link> response,
                                             <link linkend="gpointer">gpointer</link> response_data);</programlisting>
<para>
This is the type of a callback function that gets set for an async
module callback. 
</para>
<para>
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.
</para>
<para>
Like a <link linkend="GnomeVFSModuleCallback"><function>GnomeVFSModuleCallback()</function></link>, an async callback has <parameter>in</parameter> and <parameter>out</parameter>
arguments for passing data into and out of the callback. However,
an async callback does not need to fill in the <parameter>out</parameter> argument before
returning. Instead, it can arrange to have the work done from a
callback on the main loop, from another thread, etc. The <parameter>response</parameter>
function should be called by whatever code finishes the work of the
callback with <parameter>response_data</parameter> as an argument once the <parameter>out</parameter> argument
is filled in and the callback is done.
</para>
<para>
The <parameter>in</parameter> and <parameter>out</parameter> arguments are guaranteed to remain valid until the
<parameter>response</parameter> function is called.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>in</parameter>&nbsp;:</term>
<listitem><simpara> in argument for this callback; the exact type depends on the specific callback.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>in_size</parameter>&nbsp;:</term>
<listitem><simpara> size of the in argument; useful for sanity-checking.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>out</parameter>&nbsp;:</term>
<listitem><simpara> out argument for this callback; the exact type depends on the specific callback.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>out_size</parameter>&nbsp;:</term>
<listitem><simpara> size of the out argument; useful for sanity-checking.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
<listitem><simpara> The <parameter>callback_data</parameter> specified when this callback was set.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>response</parameter>&nbsp;:</term>
<listitem><simpara> response function to call when the callback is completed.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>response_data</parameter>&nbsp;:</term>
<listitem><simpara> argument to pass to <parameter>response</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-module-callback-set-default" role="function"/>gnome_vfs_module_callback_set_default ()</title>
<indexterm><primary>gnome_vfs_module_callback_set_default</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_module_callback_set_default
                                            (const <link linkend="char">char</link> *callback_name,
                                             <link linkend="GnomeVFSModuleCallback">GnomeVFSModuleCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> callback_data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_notify);</programlisting>
<para>
Set the default callback for <parameter>callback_name</parameter> to
<parameter>callback</parameter>. <parameter>callback</parameter> will be called with <parameter>callback_data</parameter> 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.
</para>
<para>
Use this function if you want to set a handler to be used by your
whole application. You can use <link linkend="gnome-vfs-module-callback-push"><function>gnome_vfs_module_callback_push()</function></link> to
set a callback function that will temporarily override the default
on the current thread instead. Or you can also use
<link linkend="gnome-vfs-async-module-callback-set-default"><function>gnome_vfs_async_module_callback_set_default()</function></link> to set an async
callback function.
</para>
<para>
Note: <parameter>destroy_notify</parameter> may be called on any thread - it is not
guaranteed to be called on the main thread.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>callback_name</parameter>&nbsp;:</term>
<listitem><simpara> name of the module callback to set.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
<listitem><simpara> function to call when the <parameter>callback</parameter> is invoked.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
<listitem><simpara> data to pass to <parameter>callback</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy_notify</parameter>&nbsp;:</term>
<listitem><simpara> function to call when <parameter>callback_data</parameter> is to be freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-module-callback-push" role="function"/>gnome_vfs_module_callback_push ()</title>
<indexterm><primary>gnome_vfs_module_callback_push</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_module_callback_push  (const <link linkend="char">char</link> *callback_name,
                                             <link linkend="GnomeVFSModuleCallback">GnomeVFSModuleCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> callback_data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_notify);</programlisting>
<para>
Set <parameter>callback</parameter> as a temprary handler for <parameter>callback_name</parameter>. <parameter>callback</parameter>
will be called with <parameter>callback_data</parameter> on the same thread as the
gnome-vfs operation that invokes it. The temporary handler is set
per-thread.
</para>
<para>
<link linkend="gnome-vfs-module-callback-pop"><function>gnome_vfs_module_callback_pop()</function></link> removes the most recently set
temporary handler. The temporary handlers are treated as a first-in
first-out stack.
</para>
<para>
Use this function to set a temporary callback handler for a single
call or a few calls. You can use
<link linkend="gnome-vfs-module-callback-set-default"><function>gnome_vfs_module_callback_set_default()</function></link> to set a callback function
that will establish a permanent global setting for all threads
instead.
</para>
<para>
Note: <parameter>destroy_notify</parameter> may be called on any thread - it is not
guaranteed to be called on the main thread.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>callback_name</parameter>&nbsp;:</term>
<listitem><simpara> name of the module callback to set temporarily.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
<listitem><simpara> function to call when the <parameter>callback</parameter> is invoked.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
<listitem><simpara> data to pass to <parameter>callback</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy_notify</parameter>&nbsp;:</term>
<listitem><simpara> function to call when <parameter>callback_data</parameter> is to be freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-module-callback-pop" role="function"/>gnome_vfs_module_callback_pop ()</title>
<indexterm><primary>gnome_vfs_module_callback_pop</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_module_callback_pop   (const <link linkend="char">char</link> *callback_name);</programlisting>
<para>
Remove the temporary handler for <parameter>callback_name</parameter> most recently set
with <link linkend="gnome-vfs-module-callback-push"><function>gnome_vfs_module_callback_push()</function></link>.  If another temporary
handler was previously set on the same thread, it becomes the
current handler. Otherwise, the default handler, if any, becomes
current. 
</para>
<para>
The temporary handlers are treated as a first-in first-out
stack.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>callback_name</parameter>&nbsp;:</term>
<listitem><simpara> name of the module callback to remove a temporary handler for.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-async-module-callback-set-default" role="function"/>gnome_vfs_async_module_callback_set_default ()</title>
<indexterm><primary>gnome_vfs_async_module_callback_set_default</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_module_callback_set_default
                                            (const <link linkend="char">char</link> *callback_name,
                                             <link linkend="GnomeVFSAsyncModuleCallback">GnomeVFSAsyncModuleCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> callback_data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_notify);</programlisting>
<para>
Set the default async callback for <parameter>callback_name</parameter> to
<parameter>callback</parameter>. <parameter>callback</parameter> will be called with <parameter>callback_data</parameter>
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.
</para>
<para>
The default value is shared for all threads, but setting it is
thread-safe.
</para>
<para>
Use this function if you want to globally set a callback handler
for use with async operations.
</para>
<para>
You can use <link linkend="gnome-vfs-async-module-callback-push"><function>gnome_vfs_async_module_callback_push()</function></link> to set an async
callback function that will temporarily override the default on the
current thread instead. Or you can also use
<link linkend="gnome-vfs-module-callback-set-default"><function>gnome_vfs_module_callback_set_default()</function></link> to set a regular callback
function.
</para>
<para>
Note: <parameter>destroy_notify</parameter> may be called on any thread - it is not
guaranteed to be called on the main thread.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>callback_name</parameter>&nbsp;:</term>
<listitem><simpara> name of the async module callback to set.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
<listitem><simpara> function to call when <parameter>callback</parameter> is invoked.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
<listitem><simpara> data to pass to <parameter>callback</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy_notify</parameter>&nbsp;:</term>
<listitem><simpara> function to call when <parameter>callback_data</parameter> is to be freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-async-module-callback-push" role="function"/>gnome_vfs_async_module_callback_push ()</title>
<indexterm><primary>gnome_vfs_async_module_callback_push</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_module_callback_push
                                            (const <link linkend="char">char</link> *callback_name,
                                             <link linkend="GnomeVFSAsyncModuleCallback">GnomeVFSAsyncModuleCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> callback_data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_notify);</programlisting>
<para>
Set <parameter>callback</parameter> as a temprary async handler for
<parameter>callback_name</parameter>. <parameter>callback</parameter> will be called with <parameter>callback_data</parameter>
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.
</para>
<para>
The temporary async handler is set per-thread.
</para>
<para>
<link linkend="gnome-vfs-async-module-callback-pop"><function>gnome_vfs_async_module_callback_pop()</function></link> removes the most recently set
temporary handler. The temporary async handlers are
treated as a first-in first-out stack.
</para>
<para>
Use this function to set a temporary async callback handler for a
single call or a few calls. You can use
<link linkend="gnome-vfs-async-module-callback-set-default"><function>gnome_vfs_async_module_callback_set_default()</function></link> to set an async
callback function that will establish a permanent global setting
for all threads instead.
</para>
<para>
Note: <parameter>destroy_notify</parameter> may be called on any thread - it is not
guaranteed to be called on the main thread.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>callback_name</parameter>&nbsp;:</term>
<listitem><simpara> name of the module callback to set temporarily.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
<listitem><simpara> function to call when <parameter>callback</parameter> is invoked.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback_data</parameter>&nbsp;:</term>
<listitem><simpara> data to pass to <parameter>callback</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy_notify</parameter>&nbsp;:</term>
<listitem><simpara> function to call when <parameter>callback_data</parameter> is to be freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-async-module-callback-pop" role="function"/>gnome_vfs_async_module_callback_pop ()</title>
<indexterm><primary>gnome_vfs_async_module_callback_pop</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_async_module_callback_pop
                                            (const <link linkend="char">char</link> *callback_name);</programlisting>
<para>
Remove the temporary async handler for <parameter>callback_name</parameter> most recently
set with <link linkend="gnome-vfs-async-module-callback-push"><function>gnome_vfs_async_module_callback_push()</function></link>.  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.
</para>
<para>
The temporary async handlers are treated as a first-in first-out
stack.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>callback_name</parameter>&nbsp;:</term>
<listitem><simpara> name of the module callback to remove a temporary handler for.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
