docs/reference/pygio-bufferedinputstream.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-giobufferedinputstream">
   6     <refnamediv>
   7         <refname>gio.BufferedInputStream</refname>
   8         <refpurpose>Buffered Input Stream</refpurpose>
   9     </refnamediv>
  10
  11     <refsect1>
  12         <title>Synopsis</title>
  13
  14     <classsynopsis language="python">
  15         <ooclass><classname>gio.BufferedInputStream</classname></ooclass>
  16         <ooclass><classname><link linkend="class-giofilterinputstream">gio.FilterInputStream</link></classname></ooclass>
  17
  18     <constructorsynopsis language="python">
  19         <methodname><link linkend="constructor-giobufferedinputstream">gio.BufferedInputStream</link></methodname>
  20         <methodparam><parameter role="keyword">base_stream</parameter></methodparam>
  21     </constructorsynopsis>
  22
  23     <methodsynopsis language="python">
  24         <methodname><link linkend="method-giobufferedinputstream--fill">fill</link></methodname>
  25         <methodparam><parameter role="keyword">count</parameter></methodparam>
  26         <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
  27     </methodsynopsis>
  28     <methodsynopsis language="python">
  29         <methodname><link linkend="method-giobufferedinputstream--fill-async">fill_async</link></methodname>
  30         <methodparam><parameter role="keyword">count</parameter></methodparam>
  31         <methodparam><parameter role="keyword">callback</parameter></methodparam>
  32         <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam>
  33         <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
  34         <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
  35     </methodsynopsis>
  36     <methodsynopsis language="python">
  37         <methodname><link linkend="method-giobufferedinputstream--fill-finish">fill_finish</link></methodname>
  38         <methodparam><parameter role="keyword">result</parameter></methodparam>
  39     </methodsynopsis>
  40     <methodsynopsis language="python">
  41         <methodname><link linkend="method-giobufferedinputstream--get-available">get_available</link></methodname>
  42         <methodparam></methodparam>
  43     </methodsynopsis>
  44     <methodsynopsis language="python">
  45         <methodname><link linkend="method-giobufferedinputstream--get-buffer-size">get_buffer_size</link></methodname>
  46         <methodparam></methodparam>
  47     </methodsynopsis>
  48     <methodsynopsis language="python">
  49         <methodname><link linkend="method-giobufferedinputstream--read-byte">read_byte</link></methodname>
  50         <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
  51     </methodsynopsis>
  52     <methodsynopsis language="python">
  53         <methodname><link linkend="method-giobufferedinputstream--set-buffer-size">set_buffer_size</link></methodname>
  54         <methodparam><parameter role="keyword">size</parameter></methodparam>
  55     </methodsynopsis>
  56
  57     </classsynopsis>
  58
  59 <programlisting>
  60 <emphasis role="bold">Functions</emphasis>
  61
  62 <methodsynopsis language="python">
  63     <methodname><link linkend="function-gio--buffered-input-stream-new-sized">gio.buffered_input_stream_new_sized</link></methodname>
  64     <methodparam><parameter role="keyword">size</parameter></methodparam>
  65 </methodsynopsis></programlisting>
  66
  67     </refsect1>
  68
  69     <refsect1>
  70         <title>Ancestry</title>
  71
  72 <synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  73   +-- <link linkend="class-gioinputstream">gio.InputStream</link>
  74     +-- <link linkend="class-giofilterinputstream">gio.FilterInputStream</link>
  75       +-- <link linkend="class-giobufferedinputstream">gio.BufferedInputStream</link>
  76 </synopsis>
  77
  78     </refsect1>
  79
  80     <refsect1 id="properties-giobufferedinputstream">
  81         <title>gio.BufferedInputStream Properties</title>
  82
  83         <blockquote role="properties">
  84             <informaltable pgwide="1" frame="none">
  85                 <tgroup cols="3">
  86                     <colspec column="1" colwidth="1in"/>
  87                     <colspec column="2" colwidth="1in"/>
  88                     <colspec column="3" colwidth="4in"/>
  89                     <tbody>
  90                         <row valign="top">
  91                             <entry>"buffer-size"</entry>
  92                             <entry>Read - Write - Construct</entry>
  93                             <entry>The size of the backend buffer. Allowed values: >= 1. Default value: 4096.</entry>
  94                         </row>
  95                     </tbody>
  96                 </tgroup>
  97             </informaltable>
  98         </blockquote>
  99
 100     </refsect1>
 101
 102     <refsect1>
 103         <title>Description</title>
 104
 105         <para>
 106             <link linkend="class-giobufferedinputstream"><classname>gio.BufferedInputStream</classname></link>
 107             implements <link linkend="class-giofilterinputstream"><classname>gio.FilterInputStream</classname></link>
 108             and provides for buffered reads.
 109         </para>
 110         <para>
 111             By default,
 112             <link linkend="class-giobufferedinputstream"><classname>gio.BufferedInputStream</classname></link>'s
 113             buffer size is set at 4 kilobytes.
 114         </para>
 115         <para>
 116             To create a buffered input stream, use
 117             <methodname><link linkend="constructor-giobufferedinputstream">gio.BufferedInputStream</link></methodname>(),
 118             or <methodname><link linkend="function-gio--buffered-input-stream-new-sized">gio.buffered_input_stream_new_sized</link></methodname>()
 119             to specify the buffer's size at construction.
 120         </para>
 121         <para>
 122             To get the size of a buffer within a buffered input stream, use
 123             <methodname><link linkend="method-giobufferedinputstream--get-buffer-size">get_buffer_size</link></methodname>().
 124             To change the size of a buffered input stream's buffer, use
 125             <methodname><link linkend="method-giobufferedinputstream--set-buffer-size">set_buffer_size</link></methodname>().
 126             Note that the buffer's size cannot be reduced below the size of the data within the buffer.
 127         </para>
 128     </refsect1>
 129
 130     <refsect1 id="constructor-giobufferedinputstream">
 131         <title>Constructor</title>
 132
 133         <programlisting><constructorsynopsis language="python">
 134             <methodname>gio.BufferedInputStream</methodname>
 135             <methodparam><parameter role="keyword">base_stream</parameter></methodparam>
 136         </constructorsynopsis></programlisting>
 137         <variablelist>
 138             <varlistentry>
 139                 <term><parameter>base_stream</parameter>&nbsp;:</term>
 140                 <listitem><simpara>a
 141                 <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link>.
 142                 </simpara></listitem>
 143             </varlistentry>
 144             <varlistentry>
 145                 <term><emphasis>Returns</emphasis>&nbsp;:</term>
 146                 <listitem><simpara>a new
 147                 <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link>
 148                 for the given base_stream.
 149                 </simpara></listitem>
 150             </varlistentry>
 151         </variablelist>
 152
 153         <para>
 154             Creates a new <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link>
 155             from the given base_stream, with a buffer set to the default size (4 kilobytes).
 156         </para>
 157
 158     </refsect1>
 159
 160     <refsect1>
 161         <title>Methods</title>
 162
 163         <refsect2 id="method-giobufferedinputstream--fill">
 164             <title>gio.BufferedInputStream.fill</title>
 165
 166             <programlisting><methodsynopsis language="python">
 167                 <methodname>fill</methodname>
 168                 <methodparam><parameter role="keyword">count</parameter></methodparam>
 169                 <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
 170             </methodsynopsis></programlisting>
 171
 172             <variablelist>
 173                 <varlistentry>
 174                   <term><parameter role="keyword">count</parameter>&nbsp;:</term>
 175                   <listitem><simpara>the number of bytes that will be read from the stream.
 176                   </simpara></listitem>
 177                 </varlistentry>
 178                 <varlistentry>
 179                   <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
 180                   <listitem><simpara>optional
 181                     <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
 182                     object, <literal>None</literal> to ignore.
 183                   </simpara></listitem>
 184                 </varlistentry>
 185                 <varlistentry>
 186                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 187                     <listitem><simpara>the number of bytes read into stream's buffer,
 188                     up to count, or -1 on error.
 189                     </simpara></listitem>
 190                 </varlistentry>
 191             </variablelist>
 192
 193             <para>
 194                 The <methodname>fill</methodname>() method tries to read count bytes
 195                 from the stream into the buffer. Will block during this read.
 196             </para>
 197             <para>
 198                 If count is zero, returns zero and does nothing. A value of count
 199                 larger than G_MAXSSIZE will cause a gio.ERROR_INVALID_ARGUMENT error.
 200             </para>
 201             <para>
 202                 On success, the number of bytes read into the buffer is returned. It
 203                 is not an error if this is not the same as the requested size, as it can
 204                 happen e.g. near the end of a file. Zero is returned on end of file
 205                 (or if count is zero), but never otherwise.
 206             </para>
 207             <para>
 208                 If count is -1 then the attempted read size is equal to the number
 209                 of bytes that are required to fill the buffer.
 210             </para>
 211             <para>
 212                 If cancellable is not <literal>None</literal>, then the operation can
 213                 be cancelled by triggering the cancellable object from another thread.
 214                 If the operation was cancelled, the error gio.ERROR_CANCELLED will be
 215                 returned. If an operation was partially finished when the operation was
 216                 cancelled the partial result will be returned, without an error.
 217             </para>
 218             <para>
 219                 On error -1 is returned and error is set accordingly.
 220             </para>
 221             <para>
 222                 For the asynchronous, non-blocking, version of this function, see
 223                 <methodname><link linkend="method-giobufferedinputstream--fill-async">gio.BufferedInputStream.fill_async</link></methodname>().
 224             </para>
 225         </refsect2>
 226
 227         <refsect2 id="method-giobufferedinputstream--fill-async">
 228             <title>gio.BufferedInputStream.fill_async</title>
 229
 230             <programlisting><methodsynopsis language="python">
 231                 <methodname>fill_async</methodname>
 232                 <methodparam><parameter role="keyword">count</parameter></methodparam>
 233                 <methodparam><parameter role="keyword">callback</parameter></methodparam>
 234                 <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam>
 235                 <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
 236                 <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
 237             </methodsynopsis></programlisting>
 238
 239             <variablelist>
 240                 <varlistentry>
 241                   <term><parameter role="keyword">count</parameter>&nbsp;:</term>
 242                   <listitem><simpara>the number of bytes that will be read from the stream.
 243                   </simpara></listitem>
 244                 </varlistentry>
 245                 <varlistentry>
 246                     <term><parameter>callback</parameter>&nbsp;:</term>
 247                     <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied.
 248                     </simpara></listitem>
 249                 </varlistentry>
 250                 <varlistentry>
 251                     <term><parameter>io_priority</parameter>&nbsp;:</term>
 252                     <listitem><simpara>the
 253                     <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref>
 254                     of the request.
 255                     </simpara></listitem>
 256                 </varlistentry>
 257                 <varlistentry>
 258                     <term><parameter>cancellable</parameter>&nbsp;:</term>
 259                     <listitem><simpara>optional
 260                     <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
 261                     object, <literal>None</literal> to ignore.</simpara></listitem>
 262                 </varlistentry>
 263                 <varlistentry>
 264                     <term><parameter>user_data</parameter>&nbsp;:</term>
 265                     <listitem><simpara>the data to pass to callback function.
 266                     </simpara></listitem>
 267                 </varlistentry>
 268             </variablelist>
 269
 270             <para>
 271                 The <methodname>fill_async</methodname>() method reads data into stream's
 272                 buffer asynchronously, up to count size. io_priority can be used to
 273                 prioritize reads.
 274             </para>
 275             <para>
 276                 For the synchronous version of this function, see
 277                 <methodname><link linkend="method-giobufferedinputstream--fill">gio.BufferedInputStream.fill</link></methodname>().
 278             </para>
 279             <para>
 280                 If cancellable is not <literal>None</literal>, then the operation can be cancelled
 281                 by triggering the cancellable object from another thread. If the operation was
 282                 cancelled, the error gio.ERROR_CANCELLED will be set
 283             </para>
 284             <para>
 285                 If count is -1 then the attempted read size is equal to the number of bytes
 286                 that are required to fill the buffer.
 287             </para>
 288         </refsect2>
 289
 290         <refsect2 id="method-giobufferedinputstream--fill-finish">
 291             <title>gio.BufferedInputStream.fill_finish</title>
 292
 293             <programlisting><methodsynopsis language="python">
 294                 <methodname>fill_finish</methodname>
 295                 <methodparam><parameter role="keyword">result</parameter></methodparam>
 296             </methodsynopsis></programlisting>
 297
 298             <variablelist>
 299                 <varlistentry>
 300                   <term><parameter role="keyword">result</parameter>&nbsp;:</term>
 301                   <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
 302                   </simpara></listitem>
 303                 </varlistentry>
 304                 <varlistentry>
 305                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 306                     <listitem><simpara>the size of the read stream, or -1 on an error.
 307                     </simpara></listitem>
 308                 </varlistentry>
 309             </variablelist>
 310
 311             <para>
 312                 The <methodname>fill_finish</methodname>() method finishes an asynchronous
 313                 file append operation started with
 314                 <methodname><link linkend="method-giobufferedinputstream--fill-async">gio.BufferedInputStream.fill_async</link></methodname>().
 315             </para>
 316         </refsect2>
 317
 318         <refsect2 id="method-giobufferedinputstream--get-available">
 319             <title>gio.BufferedInputStream.get_available</title>
 320
 321             <programlisting><methodsynopsis language="python">
 322                 <methodname>get_available</methodname>
 323                 <methodparam></methodparam>
 324             </methodsynopsis></programlisting>
 325
 326             <variablelist>
 327                 <varlistentry>
 328                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 329                     <listitem><simpara>size of the available stream.
 330                     </simpara></listitem>
 331                 </varlistentry>
 332             </variablelist>
 333
 334             <para>
 335                 The <methodname>get_available</methodname>() method gets the size of
 336                 the available data within the stream.
 337             </para>
 338         </refsect2>
 339
 340         <refsect2 id="method-giobufferedinputstream--get-buffer-size">
 341             <title>gio.BufferedInputStream.get_buffer_size</title>
 342
 343             <programlisting><methodsynopsis language="python">
 344                 <methodname>get_buffer_size</methodname>
 345                 <methodparam></methodparam>
 346             </methodsynopsis></programlisting>
 347
 348             <variablelist>
 349                 <varlistentry>
 350                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 351                     <listitem><simpara>the current buffer size.
 352                     </simpara></listitem>
 353                 </varlistentry>
 354             </variablelist>
 355
 356             <para>
 357                 The <methodname>get_buffer_size</methodname>() method gets the size
 358                 of the input buffer.
 359             </para>
 360         </refsect2>
 361
 362         <refsect2 id="method-giobufferedinputstream--read-byte">
 363             <title>gio.BufferedInputStream.read_byte</title>
 364
 365             <programlisting><methodsynopsis language="python">
 366                 <methodname>read_byte</methodname>
 367                 <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
 368             </methodsynopsis></programlisting>
 369
 370             <variablelist>
 371                 <varlistentry>
 372                   <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
 373                   <listitem><simpara>optional
 374                     <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
 375                     object, <literal>None</literal> to ignore.
 376                   </simpara></listitem>
 377                 </varlistentry>
 378                 <varlistentry>
 379                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 380                     <listitem><simpara>the byte read from the stream, or -1 on end of stream or error.
 381                     </simpara></listitem>
 382                 </varlistentry>
 383             </variablelist>
 384
 385             <para>
 386                 The <methodname>read_byte</methodname>() method tries to read a single
 387                 byte from the stream or the buffer. Will block during this read.
 388             </para>
 389             <para>
 390                 On success, the byte read from the stream is returned. On end of stream -1
 391                 is returned but it's not an exceptional error and error is not set.
 392             </para>
 393             <para>
 394                 If cancellable is not <literal>None</literal>, then the operation can
 395                 be cancelled by triggering the cancellable object from another thread.
 396                 If the operation was cancelled, the error gio.ERROR_CANCELLED will be
 397                 returned. If an operation was partially finished when the operation was
 398                 cancelled the partial result will be returned, without an error.
 399             </para>
 400             <para>
 401                 On error -1 is returned and error is set accordingly.
 402             </para>
 403         </refsect2>
 404
 405         <refsect2 id="method-giobufferedinputstream--set-buffer-size">
 406             <title>gio.BufferedInputStream.set_buffer_size</title>
 407
 408             <programlisting><methodsynopsis language="python">
 409                 <methodname>set_buffer_size</methodname>
 410                 <methodparam><parameter role="keyword">size</parameter></methodparam>
 411             </methodsynopsis></programlisting>
 412
 413             <variablelist>
 414                 <varlistentry>
 415                   <term><parameter role="keyword">size</parameter>&nbsp;:</term>
 416                   <listitem><simpara>the new buffer size.
 417                   </simpara></listitem>
 418                 </varlistentry>
 419             </variablelist>
 420
 421             <para>
 422                 The <methodname>set_buffer_size</methodname>() method sets the size
 423                 of the internal buffer of stream to size, or to the size of the contents
 424                 of the buffer. The buffer can never be resized smaller than its current contents.
 425             </para>
 426         </refsect2>
 427     </refsect1>
 428
 429     <refsect1>
 430         <title>Functions</title>
 431
 432         <refsect2 id="function-gio--buffered-input-stream-new-sized">
 433             <title>gio.buffered_input_stream_new_sized</title>
 434
 435             <programlisting><methodsynopsis language="python">
 436                 <methodname>buffered_input_stream_new_sized</methodname>
 437                 <methodparam><parameter role="keyword">size</parameter></methodparam>
 438             </methodsynopsis></programlisting>
 439
 440             <variablelist>
 441                 <varlistentry>
 442                     <term><parameter>size</parameter>&nbsp;:</term>
 443                     <listitem><simpara>the requested buffer size.
 444                     </simpara></listitem>
 445                 </varlistentry>
 446                 <varlistentry>
 447                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 448                     <listitem><simpara>A new
 449                     <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link>.
 450                     </simpara></listitem>
 451                 </varlistentry>
 452             </variablelist>
 453
 454             <para>
 455                 The <methodname>buffered_input_stream_new_sized</methodname>() function creates
 456                 a new <link linkend="class-giobufferedinputstream"><classname>gio.BufferedInputStream</classname></link>
 457                 from the given base_stream, with a buffer set to size.
 458             </para>
 459         </refsect2>
 460     </refsect1>
 461 </refentry>