[pygobject] Add docs for gio.BufferedInputStream
- From: Gian Mario Tagliaretti <gianmt src gnome org>
- To: svn-commits-list gnome org
- Subject: [pygobject] Add docs for gio.BufferedInputStream
- Date: Fri, 12 Jun 2009 19:26:12 -0400 (EDT)
commit a9b13b60a5aad726d7d7dd7fdc5153b1561fb591
Author: Gian Mario Tagliaretti <gianmt gnome org>
Date: Sat Jun 13 01:25:06 2009 +0200
Add docs for gio.BufferedInputStream
docs/Makefile.am | 2 +
docs/reference/pygio-bufferedinputstream.xml | 431 ++++++++++++++++++++++++++
docs/reference/pygio-classes.xml | 1 +
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> :</term>
+ <listitem><simpara>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 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> :</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>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> :</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 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> :</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> :</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> :</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 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> :</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> :</term>
+ <listitem><simpara>the requested buffer size.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</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"/>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
