[pygobject] Add docs for the gio.InputStream class
- From: Gian Mario Tagliaretti <gianmt src gnome org>
- To: svn-commits-list gnome org
- Subject: [pygobject] Add docs for the gio.InputStream class
- Date: Fri, 8 May 2009 18:05:07 -0400 (EDT)
commit ed6b06315c17441b41c001d38537c904b8fe18de
Author: Gian Mario Tagliaretti <gianmt gnome org>
Date: Sat May 9 00:02:33 2009 +0200
Add docs for the gio.InputStream class
---
docs/Makefile.am | 2 +
docs/reference/pygio-classes.xml | 1 +
docs/reference/pygio-inputstream.xml | 730 ++++++++++++++++++++++++++++++++++
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> :</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> :</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> :</term>
+ <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>io_priority</parameter> :</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> :</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> :</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> :</term>
+ <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</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> :</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> :</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> :</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> :</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> :</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> :</term>
+ <listitem><simpara>the number of bytes that will be read from the stream.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>callback</parameter> :</term>
+ <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>io_priority</parameter> :</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> :</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> :</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> :</term>
+ <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</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> :</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> :</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> :</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> :</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> :</term>
+ <listitem><simpara>the number of bytes that will be skipped from the stream.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter role="keyword">cancellable</parameter> :</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> :</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> :</term>
+ <listitem><simpara>the number of bytes that will be skipped from the stream.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>callback</parameter> :</term>
+ <listitem><simpara>a GAsyncskipyCallback to call when the request is satisfied.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>io_priority</parameter> :</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> :</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> :</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> :</term>
+ <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</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>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
