Add docs for the gio.InputStream class

3 files changed, 733 insertions, 0 deletions

diff --git a/docs/Makefile.am b/docs/Makefile.am
index fd8ed9e..fb761fb 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -28,6 +28,7 @@ HTML_FILES =					\
 	html/class-giofileenumerator.html	\
 	html/class-giofileicon.html		\
 	html/class-gioicon.html			\
+	html/class-gioinputstream.html		\
 	html/class-gioloadableicon.html		\
         html/class-giomount.html		\
 	html/class-giomountoperation.html	\
@@ -75,6 +76,7 @@ XML_FILES = 					\
 	reference/pygio-fileenumerator.xml	\
 	reference/pygio-fileicon.xml 		\
 	reference/pygio-icon.xml		\
+	reference/pygio-inputstream.xml		\
 	reference/pygio-loadableicon.xml	\
 	reference/pygio-mount.xml		\
 	reference/pygio-mountoperation.xml	\
diff --git a/docs/reference/pygio-classes.xml b/docs/reference/pygio-classes.xml
index c4722b3..58c3994 100644
--- a/docs/reference/pygio-classes.xml
+++ b/docs/reference/pygio-classes.xml
@@ -19,6 +19,7 @@
 <xi:include href="pygio-fileenumerator.xml"/>
 <xi:include href="pygio-fileicon.xml"/>
 <xi:include href="pygio-icon.xml"/>
+<xi:include href="pygio-inputstream.xml"/>
 <xi:include href="pygio-loadableicon.xml"/>
 <xi:include href="pygio-mount.xml"/>
 <xi:include href="pygio-mountoperation.xml"/>
diff --git a/docs/reference/pygio-inputstream.xml b/docs/reference/pygio-inputstream.xml
new file mode 100644
index 0000000..b1807e5
--- /dev/null
+++ b/docs/reference/pygio-inputstream.xml
@@ -0,0 +1,730 @@
+<?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-gioinputstream">
+    <refnamediv>
+        <refname>gio.InputStream</refname>
+        <refpurpose>Base class for implementing streaming input</refpurpose>
+    </refnamediv>
+
+    <refsect1>
+        <title>Synopsis</title>
+
+    <classsynopsis language="python">
+        <ooclass><classname>gio.InputStream</classname></ooclass>
+        <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
+
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gioinputstream--clear-pending">clear_pending</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gioinputstream--close">close</link></methodname>
+        <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gioinputstream--close-async">close_async</link></methodname>
+        <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-gioinputstream--close-finish">close_finish</link></methodname>
+        <methodparam><parameter role="keyword">result</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gioinputstream--has-pending">has_pending</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gioinputstream--is-closed">is_closed</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gioinputstream--read">read</link></methodname>
+        <methodparam><parameter role="keyword">count</parameter><initializer>-1</initializer></methodparam>
+        <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gioinputstream--read-async">read_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-gioinputstream--read-finish">read_finish</link></methodname>
+        <methodparam><parameter role="keyword">result</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gioinputstream--read-part">read_part</link></methodname>
+        <methodparam><parameter role="keyword">count</parameter><initializer>-1</initializer></methodparam>
+        <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gioinputstream--set-pending">set_pending</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gioinputstream--skip">skip</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-gioinputstream--skip-async">skip_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-gioinputstream--skip-finish">skip_finish</link></methodname>
+        <methodparam><parameter role="keyword">result</parameter></methodparam>
+    </methodsynopsis>
+
+    </classsynopsis>
+
+    </refsect1>
+
+    <refsect1>
+        <title>Ancestry</title>
+
+<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
+  +-- <link linkend="class-gioinputstream">gio.InputStream</link>
+</synopsis>
+
+    </refsect1>
+
+    <refsect1>
+        <title>Description</title>
+
+        <para>
+            <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link>
+            has functions to read from a stream (
+            <methodname><link linkend="method-gioinputstream--read">gio.InputStream.read</link></methodname>()
+            ), to close a stream (
+            <methodname><link linkend="method-gioinputstream--close">gio.InputStream.close</link></methodname>()
+            ) and to skip some content (
+            <methodname><link linkend="method-gioinputstream--skip">gio.InputStream.skip</link></methodname>()
+            ).
+        </para>
+        <para>
+            To copy the content of an input stream to an output stream without manually
+            handling the reads and writes, use
+            <methodname><link linkend="method-giooutputstream--skip">gio.OutputStream.splice</link></methodname>().
+        </para>
+        <para>
+            All of these functions have async variants too.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Methods</title>
+
+        <refsect2 id="method-gioinputstream--clear-pending">
+            <title>gio.InputStream.clear_pending</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>clear_pending</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+            </variablelist>
+    
+            <para>
+                The <methodname>clear_pending</methodname>() method clears the pending flag on stream.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gioinputstream--close">
+            <title>gio.InputStream.close</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>close</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><literal>True</literal> on success
+                    <literal>False</literal> on failure.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>close</methodname>() method closes the stream, releasing
+                resources related to it.
+            </para>
+            <para>
+                Once the stream is closed, all other operations will return gio.IO_ERROR_CLOSED.
+                Closing a stream multiple times will not return an error.
+            </para>
+            <para>
+                Streams will be automatically closed when the last reference is dropped, but
+                you might want to call this function to make sure resources are released as
+                early as possible.
+            </para>
+            <para>
+                Some streams might keep the backing store of the stream (e.g. a file descriptor)
+                open after the stream is closed. See the documentation for the individual
+                stream for details.
+            </para>
+            <para>
+                On failure the first error that happened will be reported, but the close operation
+                will finish as much as possible. A stream that failed to close will still return
+                gio.IO_ERROR_CLOSED for all operations. Still, it is important to check and report
+                the error to the user.
+            </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.IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave
+                the stream closed, but some streams can use a faster close that doesn't block to e.g.
+                check errors.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gioinputstream--close-async">
+            <title>gio.InputStream.close_async</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>close_async</methodname>
+                <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>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>close_async</methodname>() method asynchronously requests an
+                asynchronous closes of the stream, releasing resources related to it.
+            </para>
+            <para>
+                For more details, see
+                <methodname><link linkend="method-gioinputstream--close">gio.InputStream.close</link></methodname>()
+                which is the synchronous version of this call. 
+            </para>
+            <para>
+                When the operation is finished, callback will be called. You can then call
+                <methodname><link linkend="method-gioinputstream--close-finish">gio.InputStream.close_finish</link></methodname>()
+                to get the result of the operation.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gioinputstream--close-finish">
+            <title>gio.InputStream.close_finish</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>close_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><literal>True</literal> if the stream was closed successfully.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>close_finish</methodname>() method finishes an asynchronous
+                file append operation started with
+                <methodname><link linkend="method-gioinputstream--close-async">gio.InputStream.close_async</link></methodname>().
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gioinputstream--has-pending">
+            <title>gio.InputStream.has_pending</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>has_pending</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara><literal>True</literal> if stream has pending actions.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>has_pending</methodname>() method checks if an input stream has pending actions.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gioinputstream--is-closed">
+            <title>gio.InputStream.is_closed</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>is_closed</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara><literal>True</literal> if the stream is closed.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>is_closed</methodname>() method checks if an input stream is closed.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gioinputstream--read">
+            <title>gio.InputStream.read</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>read</methodname>
+                <methodparam><parameter role="keyword">count</parameter><initializer>-1</initializer></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>optionally 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, or -1 on error.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>read</methodname>() method tries to read count bytes from
+                the stream into the buffer starting at buffer. Will block during this read.
+            </para>
+            <para>
+                This function is similar to
+                <methodname><link linkend="method-gioinputstream--read-part">gio.InputStream.read_part</link></methodname>(),
+                except it tries to read as many bytes as requested, only stopping on an error or end of stream.
+            </para>
+            <para>
+                On a successful read of count bytes, or if we reached the end of the stream,
+                <literal>True</literal> is returned, and bytes_read is set to the number of bytes read into 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.IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave
+                the stream closed, but some streams can use a faster close that doesn't block to e.g.
+                check errors.
+            </para>
+            <para>
+                If there is an error during the operation <literal>False</literal> is returned and error
+                is set to indicate the error status, bytes_read is updated to contain the number of
+                bytes read into buffer before the error occurred.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gioinputstream--read-async">
+            <title>gio.InputStream.read_async</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>read_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>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>read_async</methodname>() method requests an asynchronous read
+                of count bytes from the stream into the buffer.
+            </para>
+            <para>
+                For more details, see
+                <methodname><link linkend="method-gioinputstream--read">gio.InputStream.read</link></methodname>()
+                which is the synchronous version of this call. 
+            </para>
+            <para>
+                When the operation is finished, callback will be called. You can then call
+                <methodname><link linkend="method-gioinputstream--read-finish">gio.InputStream.read_finish</link></methodname>()
+                to get the result of the operation.
+            </para>
+            <para>
+                During an async request no other sync and async calls are allowed, and
+                will result in gio.IO_ERROR_PENDING errors.
+            </para>
+            <para>
+                A value of count larger than G_MAXSSIZE will cause a gio.IO_ERROR_INVALID_ARGUMENT error.
+            </para>
+            <para>
+                On success, the number of bytes read into the buffer will be passed to the callback.
+                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, but generally we try to read as many bytes as requested. Zero
+                is returned on end of file (or if count is zero), but never otherwise.
+            </para>
+            <para>
+                Any outstanding i/o request with higher priority (lower numerical value) will be
+                executed before an outstanding request with lower priority. Default priority is glib.PRIORITY_DEFAULT.
+            </para>
+            <para>
+                The asyncronous methods have a default fallback that uses threads to implement asynchronicity, so
+                they are optional for inheriting classes. However, if you override one you must override all.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gioinputstream--read-finish">
+            <title>gio.InputStream.read_finish</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>read_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 number of bytes read in, or -1 on error.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>read_finish</methodname>() method finishes an asynchronous
+                stream read operation started by
+                <methodname><link linkend="method-gioinputstream--read-async">gio.InputStream.read_async</link></methodname>().
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gioinputstream--read-part">
+            <title>gio.InputStream.read_part</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>read_part</methodname>
+                <methodparam><parameter role="keyword">count</parameter><initializer>-1</initializer></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>optionally 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, or -1 on error.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>read_part</methodname>() method tries to read count bytes from
+                the stream into the buffer starting at 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.IO_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 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.IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave
+                the stream closed, but some streams can use a faster close that doesn't block to e.g.
+                check errors.
+            </para>
+            <para>
+                On error -1 is returned and error is set accordingly.
+            </para>
+            <note>
+                This method roughly corresponds to C GIO g_input_stream_read.
+            </note>
+        </refsect2>
+
+        <refsect2 id="method-gioinputstream--set-pending">
+            <title>gio.InputStream.set_pending</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>set_pending</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara><literal>True</literal> if pending was previously
+                    unset and is now set.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>set_pending</methodname>() method sets stream to have actions pending.
+                If the pending flag is already set or stream is closed,
+                it will return <literal>False</literal> and set error.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gioinputstream--skip">
+            <title>gio.InputStream.skip</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>skip</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 skipped 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 skipped, or -1 on error
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>skip</methodname>() method tries to skip count bytes
+                from the stream. Will block during the operation.
+            </para>
+            <para>
+                This is identical to
+                <methodname><link linkend="method-gioinputstream--read">read</link></methodname>(),
+                from a behaviour standpoint, but the bytes that are skipped are not
+                returned to the user. Some streams have an implementation that is more
+                efficient than reading the data.
+            </para>
+            <para>
+                This function is optional for inherited classes, as the default implementation emulates it using read.
+            </para>
+            <para>
+               If cancellable is not <literal>None</literal>, then the operation can be cancelled by
+                triggering the cancellable object from another thskip. If the operation was cancelled,
+                the error gio.IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave
+                the stream closed, but some streams can use a faster close that doesn't block to e.g.
+                check errors.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gioinputstream--skip-async">
+            <title>gio.InputStream.skip_async</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>skip_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>count</parameter>&nbsp;:</term>
+                    <listitem><simpara>the number of bytes that will be skipped from the stream.
+                    </simpara></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><parameter>callback</parameter>&nbsp;:</term>
+                    <listitem><simpara>a GAsyncskipyCallback 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>skip_async</methodname>() method request an asynchronous
+                skip of count bytes from the stream.
+            </para>
+            <para>
+                For more details, see
+                <methodname><link linkend="method-gioinputstream--skip">gio.InputStream.skip</link></methodname>()
+                which is the synchronous version of this call. 
+            </para>
+            <para>
+                When the operation is finished, callback will be called. You can then call
+                <methodname><link linkend="method-gioinputstream--skip-finish">gio.InputStream.skip_finish</link></methodname>()
+                to get the result of the operation.
+            </para>
+            <para>
+                During an async request no other sync and async calls are allowed, and
+                will result in gio.IO_ERROR_PENDING errors.
+            </para>
+            <para>
+                A value of count larger than G_MAXSSIZE will cause a gio.IO_ERROR_INVALID_ARGUMENT error.
+            </para>
+            <para>
+                On success, the number of bytes skipped will be passed to the callback. 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, but generally we try to skip as many bytes as requested.
+                Zero is returned on end of file (or if count is zero), but never otherwise.
+            </para>
+            <para>
+                Any outstanding i/o request with higher priority (lower numerical value) will be
+                executed before an outstanding request with lower priority. Default priority is glib.PRIORITY_DEFAULT.
+            </para>
+            <para>
+                The asyncronous methods have a default fallback that uses thskips to implement asynchronicity, so
+                they are optional for inheriting classes. However, if you override one you must override all.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gioinputstream--skip-finish">
+            <title>gio.InputStream.skip_finish</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>skip_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 number of bytes skipped in, or -1 on error.
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>skip_finish</methodname>() method finishes an asynchronous
+                stream skip operation started by
+                <methodname><link linkend="method-gioinputstream--skip-async">gio.InputStream.skip_async</link></methodname>().
+            </para>
+        </refsect2>
+    </refsect1>
+</refentry>