Add docs for gio.BufferedInputStream

3 files changed, 434 insertions, 0 deletions

diff --git a/docs/Makefile.am b/docs/Makefile.am
index d32d4e9..f9255d1 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -19,6 +19,7 @@ HTML_FILES =					\
 	html/class-gioapplaunchcontext.html	\
 	html/class-gioappinfo.html		\
 	html/class-gioasyncresult.html		\
+	html/class-giobufferedinputstream.html	\
 	html/class-giocancellable.html		\
 	html/class-giodrive.html		\
 	html/class-gioemblem.html		\
@@ -76,6 +77,7 @@ XML_FILES = 					\
 	reference/pygio-applaunchcontext.xml 	\
 	reference/pygio-appinfo.xml 		\
 	reference/pygio-asyncresult.xml 	\
+	reference/pygio-bufferedinputstream.xml \
 	reference/pygio-cancellable.xml 	\
 	reference/pygio-drive.xml 		\
 	reference/pygio-emblem.xml		\
diff --git a/docs/reference/pygio-bufferedinputstream.xml b/docs/reference/pygio-bufferedinputstream.xml
new file mode 100644
index 0000000..97d5046
--- /dev/null
+++ b/docs/reference/pygio-bufferedinputstream.xml
@@ -0,0 +1,431 @@
+<?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-giofilterinputstream">
+        <title>gio.FilterInputStream 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>
+        <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>
diff --git a/docs/reference/pygio-classes.xml b/docs/reference/pygio-classes.xml
index f14c592..f9396cb 100644
--- a/docs/reference/pygio-classes.xml
+++ b/docs/reference/pygio-classes.xml
@@ -10,6 +10,7 @@
 <xi:include href="pygio-appinfo.xml"/>
 <xi:include href="pygio-applaunchcontext.xml"/>
 <xi:include href="pygio-asyncresult.xml"/>
+<xi:include href="pygio-bufferedinputstream.xml"/>
 <xi:include href="pygio-cancellable.xml"/>
 <xi:include href="pygio-drive.xml"/>
 <xi:include href="pygio-emblem.xml"/>