docs/reference/pygio-seekable.xml

   1 <?xml version="1.0" standalone="no"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3     "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4
   5 <refentry id="class-gioseekable">
   6     <refnamediv>
   7         <refname>gio.Seekable</refname>
   8         <refpurpose>Stream seeking interface.</refpurpose>
   9     </refnamediv>
  10
  11     <refsect1>
  12         <title>Synopsis</title>
  13
  14     <classsynopsis language="python">
  15         <ooclass><classname>gio.Seekable</classname></ooclass>
  16         <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass>
  17
  18     <methodsynopsis language="python">
  19         <methodname><link linkend="method-gioseekable--tell">tell</link></methodname>
  20     </methodsynopsis>
  21
  22     <methodsynopsis language="python">
  23         <methodname><link linkend="method-gioseekable--can_seek">can_seek</link></methodname>
  24     </methodsynopsis>
  25
  26     <methodsynopsis language="python">
  27         <methodname><link linkend="method-gioseekable--seek">seek</link></methodname>
  28         <methodparam><parameter role="keyword">offset</parameter></methodparam>
  29         <methodparam><parameter role="keyword">type</parameter><initializer>0</initializer></methodparam>
  30         <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
  31     </methodsynopsis>
  32
  33     <methodsynopsis language="python">
  34         <methodname><link linkend="method-gioseekable--can_truncate">can_truncate</link></methodname>
  35     </methodsynopsis>
  36
  37     <methodsynopsis language="python">
  38         <methodname><link linkend="method-gioseekable--truncate">truncate</link></methodname>
  39         <methodparam><parameter role="keyword">offset</parameter></methodparam>
  40         <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
  41     </methodsynopsis>
  42
  43     </classsynopsis>
  44
  45     </refsect1>
  46
  47     <refsect1>
  48         <title>Ancestry</title>
  49
  50 <synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link>
  51   +-- <link linkend="class-gioseekable">gio.Seekable</link>
  52 </synopsis>
  53
  54     </refsect1>
  55
  56     <refsect1>
  57         <title>Known Implementation</title>
  58         <para>
  59             <link linkend="class-gioseekable"><classname>gio.Seekable</classname></link> is implemented by
  60             <link linkend="class-giofileoutputstream"><classname>gio.FileOutputStream</classname></link>,
  61             <link linkend="class-giomemoryinputstream"><classname>gio.MemoryInputStream</classname></link>,
  62             <link linkend="class-giofileinputstream"><classname>gio.FileInputStream</classname></link> and
  63             <link linkend="class-giomemoryoutputstream"><classname>gio.MemoryOutputStream</classname></link>.
  64         </para>
  65     </refsect1>
  66
  67     <refsect1>
  68         <title>Description</title>
  69
  70         <para>
  71             <link linkend="class-gioseekable"><classname>gio.Seekable</classname></link>
  72             is implemented by streams (implementations of
  73             <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link> or
  74             <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link>)
  75             that support seeking.
  76         </para>
  77     </refsect1>
  78
  79     <refsect1>
  80         <title>Methods</title>
  81
  82         <refsect2 id="method-gioseekable--tell">
  83             <title>gio.Seekable.tell</title>
  84
  85             <programlisting><methodsynopsis language="python">
  86                 <methodname>tell</methodname>
  87             </methodsynopsis></programlisting>
  88
  89             <variablelist>
  90                 <varlistentry>
  91                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
  92                     <listitem><simpara>
  93                             the offset from the beginning of the buffer
  94                     </simpara></listitem>
  95                 </varlistentry>
  96             </variablelist>
  97
  98             <para>
  99                 Tells the current position within the stream.
 100             </para>
 101         </refsect2>
 102
 103         <refsect2 id="method-gioseekable--can_seek">
 104             <title>gio.Seekable.can_seek</title>
 105
 106             <programlisting><methodsynopsis language="python">
 107                 <methodname>can_seek</methodname>
 108             </methodsynopsis></programlisting>
 109
 110             <variablelist>
 111                 <varlistentry>
 112                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 113                     <listitem><simpara><literal>True</literal> if this
 114                     <classname>gio.Seekable</classname> can be seeked with
 115                     the <methodname>seek</methodname>() method, <literal>False</literal>
 116                     if not. </simpara></listitem>
 117                 </varlistentry>
 118             </variablelist>
 119
 120             <para>
 121                 The <methodname>can_seek</methodname>() method checks if the
 122                 <link linkend="method-gioseekable--seek"><methodname>seek</methodname>()</link>
 123                 can be used on this <classname>gio.Seekable</classname>.
 124             </para>
 125         </refsect2>
 126         <refsect2 id="method-gioseekable--seek">
 127             <title>gio.Seekable.seek</title>
 128
 129             <programlisting><methodsynopsis language="python">
 130                 <methodname>seek</methodname>
 131                 <methodparam><parameter role="keyword">offset</parameter></methodparam>
 132                 <methodparam><parameter role="keyword">type</parameter><initializer>0</initializer></methodparam>
 133                 <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
 134             </methodsynopsis></programlisting>
 135
 136             <variablelist>
 137                 <varlistentry>
 138                     <term><parameter>offset</parameter>&nbsp;:</term>
 139                     <listitem><simpara>the offset that is added to the position determined by the <literal>type</literal> parameter.
 140                     </simpara></listitem>
 141                 </varlistentry>
 142                 <varlistentry>
 143                     <term><parameter>type</parameter>&nbsp;:</term>
 144                     <listitem><simpara>0=current position, 1=start of the file, 2=end of the file.</simpara></listitem>
 145                 </varlistentry>
 146                 <varlistentry>
 147                     <term><parameter>cancellable</parameter>&nbsp;:</term>
 148                     <listitem><simpara>a <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
 149                     or <literal>None</literal>.</simpara></listitem>
 150                 </varlistentry>
 151                 <varlistentry>
 152                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 153                     <listitem><simpara><literal>True</literal> on successful seek,
 154                     <literal>False</literal> otherwise.
 155                     </simpara></listitem>
 156                 </varlistentry>
 157             </variablelist>
 158
 159             <para>
 160                 Seeks in the stream by the given <literal>offset</literal>, modified by <literal>type</literal>.
 161             </para>
 162             <para>
 163                 If <literal>cancellable</literal> is not <literal>None</literal>, then the
 164                 operation can be cancelled by triggering the cancellable object from another thread.
 165             </para>
 166         </refsect2>
 167         <refsect2 id="method-gioseekable--can_truncate">
 168             <title>gio.Seekable.can_truncate</title>
 169
 170             <programlisting><methodsynopsis language="python">
 171                 <methodname>can_truncate</methodname>
 172             </methodsynopsis></programlisting>
 173
 174             <variablelist>
 175                 <varlistentry>
 176                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 177                     <listitem><simpara><literal>True</literal> if this
 178                     <classname>gio.Seekable</classname> can be truncated with
 179                     the <methodname>truncate</methodname>() method, <literal>False</literal>
 180                     if not. </simpara></listitem>
 181                 </varlistentry>
 182             </variablelist>
 183
 184             <para>
 185                 The <methodname>can_truncate</methodname>() method checks if the
 186                 <link linkend="method-gioseekable--truncate"><methodname>truncate</methodname>()</link>
 187                 can be used on this <classname>gio.Seekable</classname>.
 188             </para>
 189         </refsect2>
 190         <refsect2 id="method-gioseekable--truncate">
 191             <title>gio.Seekable.truncate</title>
 192
 193             <programlisting><methodsynopsis language="python">
 194                 <methodname>truncate</methodname>
 195                 <methodparam><parameter role="keyword">offset</parameter></methodparam>
 196                 <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
 197             </methodsynopsis></programlisting>
 198
 199             <variablelist>
 200                 <varlistentry>
 201                     <term><parameter>offset</parameter>&nbsp;:</term>
 202                     <listitem><simpara>the offset at which the stream should be truncated
 203                     </simpara></listitem>
 204                 </varlistentry>
 205                 <varlistentry>
 206                     <term><parameter>cancellable</parameter>&nbsp;:</term>
 207                     <listitem><simpara>a <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
 208                     or <literal>None</literal>.</simpara></listitem>
 209                 </varlistentry>
 210                 <varlistentry>
 211                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 212                     <listitem><simpara><literal>True</literal> if successful,
 213                     <literal>False</literal> otherwise.
 214                     </simpara></listitem>
 215                 </varlistentry>
 216             </variablelist>
 217
 218             <para>
 219                 Truncates a stream with a given <literal>offset</literal>.
 220             </para>
 221             <para>
 222                 If <literal>cancellable</literal> is not <literal>None</literal>, then the
 223                 operation can be cancelled by triggering the cancellable object from another thread.
 224             </para>
 225             <para>
 226                 If an operation was partially finished when the operation was cancelled the
 227                 partial result will be returned, without an error.
 228             </para>
 229         </refsect2>
 230     </refsect1>
 231 </refentry>