path: root/docs/reference/pygio-bufferedinputstream.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-giobufferedinputstream">
    <refnamediv>
        <refname>gio.BufferedInputStream</refname>
        <refpurpose>Buffered Input Stream</refpurpose>
    </refnamediv>

    <refsect1>
        <title>Synopsis</title>

    <classsynopsis language="python">
        <ooclass><classname>gio.BufferedInputStream</classname></ooclass>
        <ooclass><classname><link linkend="class-giofilterinputstream">gio.FilterInputStream</link></classname></ooclass>

    <constructorsynopsis language="python">
	<methodname><link linkend="constructor-giobufferedinputstream">gio.BufferedInputStream</link></methodname>
	<methodparam><parameter role="keyword">base_stream</parameter></methodparam>
    </constructorsynopsis>

    <methodsynopsis language="python">
        <methodname><link linkend="method-giobufferedinputstream--fill">fill</link></methodname>
        <methodparam><parameter role="keyword">count</parameter></methodparam>
        <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giobufferedinputstream--fill-async">fill_async</link></methodname>
        <methodparam><parameter role="keyword">count</parameter></methodparam>
        <methodparam><parameter role="keyword">callback</parameter></methodparam>
        <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam>
        <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
        <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giobufferedinputstream--fill-finish">fill_finish</link></methodname>
        <methodparam><parameter role="keyword">result</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giobufferedinputstream--get-available">get_available</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giobufferedinputstream--get-buffer-size">get_buffer_size</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giobufferedinputstream--read-byte">read_byte</link></methodname>
        <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giobufferedinputstream--set-buffer-size">set_buffer_size</link></methodname>
        <methodparam><parameter role="keyword">size</parameter></methodparam>
    </methodsynopsis>

    </classsynopsis>

<programlisting>
<emphasis role="bold">Functions</emphasis>
 
<methodsynopsis language="python">
    <methodname><link linkend="function-gio--buffered-input-stream-new-sized">gio.buffered_input_stream_new_sized</link></methodname>
    <methodparam><parameter role="keyword">size</parameter></methodparam>
</methodsynopsis></programlisting>

    </refsect1>

    <refsect1>
        <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gioinputstream">gio.InputStream</link>
    +-- <link linkend="class-giofilterinputstream">gio.FilterInputStream</link>
      +-- <link linkend="class-giobufferedinputstream">gio.BufferedInputStream</link>
</synopsis>

    </refsect1>

    <refsect1 id="properties-giobufferedinputstream">
        <title>gio.BufferedInputStream Properties</title>
    
        <blockquote role="properties">
            <informaltable pgwide="1" frame="none">
                <tgroup cols="3">
                    <colspec column="1" colwidth="1in"/>
                    <colspec column="2" colwidth="1in"/>
                    <colspec column="3" colwidth="4in"/>
                    <tbody>
                        <row valign="top">
                            <entry>"buffer-size"</entry>
                            <entry>Read - Write - Construct</entry>
                            <entry>The size of the backend buffer. Allowed values: >= 1. Default value: 4096.</entry>
                        </row>
                    </tbody>
                </tgroup>
            </informaltable>
        </blockquote>
  
    </refsect1>

    <refsect1>
        <title>Description</title>

        <para>
            <link linkend="class-giobufferedinputstream"><classname>gio.BufferedInputStream</classname></link>
            implements <link linkend="class-giofilterinputstream"><classname>gio.FilterInputStream</classname></link>
            and provides for buffered reads.
        </para>
        <para>
            By default,
            <link linkend="class-giobufferedinputstream"><classname>gio.BufferedInputStream</classname></link>'s
            buffer size is set at 4 kilobytes.
        </para>
        <para>
            To create a buffered input stream, use
            <methodname><link linkend="constructor-giobufferedinputstream">gio.BufferedInputStream</link></methodname>(),
            or <methodname><link linkend="function-gio--buffered-input-stream-new-sized">gio.buffered_input_stream_new_sized</link></methodname>()
            to specify the buffer's size at construction.
        </para>
        <para>
            To get the size of a buffer within a buffered input stream, use
            <methodname><link linkend="method-giobufferedinputstream--get-buffer-size">get_buffer_size</link></methodname>().
            To change the size of a buffered input stream's buffer, use
            <methodname><link linkend="method-giobufferedinputstream--set-buffer-size">set_buffer_size</link></methodname>().
            Note that the buffer's size cannot be reduced below the size of the data within the buffer.
        </para>
    </refsect1>

    <refsect1 id="constructor-giobufferedinputstream">
        <title>Constructor</title>
  
        <programlisting><constructorsynopsis language="python">
            <methodname>gio.BufferedInputStream</methodname>
            <methodparam><parameter role="keyword">base_stream</parameter></methodparam>
        </constructorsynopsis></programlisting>
        <variablelist>
            <varlistentry>
                <term><parameter>base_stream</parameter>&nbsp;:</term>
                <listitem><simpara>a
                <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link>.
                </simpara></listitem>
            </varlistentry>
            <varlistentry>
                <term><emphasis>Returns</emphasis>&nbsp;:</term>
                <listitem><simpara>a new
                <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link>
                for the given base_stream.
                </simpara></listitem>
            </varlistentry>
        </variablelist>
    
        <para>
            Creates a new <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link>
            from the given base_stream, with a buffer set to the default size (4 kilobytes).
        </para>
  
    </refsect1>

    <refsect1>
        <title>Methods</title>

        <refsect2 id="method-giobufferedinputstream--fill">
            <title>gio.BufferedInputStream.fill</title>

            <programlisting><methodsynopsis language="python">
                <methodname>fill</methodname>
                <methodparam><parameter role="keyword">count</parameter></methodparam>
                <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">count</parameter>&nbsp;:</term>
                  <listitem><simpara>the number of bytes that will be read from the stream.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                  <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
                  <listitem><simpara>optional
                    <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
                    object, <literal>None</literal> to ignore.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara>the number of bytes read into stream's buffer,
                    up to count, or -1 on error.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>fill</methodname>() method tries to read count bytes
                from the stream into the buffer. Will block during this read.
            </para>
            <para>
                If count is zero, returns zero and does nothing. A value of count
                larger than G_MAXSSIZE will cause a gio.ERROR_INVALID_ARGUMENT error.
            </para>
            <para>
                On success, the number of bytes read into the buffer is returned. It
                is not an error if this is not the same as the requested size, as it can
                happen e.g. near the end of a file. Zero is returned on end of file
                (or if count is zero), but never otherwise.
            </para>
            <para>
                If count is -1 then the attempted read size is equal to the number
                of bytes that are required to fill the buffer.
            </para>
            <para>
                If cancellable is not <literal>None</literal>, then the operation can
                be cancelled by triggering the cancellable object from another thread.
                If the operation was cancelled, the error gio.ERROR_CANCELLED will be
                returned. If an operation was partially finished when the operation was
                cancelled the partial result will be returned, without an error.
            </para>
            <para>
                On error -1 is returned and error is set accordingly.
            </para>
            <para>
                For the asynchronous, non-blocking, version of this function, see
                <methodname><link linkend="method-giobufferedinputstream--fill-async">gio.BufferedInputStream.fill_async</link></methodname>().
            </para>
        </refsect2>

        <refsect2 id="method-giobufferedinputstream--fill-async">
            <title>gio.BufferedInputStream.fill_async</title>

            <programlisting><methodsynopsis language="python">
                <methodname>fill_async</methodname>
                <methodparam><parameter role="keyword">count</parameter></methodparam>
                <methodparam><parameter role="keyword">callback</parameter></methodparam>
                <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam>
                <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
                <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">count</parameter>&nbsp;:</term>
                  <listitem><simpara>the number of bytes that will be read from the stream.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>callback</parameter>&nbsp;:</term>
                    <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied.
                    </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>io_priority</parameter>&nbsp;:</term>
                    <listitem><simpara>the
                    <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref>
                    of the request. 
                    </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>cancellable</parameter>&nbsp;:</term>
                    <listitem><simpara>optional
                    <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
                    object, <literal>None</literal> to ignore.</simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>user_data</parameter>&nbsp;:</term>
                    <listitem><simpara>the data to pass to callback function.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>fill_async</methodname>() method reads data into stream's
                buffer asynchronously, up to count size. io_priority can be used to
                prioritize reads.
            </para>
            <para>
                For the synchronous version of this function, see
                <methodname><link linkend="method-giobufferedinputstream--fill">gio.BufferedInputStream.fill</link></methodname>().
            </para>
            <para>
                If cancellable is not <literal>None</literal>, then the operation can be cancelled
                by triggering the cancellable object from another thread. If the operation was
                cancelled, the error gio.ERROR_CANCELLED will be set
            </para>
            <para>
                If count is -1 then the attempted read size is equal to the number of bytes
                that are required to fill the buffer.
            </para>
        </refsect2>

        <refsect2 id="method-giobufferedinputstream--fill-finish">
            <title>gio.BufferedInputStream.fill_finish</title>

            <programlisting><methodsynopsis language="python">
                <methodname>fill_finish</methodname>
                <methodparam><parameter role="keyword">result</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">result</parameter>&nbsp;:</term>
                  <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara>the size of the read stream, or -1 on an error.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>fill_finish</methodname>() method finishes an asynchronous
                file append operation started with
                <methodname><link linkend="method-giobufferedinputstream--fill-async">gio.BufferedInputStream.fill_async</link></methodname>().
            </para>
        </refsect2>

        <refsect2 id="method-giobufferedinputstream--get-available">
            <title>gio.BufferedInputStream.get_available</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_available</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara>size of the available stream.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>get_available</methodname>() method gets the size of
                the available data within the stream.
            </para>
        </refsect2>

        <refsect2 id="method-giobufferedinputstream--get-buffer-size">
            <title>gio.BufferedInputStream.get_buffer_size</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_buffer_size</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara>the current buffer size.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>get_buffer_size</methodname>() method gets the size
                of the input buffer.
            </para>
        </refsect2>

        <refsect2 id="method-giobufferedinputstream--read-byte">
            <title>gio.BufferedInputStream.read_byte</title>

            <programlisting><methodsynopsis language="python">
                <methodname>read_byte</methodname>
                <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
                  <listitem><simpara>optional
                    <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
                    object, <literal>None</literal> to ignore.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara>the byte read from the stream, or -1 on end of stream or error.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>read_byte</methodname>() method tries to read a single
                byte from the stream or the buffer. Will block during this read.
            </para>
            <para>
                On success, the byte read from the stream is returned. On end of stream -1
                is returned but it's not an exceptional error and error is not set.
            </para>
            <para>
                If cancellable is not <literal>None</literal>, then the operation can
                be cancelled by triggering the cancellable object from another thread.
                If the operation was cancelled, the error gio.ERROR_CANCELLED will be
                returned. If an operation was partially finished when the operation was
                cancelled the partial result will be returned, without an error.
            </para>
            <para>
                On error -1 is returned and error is set accordingly.
            </para>
        </refsect2>

        <refsect2 id="method-giobufferedinputstream--set-buffer-size">
            <title>gio.BufferedInputStream.set_buffer_size</title>

            <programlisting><methodsynopsis language="python">
                <methodname>set_buffer_size</methodname>
                <methodparam><parameter role="keyword">size</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
                  <listitem><simpara>the new buffer size.
                  </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>set_buffer_size</methodname>() method sets the size
                of the internal buffer of stream to size, or to the size of the contents
                of the buffer. The buffer can never be resized smaller than its current contents.
            </para>
        </refsect2>
    </refsect1>
    
    <refsect1>
        <title>Functions</title>

        <refsect2 id="function-gio--buffered-input-stream-new-sized">
            <title>gio.buffered_input_stream_new_sized</title>

            <programlisting><methodsynopsis language="python">
                <methodname>buffered_input_stream_new_sized</methodname>
                <methodparam><parameter role="keyword">size</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter>size</parameter>&nbsp;:</term>
                    <listitem><simpara>the requested buffer size.
                    </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara>A new
                    <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link>.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>

            <para>
                The <methodname>buffered_input_stream_new_sized</methodname>() function creates
                a new <link linkend="class-giobufferedinputstream"><classname>gio.BufferedInputStream</classname></link>
                from the given base_stream, with a buffer set to size.
            </para>
        </refsect2>
    </refsect1>
</refentry>