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

<refnamediv>
<refname>Cancellation</refname>
<refpurpose>
halt in-progress operations</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

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

<synopsis>



<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link>* <link linkend="gnome-vfs-cancellation-new">gnome_vfs_cancellation_new</link>
                                            (void);
<link linkend="void">void</link>        <link linkend="gnome-vfs-cancellation-destroy">gnome_vfs_cancellation_destroy</link>  (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
<link linkend="void">void</link>        <link linkend="gnome-vfs-cancellation-cancel">gnome_vfs_cancellation_cancel</link>   (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
<link linkend="gboolean">gboolean</link>    <link linkend="gnome-vfs-cancellation-check">gnome_vfs_cancellation_check</link>    (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
<link linkend="void">void</link>        <link linkend="gnome-vfs-cancellation-ack">gnome_vfs_cancellation_ack</link>      (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
<link linkend="gint">gint</link>        <link linkend="gnome-vfs-cancellation-get-fd">gnome_vfs_cancellation_get_fd</link>   (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
</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="gnome-vfs-cancellation-new" role="function"/>gnome_vfs_cancellation_new ()</title>
<indexterm><primary>gnome_vfs_cancellation_new</primary></indexterm><programlisting><link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link>* gnome_vfs_cancellation_new
                                            (void);</programlisting>
<para>
Create a new <link linkend="GnomeVFSCancellation"><type>GnomeVFSCancellation</type></link> object for reporting cancellation to a
gnome-vfs module.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A pointer to the new GnomeVFSCancellation object.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-cancellation-destroy" role="function"/>gnome_vfs_cancellation_destroy ()</title>
<indexterm><primary>gnome_vfs_cancellation_destroy</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_cancellation_destroy  (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Destroy <parameter>cancellation</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeVFSCancellation"><type>GnomeVFSCancellation</type></link> object.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-cancellation-cancel" role="function"/>gnome_vfs_cancellation_cancel ()</title>
<indexterm><primary>gnome_vfs_cancellation_cancel</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_cancellation_cancel   (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Send a cancellation request through <parameter>cancellation</parameter>.
</para>
<para>
If called on a different thread than the one handling idle
callbacks, there is a small race condition where the
operation finished callback will be called even if you
cancelled the operation. Its the apps responsibility
to handle this. See <link linkend="gnome-vfs-async-cancel"><function>gnome_vfs_async_cancel()</function></link> for more
discussion about this.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeVFSCancellation"><type>GnomeVFSCancellation</type></link> object.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-cancellation-check" role="function"/>gnome_vfs_cancellation_check ()</title>
<indexterm><primary>gnome_vfs_cancellation_check</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    gnome_vfs_cancellation_check    (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Check for pending cancellation.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeVFSCancellation"><type>GnomeVFSCancellation</type></link> object.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <literal>TRUE</literal> if the operation should be interrupted.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-cancellation-ack" role="function"/>gnome_vfs_cancellation_ack ()</title>
<indexterm><primary>gnome_vfs_cancellation_ack</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_cancellation_ack      (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Acknowledge a cancellation.  This should be called if
<link linkend="gnome-vfs-cancellation-check"><function>gnome_vfs_cancellation_check()</function></link> returns <literal>TRUE</literal> or if <link linkend="select"><function>select()</function></link> reports that
input is available on the file descriptor returned by
<link linkend="gnome-vfs-cancellation-get-fd"><function>gnome_vfs_cancellation_get_fd()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeVFSCancellation"><type>GnomeVFSCancellation</type></link> object.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-cancellation-get-fd" role="function"/>gnome_vfs_cancellation_get_fd ()</title>
<indexterm><primary>gnome_vfs_cancellation_get_fd</primary></indexterm><programlisting><link linkend="gint">gint</link>        gnome_vfs_cancellation_get_fd   (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Get a file descriptor -based notificator for <parameter>cancellation</parameter>.  When
<parameter>cancellation</parameter> receives a cancellation request, a character will be made
available on the returned file descriptor for input.
</para>
<para>
This is very useful for detecting cancellation during I/O operations: you
can use the <link linkend="select"><function>select()</function></link> call to check for available input/output on the file
you are reading/writing, and on the notificator's file descriptor at the
same time.  If a data is available on the notificator's file descriptor, you
know you have to cancel the read/write operation.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeVFSCancellation"><type>GnomeVFSCancellation</type></link> object.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the notificator's file descriptor, or -1 if starved of
              file descriptors.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
