doc/xml/gnome-vfs-cancellation.xml

   1 <refentry id="gnome-vfs-20-gnome-vfs-cancellation">
   2 <refmeta>
   3 <refentrytitle>Cancellation</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>GNOME-VFS-2.0 Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Cancellation</refname><refpurpose>
  10 halt in-progress operations</refpurpose>
  11 </refnamediv>
  12
  13 <refsynopsisdiv><title>Synopsis</title>
  14
  15 <synopsis>
  16
  17
  18
  19 <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link>* <link linkend="gnome-vfs-cancellation-new">gnome_vfs_cancellation_new</link>
  20                                             (void);
  21 <link linkend="void">void</link>        <link linkend="gnome-vfs-cancellation-destroy">gnome_vfs_cancellation_destroy</link>  (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
  22 <link linkend="void">void</link>        <link linkend="gnome-vfs-cancellation-cancel">gnome_vfs_cancellation_cancel</link>   (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
  23 <link linkend="gboolean">gboolean</link>    <link linkend="gnome-vfs-cancellation-check">gnome_vfs_cancellation_check</link>    (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
  24 <link linkend="void">void</link>        <link linkend="gnome-vfs-cancellation-ack">gnome_vfs_cancellation_ack</link>      (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
  25 <link linkend="gint">gint</link>        <link linkend="gnome-vfs-cancellation-get-fd">gnome_vfs_cancellation_get_fd</link>   (<link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
  26 </synopsis>
  27 </refsynopsisdiv>
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37 <refsect1>
  38 <title>Description</title>
  39 <para>
  40
  41 </para>
  42 </refsect1>
  43
  44 <refsect1>
  45 <title>Details</title>
  46 <refsect2>
  47 <title><anchor id="gnome-vfs-cancellation-new"/>gnome_vfs_cancellation_new ()</title>
  48 <indexterm><primary>gnome_vfs_cancellation_new</primary></indexterm><programlisting><link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link>* gnome_vfs_cancellation_new
  49                                             (void);</programlisting>
  50 <para>
  51 Create a new GnomeVFSCancellation object for reporting cancellation to a
  52 GNOME VFS module.</para>
  53 <para>
  54
  55 </para><variablelist role="params">
  56 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A pointer to the new GnomeVFSCancellation object.
  57 </simpara></listitem></varlistentry>
  58 </variablelist></refsect2>
  59 <refsect2>
  60 <title><anchor id="gnome-vfs-cancellation-destroy"/>gnome_vfs_cancellation_destroy ()</title>
  61 <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>
  62 <para>
  63 Destroy <parameter>cancellation</parameter>.</para>
  64 <para>
  65
  66 </para><variablelist role="params">
  67 <varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
  68 <listitem><simpara> A GnomeVFSCancellation object
  69 </simpara></listitem></varlistentry>
  70 </variablelist></refsect2>
  71 <refsect2>
  72 <title><anchor id="gnome-vfs-cancellation-cancel"/>gnome_vfs_cancellation_cancel ()</title>
  73 <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>
  74 <para>
  75 Send a cancellation request through <parameter>cancellation</parameter>.</para>
  76 <para>
  77
  78 </para><variablelist role="params">
  79 <varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
  80 <listitem><simpara> A GnomeVFSCancellation object
  81 </simpara></listitem></varlistentry>
  82 </variablelist></refsect2>
  83 <refsect2>
  84 <title><anchor id="gnome-vfs-cancellation-check"/>gnome_vfs_cancellation_check ()</title>
  85 <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>
  86 <para>
  87 Check for pending cancellation.</para>
  88 <para>
  89
  90 </para><variablelist role="params">
  91 <varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
  92 <listitem><simpara> A GnomeVFSCancellation object
  93 </simpara></listitem></varlistentry>
  94 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if the operation should be interrupted.
  95 </simpara></listitem></varlistentry>
  96 </variablelist></refsect2>
  97 <refsect2>
  98 <title><anchor id="gnome-vfs-cancellation-ack"/>gnome_vfs_cancellation_ack ()</title>
  99 <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>
 100 <para>
 101 Acknowledge a cancellation.  This should be called if
 102 `<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
 103 input is available on the file descriptor returned by
 104 `<link linkend="gnome-vfs-cancellation-get-fd"><function>gnome_vfs_cancellation_get_fd()</function></link>'.</para>
 105 <para>
 106
 107 </para><variablelist role="params">
 108 <varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
 109 <listitem><simpara> A GnomeVFSCancellation object
 110 </simpara></listitem></varlistentry>
 111 </variablelist></refsect2>
 112 <refsect2>
 113 <title><anchor id="gnome-vfs-cancellation-get-fd"/>gnome_vfs_cancellation_get_fd ()</title>
 114 <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>
 115 <para>
 116 Get a file descriptor -based notificator for <parameter>cancellation</parameter>.  When
 117 <parameter>cancellation</parameter> receives a cancellation request, a character will be made
 118 available on the returned file descriptor for input.
 119 </para>
 120 <para>
 121 This is very useful for detecting cancellation during I/O operations: you
 122 can use the `<link linkend="select"><function>select()</function></link>' call to check for available input/output on the file
 123 you are reading/writing, and on the notificator's file descriptor at the
 124 same time.  If a data is available on the notificator's file descriptor, you
 125 know you have to cancel the read/write operation.</para>
 126 <para>
 127
 128 </para><variablelist role="params">
 129 <varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
 130 <listitem><simpara> A GnomeVFSCancellation object
 131 </simpara></listitem></varlistentry>
 132 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the notificator's file descriptor, or -1 if starved of
 133               file descriptors.
 134 </simpara></listitem></varlistentry>
 135 </variablelist></refsect2>
 136
 137 </refsect1>
 138
 139
 140
 141
 142 </refentry>