| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>GInputStream: GIO Reference Manual</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> |
| <link rel="home" href="index.html" title="GIO Reference Manual"> |
| <link rel="up" href="streaming.html" title="Streaming I/O"> |
| <link rel="prev" href="GSeekable.html" title="GSeekable"> |
| <link rel="next" href="GOutputStream.html" title="GOutputStream"> |
| <meta name="generator" content="GTK-Doc V1.25.1 (XML mode)"> |
| <link rel="stylesheet" href="style.css" type="text/css"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> |
| <td width="100%" align="left" class="shortcuts"> |
| <a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> |
| <a href="#GInputStream.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> |
| <a href="#GInputStream.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_derived_interfaces"> <span class="dim">|</span> |
| <a href="#GInputStream.derived-interfaces" class="shortcut">Known Derived Interfaces</a></span> |
| </td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> |
| <td><a accesskey="u" href="streaming.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> |
| <td><a accesskey="p" href="GSeekable.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> |
| <td><a accesskey="n" href="GOutputStream.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> |
| </tr></table> |
| <div class="refentry"> |
| <a name="GInputStream"></a><div class="titlepage"></div> |
| <div class="refnamediv"><table width="100%"><tr> |
| <td valign="top"> |
| <h2><span class="refentrytitle"><a name="GInputStream.top_of_page"></a>GInputStream</span></h2> |
| <p>GInputStream — Base class for implementing streaming input</p> |
| </td> |
| <td class="gallery_image" valign="top" align="right"></td> |
| </tr></table></div> |
| <div class="refsect1"> |
| <a name="GInputStream.functions"></a><h2>Functions</h2> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="functions_return"> |
| <col class="functions_name"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="function_type"> |
| <a href="../glib-Basic-Types.html#gssize"><span class="returnvalue">gssize</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-read" title="g_input_stream_read ()">g_input_stream_read</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-read-all" title="g_input_stream_read_all ()">g_input_stream_read_all</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-read-all-async" title="g_input_stream_read_all_async ()">g_input_stream_read_all_async</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-read-all-finish" title="g_input_stream_read_all_finish ()">g_input_stream_read_all_finish</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a href="../glib-Basic-Types.html#gssize"><span class="returnvalue">gssize</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-skip" title="g_input_stream_skip ()">g_input_stream_skip</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-close" title="g_input_stream_close ()">g_input_stream_close</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-read-async" title="g_input_stream_read_async ()">g_input_stream_read_async</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a href="../glib-Basic-Types.html#gssize"><span class="returnvalue">gssize</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-read-finish" title="g_input_stream_read_finish ()">g_input_stream_read_finish</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-skip-async" title="g_input_stream_skip_async ()">g_input_stream_skip_async</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a href="../glib-Basic-Types.html#gssize"><span class="returnvalue">gssize</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-skip-finish" title="g_input_stream_skip_finish ()">g_input_stream_skip_finish</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-close-async" title="g_input_stream_close_async ()">g_input_stream_close_async</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-close-finish" title="g_input_stream_close_finish ()">g_input_stream_close_finish</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-is-closed" title="g_input_stream_is_closed ()">g_input_stream_is_closed</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-has-pending" title="g_input_stream_has_pending ()">g_input_stream_has_pending</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-set-pending" title="g_input_stream_set_pending ()">g_input_stream_set_pending</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-clear-pending" title="g_input_stream_clear_pending ()">g_input_stream_clear_pending</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a href="../glib-Byte-Arrays.html#GBytes"><span class="returnvalue">GBytes</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-read-bytes" title="g_input_stream_read_bytes ()">g_input_stream_read_bytes</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-read-bytes-async" title="g_input_stream_read_bytes_async ()">g_input_stream_read_bytes_async</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a href="../glib-Byte-Arrays.html#GBytes"><span class="returnvalue">GBytes</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="GInputStream.html#g-input-stream-read-bytes-finish" title="g_input_stream_read_bytes_finish ()">g_input_stream_read_bytes_finish</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect1"> |
| <a name="GInputStream.other"></a><h2>Types and Values</h2> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="name"> |
| <col class="description"> |
| </colgroup> |
| <tbody><tr> |
| <td class="datatype_keyword"> </td> |
| <td class="function_name"><a class="link" href="GInputStream.html#GInputStream-struct" title="GInputStream">GInputStream</a></td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect1"> |
| <a name="GInputStream.object-hierarchy"></a><h2>Object Hierarchy</h2> |
| <pre class="screen"> <a href="../gobject-The-Base-Object-Type.html#GObject-struct">GObject</a> |
| <span class="lineart">╰──</span> GInputStream |
| <span class="lineart">├──</span> <a class="link" href="GFilterInputStream.html" title="GFilterInputStream">GFilterInputStream</a> |
| <span class="lineart">├──</span> <a class="link" href="GFileInputStream.html" title="GFileInputStream">GFileInputStream</a> |
| <span class="lineart">├──</span> <a class="link" href="GMemoryInputStream.html" title="GMemoryInputStream">GMemoryInputStream</a> |
| <span class="lineart">╰──</span> <a class="link" href="GUnixInputStream.html" title="GUnixInputStream">GUnixInputStream</a> |
| </pre> |
| </div> |
| <div class="refsect1"> |
| <a name="GInputStream.derived-interfaces"></a><h2>Known Derived Interfaces</h2> |
| <p> |
| GInputStream is required by |
| <a class="link" href="GPollableInputStream.html" title="GPollableInputStream">GPollableInputStream</a>.</p> |
| </div> |
| <div class="refsect1"> |
| <a name="GInputStream.includes"></a><h2>Includes</h2> |
| <pre class="synopsis">#include <gio/gio.h> |
| </pre> |
| </div> |
| <div class="refsect1"> |
| <a name="GInputStream.description"></a><h2>Description</h2> |
| <p><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> has functions to read from a stream (<a class="link" href="GInputStream.html#g-input-stream-read" title="g_input_stream_read ()"><code class="function">g_input_stream_read()</code></a>), |
| to close a stream (<a class="link" href="GInputStream.html#g-input-stream-close" title="g_input_stream_close ()"><code class="function">g_input_stream_close()</code></a>) and to skip some content |
| (<a class="link" href="GInputStream.html#g-input-stream-skip" title="g_input_stream_skip ()"><code class="function">g_input_stream_skip()</code></a>). </p> |
| <p>To copy the content of an input stream to an output stream without |
| manually handling the reads and writes, use <a class="link" href="GOutputStream.html#g-output-stream-splice" title="g_output_stream_splice ()"><code class="function">g_output_stream_splice()</code></a>.</p> |
| <p>See the documentation for <a class="link" href="GIOStream.html" title="GIOStream"><span class="type">GIOStream</span></a> for details of thread safety of |
| streaming APIs.</p> |
| <p>All of these functions have async variants too.</p> |
| </div> |
| <div class="refsect1"> |
| <a name="GInputStream.functions_details"></a><h2>Functions</h2> |
| <div class="refsect2"> |
| <a name="g-input-stream-read"></a><h3>g_input_stream_read ()</h3> |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gssize"><span class="returnvalue">gssize</span></a> |
| g_input_stream_read (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><span class="type">void</span> *buffer</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> count</code></em>, |
| <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> |
| <p>Tries to read <em class="parameter"><code>count</code></em> |
| bytes from the stream into the buffer starting at |
| <em class="parameter"><code>buffer</code></em> |
| . Will block during this read.</p> |
| <p>If count is zero returns zero and does nothing. A value of <em class="parameter"><code>count</code></em> |
| |
| larger than <a href="../glib-Basic-Types.html#G-MAXSSIZE:CAPS"><code class="literal">G_MAXSSIZE</code></a> will cause a <a class="link" href="gio-GIOError.html#G-IO-ERROR-INVALID-ARGUMENT:CAPS"><code class="literal">G_IO_ERROR_INVALID_ARGUMENT</code></a> error.</p> |
| <p>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 <em class="parameter"><code>count</code></em> |
| is zero), but never otherwise.</p> |
| <p>The returned <em class="parameter"><code>buffer</code></em> |
| is not a nul-terminated string, it can contain nul bytes |
| at any position, and this function doesn't nul-terminate the <em class="parameter"><code>buffer</code></em> |
| .</p> |
| <p>If <em class="parameter"><code>cancellable</code></em> |
| is not <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, then the operation can be cancelled by |
| triggering the cancellable object from another thread. If the operation |
| was cancelled, the error <a class="link" href="gio-GIOError.html#G-IO-ERROR-CANCELLED:CAPS"><code class="literal">G_IO_ERROR_CANCELLED</code></a> will be returned. If an |
| operation was partially finished when the operation was cancelled the |
| partial result will be returned, without an error.</p> |
| <p>On error -1 is returned and <em class="parameter"><code>error</code></em> |
| is set accordingly.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-read.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>buffer</p></td> |
| <td class="parameter_description"><p> a buffer to |
| read data into (which should be at least count bytes long). </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=count][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> guint8]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>count</p></td> |
| <td class="parameter_description"><p>the number of bytes that will be read from the stream</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>cancellable</p></td> |
| <td class="parameter_description"><p> optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>error</p></td> |
| <td class="parameter_description"><p>location to store the error occurring, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-input-stream-read.returns"></a><h4>Returns</h4> |
| <p> Number of bytes read, or -1 on error, or 0 on end of file.</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-read-all"></a><h3>g_input_stream_read_all ()</h3> |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| g_input_stream_read_all (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><span class="type">void</span> *buffer</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> count</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> *bytes_read</code></em>, |
| <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> |
| <p>Tries to read <em class="parameter"><code>count</code></em> |
| bytes from the stream into the buffer starting at |
| <em class="parameter"><code>buffer</code></em> |
| . Will block during this read.</p> |
| <p>This function is similar to <a class="link" href="GInputStream.html#g-input-stream-read" title="g_input_stream_read ()"><code class="function">g_input_stream_read()</code></a>, except it tries to |
| read as many bytes as requested, only stopping on an error or end of stream.</p> |
| <p>On a successful read of <em class="parameter"><code>count</code></em> |
| bytes, or if we reached the end of the |
| stream, <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> is returned, and <em class="parameter"><code>bytes_read</code></em> |
| is set to the number of bytes |
| read into <em class="parameter"><code>buffer</code></em> |
| .</p> |
| <p>If there is an error during the operation <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> is returned and <em class="parameter"><code>error</code></em> |
| |
| is set to indicate the error status.</p> |
| <p>As a special exception to the normal conventions for functions that |
| use <a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, if this function returns <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> (and sets <em class="parameter"><code>error</code></em> |
| ) then |
| <em class="parameter"><code>bytes_read</code></em> |
| will be set to the number of bytes that were successfully |
| read before the error was encountered. This functionality is only |
| available from C. If you need it from another language then you must |
| write your own loop around <a class="link" href="GInputStream.html#g-input-stream-read" title="g_input_stream_read ()"><code class="function">g_input_stream_read()</code></a>.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-read-all.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>buffer</p></td> |
| <td class="parameter_description"><p> a buffer to |
| read data into (which should be at least count bytes long). </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=count][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> guint8]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>count</p></td> |
| <td class="parameter_description"><p>the number of bytes that will be read from the stream</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>bytes_read</p></td> |
| <td class="parameter_description"><p> location to store the number of bytes that was read from the stream. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>cancellable</p></td> |
| <td class="parameter_description"><p> optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>error</p></td> |
| <td class="parameter_description"><p>location to store the error occurring, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-input-stream-read-all.returns"></a><h4>Returns</h4> |
| <p> <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> on success, <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if there was an error</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-read-all-async"></a><h3>g_input_stream_read_all_async ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| g_input_stream_read_all_async (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><span class="type">void</span> *buffer</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> count</code></em>, |
| <em class="parameter"><code><span class="type">int</span> io_priority</code></em>, |
| <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, |
| <em class="parameter"><code><a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> callback</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> |
| <p>Request an asynchronous read of <em class="parameter"><code>count</code></em> |
| bytes from the stream into the |
| buffer starting at <em class="parameter"><code>buffer</code></em> |
| .</p> |
| <p>This is the asynchronous equivalent of <a class="link" href="GInputStream.html#g-input-stream-read-all" title="g_input_stream_read_all ()"><code class="function">g_input_stream_read_all()</code></a>.</p> |
| <p>Call <a class="link" href="GInputStream.html#g-input-stream-read-all-finish" title="g_input_stream_read_all_finish ()"><code class="function">g_input_stream_read_all_finish()</code></a> to collect the result.</p> |
| <p>Any outstanding I/O request with higher priority (lower numerical |
| value) will be executed before an outstanding request with lower |
| priority. Default priority is <a href="../glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT:CAPS"><code class="literal">G_PRIORITY_DEFAULT</code></a>.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-read-all-async.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>A <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>buffer</p></td> |
| <td class="parameter_description"><p> a buffer to |
| read data into (which should be at least count bytes long). </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=count][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> guint8]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>count</p></td> |
| <td class="parameter_description"><p>the number of bytes that will be read from the stream</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>io_priority</p></td> |
| <td class="parameter_description"><p>the <a class="link" href="GAsyncResult.html#io-priority" title="I/O Priority">I/O priority</a> of the request</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>cancellable</p></td> |
| <td class="parameter_description"><p> optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>callback</p></td> |
| <td class="parameter_description"><p> callback to call when the request is satisfied. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>user_data</p></td> |
| <td class="parameter_description"><p> the data to pass to callback function. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-44.html#api-index-2.44">2.44</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-read-all-finish"></a><h3>g_input_stream_read_all_finish ()</h3> |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| g_input_stream_read_all_finish (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *result</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> *bytes_read</code></em>, |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> |
| <p>Finishes an asynchronous stream read operation started with |
| <a class="link" href="GInputStream.html#g-input-stream-read-all-async" title="g_input_stream_read_all_async ()"><code class="function">g_input_stream_read_all_async()</code></a>.</p> |
| <p>As a special exception to the normal conventions for functions that |
| use <a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, if this function returns <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> (and sets <em class="parameter"><code>error</code></em> |
| ) then |
| <em class="parameter"><code>bytes_read</code></em> |
| will be set to the number of bytes that were successfully |
| read before the error was encountered. This functionality is only |
| available from C. If you need it from another language then you must |
| write your own loop around <a class="link" href="GInputStream.html#g-input-stream-read-async" title="g_input_stream_read_async ()"><code class="function">g_input_stream_read_async()</code></a>.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-read-all-finish.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>result</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>bytes_read</p></td> |
| <td class="parameter_description"><p> location to store the number of bytes that was read from the stream. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>error</p></td> |
| <td class="parameter_description"><p>a <a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> location to store the error occurring, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-input-stream-read-all-finish.returns"></a><h4>Returns</h4> |
| <p> <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> on success, <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if there was an error</p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-44.html#api-index-2.44">2.44</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-skip"></a><h3>g_input_stream_skip ()</h3> |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gssize"><span class="returnvalue">gssize</span></a> |
| g_input_stream_skip (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> count</code></em>, |
| <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> |
| <p>Tries to skip <em class="parameter"><code>count</code></em> |
| bytes from the stream. Will block during the operation.</p> |
| <p>This is identical to <a class="link" href="GInputStream.html#g-input-stream-read" title="g_input_stream_read ()"><code class="function">g_input_stream_read()</code></a>, 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.</p> |
| <p>This function is optional for inherited classes, as the default implementation |
| emulates it using read.</p> |
| <p>If <em class="parameter"><code>cancellable</code></em> |
| is not <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, then the operation can be cancelled by |
| triggering the cancellable object from another thread. If the operation |
| was cancelled, the error <a class="link" href="gio-GIOError.html#G-IO-ERROR-CANCELLED:CAPS"><code class="literal">G_IO_ERROR_CANCELLED</code></a> will be returned. If an |
| operation was partially finished when the operation was cancelled the |
| partial result will be returned, without an error.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-skip.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>count</p></td> |
| <td class="parameter_description"><p>the number of bytes that will be skipped from the stream</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>cancellable</p></td> |
| <td class="parameter_description"><p> optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>error</p></td> |
| <td class="parameter_description"><p>location to store the error occurring, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-input-stream-skip.returns"></a><h4>Returns</h4> |
| <p> Number of bytes skipped, or -1 on error</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-close"></a><h3>g_input_stream_close ()</h3> |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| g_input_stream_close (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> |
| <p>Closes the stream, releasing resources related to it.</p> |
| <p>Once the stream is closed, all other operations will return <a class="link" href="gio-GIOError.html#G-IO-ERROR-CLOSED:CAPS"><code class="literal">G_IO_ERROR_CLOSED</code></a>. |
| Closing a stream multiple times will not return an error.</p> |
| <p>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.</p> |
| <p>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.</p> |
| <p>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 <a class="link" href="gio-GIOError.html#G-IO-ERROR-CLOSED:CAPS"><code class="literal">G_IO_ERROR_CLOSED</code></a> for all operations. Still, it |
| is important to check and report the error to the user.</p> |
| <p>If <em class="parameter"><code>cancellable</code></em> |
| is not <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, then the operation can be cancelled by |
| triggering the cancellable object from another thread. If the operation |
| was cancelled, the error <a class="link" href="gio-GIOError.html#G-IO-ERROR-CANCELLED:CAPS"><code class="literal">G_IO_ERROR_CANCELLED</code></a> 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.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-close.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>A <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>cancellable</p></td> |
| <td class="parameter_description"><p> optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>error</p></td> |
| <td class="parameter_description"><p>location to store the error occurring, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-input-stream-close.returns"></a><h4>Returns</h4> |
| <p> <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> on success, <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> on failure</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-read-async"></a><h3>g_input_stream_read_async ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| g_input_stream_read_async (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><span class="type">void</span> *buffer</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> count</code></em>, |
| <em class="parameter"><code><span class="type">int</span> io_priority</code></em>, |
| <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, |
| <em class="parameter"><code><a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> callback</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> |
| <p>Request an asynchronous read of <em class="parameter"><code>count</code></em> |
| bytes from the stream into the buffer |
| starting at <em class="parameter"><code>buffer</code></em> |
| . When the operation is finished <em class="parameter"><code>callback</code></em> |
| will be called. |
| You can then call <a class="link" href="GInputStream.html#g-input-stream-read-finish" title="g_input_stream_read_finish ()"><code class="function">g_input_stream_read_finish()</code></a> to get the result of the |
| operation.</p> |
| <p>During an async request no other sync and async calls are allowed on <em class="parameter"><code>stream</code></em> |
| , and will |
| result in <a class="link" href="gio-GIOError.html#G-IO-ERROR-PENDING:CAPS"><code class="literal">G_IO_ERROR_PENDING</code></a> errors. </p> |
| <p>A value of <em class="parameter"><code>count</code></em> |
| larger than <a href="../glib-Basic-Types.html#G-MAXSSIZE:CAPS"><code class="literal">G_MAXSSIZE</code></a> will cause a <a class="link" href="gio-GIOError.html#G-IO-ERROR-INVALID-ARGUMENT:CAPS"><code class="literal">G_IO_ERROR_INVALID_ARGUMENT</code></a> error.</p> |
| <p>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 <em class="parameter"><code>count</code></em> |
| is zero), but never otherwise.</p> |
| <p>Any outstanding i/o request with higher priority (lower numerical value) will |
| be executed before an outstanding request with lower priority. Default |
| priority is <a href="../glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT:CAPS"><code class="literal">G_PRIORITY_DEFAULT</code></a>.</p> |
| <p>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.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-read-async.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>A <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>buffer</p></td> |
| <td class="parameter_description"><p> a buffer to |
| read data into (which should be at least count bytes long). </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=count][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> guint8]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>count</p></td> |
| <td class="parameter_description"><p>the number of bytes that will be read from the stream</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>io_priority</p></td> |
| <td class="parameter_description"><p>the <a class="link" href="GAsyncResult.html#io-priority" title="I/O Priority">I/O priority</a> |
| of the request. </p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>cancellable</p></td> |
| <td class="parameter_description"><p> optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>callback</p></td> |
| <td class="parameter_description"><p> callback to call when the request is satisfied. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>user_data</p></td> |
| <td class="parameter_description"><p> the data to pass to callback function. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-read-finish"></a><h3>g_input_stream_read_finish ()</h3> |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gssize"><span class="returnvalue">gssize</span></a> |
| g_input_stream_read_finish (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *result</code></em>, |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> |
| <p>Finishes an asynchronous stream read operation.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-read-finish.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>result</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>error</p></td> |
| <td class="parameter_description"><p>a <a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> location to store the error occurring, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to |
| ignore.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-input-stream-read-finish.returns"></a><h4>Returns</h4> |
| <p> number of bytes read in, or -1 on error, or 0 on end of file.</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-skip-async"></a><h3>g_input_stream_skip_async ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| g_input_stream_skip_async (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> count</code></em>, |
| <em class="parameter"><code><span class="type">int</span> io_priority</code></em>, |
| <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, |
| <em class="parameter"><code><a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> callback</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> |
| <p>Request an asynchronous skip of <em class="parameter"><code>count</code></em> |
| bytes from the stream. |
| When the operation is finished <em class="parameter"><code>callback</code></em> |
| will be called. |
| You can then call <a class="link" href="GInputStream.html#g-input-stream-skip-finish" title="g_input_stream_skip_finish ()"><code class="function">g_input_stream_skip_finish()</code></a> to get the result |
| of the operation.</p> |
| <p>During an async request no other sync and async calls are allowed, |
| and will result in <a class="link" href="gio-GIOError.html#G-IO-ERROR-PENDING:CAPS"><code class="literal">G_IO_ERROR_PENDING</code></a> errors.</p> |
| <p>A value of <em class="parameter"><code>count</code></em> |
| larger than <a href="../glib-Basic-Types.html#G-MAXSSIZE:CAPS"><code class="literal">G_MAXSSIZE</code></a> will cause a <a class="link" href="gio-GIOError.html#G-IO-ERROR-INVALID-ARGUMENT:CAPS"><code class="literal">G_IO_ERROR_INVALID_ARGUMENT</code></a> error.</p> |
| <p>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 <em class="parameter"><code>count</code></em> |
| is zero), but never otherwise.</p> |
| <p>Any outstanding i/o request with higher priority (lower numerical value) |
| will be executed before an outstanding request with lower priority. |
| Default priority is <a href="../glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT:CAPS"><code class="literal">G_PRIORITY_DEFAULT</code></a>.</p> |
| <p>The asynchronous 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.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-skip-async.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>A <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>count</p></td> |
| <td class="parameter_description"><p>the number of bytes that will be skipped from the stream</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>io_priority</p></td> |
| <td class="parameter_description"><p>the <a class="link" href="GAsyncResult.html#io-priority" title="I/O Priority">I/O priority</a> of the request</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>cancellable</p></td> |
| <td class="parameter_description"><p> optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>callback</p></td> |
| <td class="parameter_description"><p> callback to call when the request is satisfied. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>user_data</p></td> |
| <td class="parameter_description"><p> the data to pass to callback function. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-skip-finish"></a><h3>g_input_stream_skip_finish ()</h3> |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gssize"><span class="returnvalue">gssize</span></a> |
| g_input_stream_skip_finish (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *result</code></em>, |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> |
| <p>Finishes a stream skip operation.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-skip-finish.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>result</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>error</p></td> |
| <td class="parameter_description"><p>a <a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> location to store the error occurring, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to |
| ignore.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-input-stream-skip-finish.returns"></a><h4>Returns</h4> |
| <p> the size of the bytes skipped, or <code class="literal">-1</code> on error.</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-close-async"></a><h3>g_input_stream_close_async ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| g_input_stream_close_async (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><span class="type">int</span> io_priority</code></em>, |
| <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, |
| <em class="parameter"><code><a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> callback</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> |
| <p>Requests an asynchronous closes of the stream, releasing resources related to it. |
| When the operation is finished <em class="parameter"><code>callback</code></em> |
| will be called. |
| You can then call <a class="link" href="GInputStream.html#g-input-stream-close-finish" title="g_input_stream_close_finish ()"><code class="function">g_input_stream_close_finish()</code></a> to get the result of the |
| operation.</p> |
| <p>For behaviour details see <a class="link" href="GInputStream.html#g-input-stream-close" title="g_input_stream_close ()"><code class="function">g_input_stream_close()</code></a>.</p> |
| <p>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.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-close-async.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>A <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>io_priority</p></td> |
| <td class="parameter_description"><p>the <a class="link" href="GAsyncResult.html#io-priority" title="I/O Priority">I/O priority</a> of the request</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>cancellable</p></td> |
| <td class="parameter_description"><p> optional cancellable object. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>callback</p></td> |
| <td class="parameter_description"><p> callback to call when the request is satisfied. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>user_data</p></td> |
| <td class="parameter_description"><p> the data to pass to callback function. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-close-finish"></a><h3>g_input_stream_close_finish ()</h3> |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| g_input_stream_close_finish (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *result</code></em>, |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> |
| <p>Finishes closing a stream asynchronously, started from <a class="link" href="GInputStream.html#g-input-stream-close-async" title="g_input_stream_close_async ()"><code class="function">g_input_stream_close_async()</code></a>.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-close-finish.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>result</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>error</p></td> |
| <td class="parameter_description"><p>a <a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> location to store the error occurring, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to |
| ignore.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-input-stream-close-finish.returns"></a><h4>Returns</h4> |
| <p> <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the stream was closed successfully.</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-is-closed"></a><h3>g_input_stream_is_closed ()</h3> |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| g_input_stream_is_closed (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>);</pre> |
| <p>Checks if an input stream is closed.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-is-closed.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>input stream.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-input-stream-is-closed.returns"></a><h4>Returns</h4> |
| <p> <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the stream is closed.</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-has-pending"></a><h3>g_input_stream_has_pending ()</h3> |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| g_input_stream_has_pending (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>);</pre> |
| <p>Checks if an input stream has pending actions.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-has-pending.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>input stream.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-input-stream-has-pending.returns"></a><h4>Returns</h4> |
| <p> <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>stream</code></em> |
| has pending actions.</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-set-pending"></a><h3>g_input_stream_set_pending ()</h3> |
| <pre class="programlisting"><a href="../glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> |
| g_input_stream_set_pending (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> |
| <p>Sets <em class="parameter"><code>stream</code></em> |
| to have actions pending. If the pending flag is |
| already set or <em class="parameter"><code>stream</code></em> |
| is closed, it will return <a href="../glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> and set |
| <em class="parameter"><code>error</code></em> |
| .</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-set-pending.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>input stream</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>error</p></td> |
| <td class="parameter_description"><p>a <a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> location to store the error occurring, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to |
| ignore.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-input-stream-set-pending.returns"></a><h4>Returns</h4> |
| <p> <a href="../glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if pending was previously unset and is now set.</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-clear-pending"></a><h3>g_input_stream_clear_pending ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| g_input_stream_clear_pending (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>);</pre> |
| <p>Clears the pending flag on <em class="parameter"><code>stream</code></em> |
| .</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-clear-pending.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>input stream</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-read-bytes"></a><h3>g_input_stream_read_bytes ()</h3> |
| <pre class="programlisting"><a href="../glib-Byte-Arrays.html#GBytes"><span class="returnvalue">GBytes</span></a> * |
| g_input_stream_read_bytes (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> count</code></em>, |
| <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> |
| <p>Like <a class="link" href="GInputStream.html#g-input-stream-read" title="g_input_stream_read ()"><code class="function">g_input_stream_read()</code></a>, this tries to read <em class="parameter"><code>count</code></em> |
| bytes from |
| the stream in a blocking fashion. However, rather than reading into |
| a user-supplied buffer, this will create a new <a href="../glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a> containing |
| the data that was read. This may be easier to use from language |
| bindings.</p> |
| <p>If count is zero, returns a zero-length <a href="../glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a> and does nothing. A |
| value of <em class="parameter"><code>count</code></em> |
| larger than <a href="../glib-Basic-Types.html#G-MAXSSIZE:CAPS"><code class="literal">G_MAXSSIZE</code></a> will cause a |
| <a class="link" href="gio-GIOError.html#G-IO-ERROR-INVALID-ARGUMENT:CAPS"><code class="literal">G_IO_ERROR_INVALID_ARGUMENT</code></a> error.</p> |
| <p>On success, a new <a href="../glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a> is returned. It is not an error if the |
| size of this object is not the same as the requested size, as it |
| can happen e.g. near the end of a file. A zero-length <a href="../glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a> is |
| returned on end of file (or if <em class="parameter"><code>count</code></em> |
| is zero), but never |
| otherwise.</p> |
| <p>If <em class="parameter"><code>cancellable</code></em> |
| is not <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, then the operation can be cancelled by |
| triggering the cancellable object from another thread. If the operation |
| was cancelled, the error <a class="link" href="gio-GIOError.html#G-IO-ERROR-CANCELLED:CAPS"><code class="literal">G_IO_ERROR_CANCELLED</code></a> will be returned. If an |
| operation was partially finished when the operation was cancelled the |
| partial result will be returned, without an error.</p> |
| <p>On error <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> is returned and <em class="parameter"><code>error</code></em> |
| is set accordingly.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-read-bytes.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>count</p></td> |
| <td class="parameter_description"><p>maximum number of bytes that will be read from the stream. Common |
| values include 4096 and 8192.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>cancellable</p></td> |
| <td class="parameter_description"><p> optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>error</p></td> |
| <td class="parameter_description"><p>location to store the error occurring, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-input-stream-read-bytes.returns"></a><h4>Returns</h4> |
| <p> a new <a href="../glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a>, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error</p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-34.html#api-index-2.34">2.34</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-read-bytes-async"></a><h3>g_input_stream_read_bytes_async ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| g_input_stream_read_bytes_async (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> count</code></em>, |
| <em class="parameter"><code><span class="type">int</span> io_priority</code></em>, |
| <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, |
| <em class="parameter"><code><a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> callback</code></em>, |
| <em class="parameter"><code><a href="../glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> |
| <p>Request an asynchronous read of <em class="parameter"><code>count</code></em> |
| bytes from the stream into a |
| new <a href="../glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a>. When the operation is finished <em class="parameter"><code>callback</code></em> |
| will be |
| called. You can then call <a class="link" href="GInputStream.html#g-input-stream-read-bytes-finish" title="g_input_stream_read_bytes_finish ()"><code class="function">g_input_stream_read_bytes_finish()</code></a> to get the |
| result of the operation.</p> |
| <p>During an async request no other sync and async calls are allowed |
| on <em class="parameter"><code>stream</code></em> |
| , and will result in <a class="link" href="gio-GIOError.html#G-IO-ERROR-PENDING:CAPS"><code class="literal">G_IO_ERROR_PENDING</code></a> errors.</p> |
| <p>A value of <em class="parameter"><code>count</code></em> |
| larger than <a href="../glib-Basic-Types.html#G-MAXSSIZE:CAPS"><code class="literal">G_MAXSSIZE</code></a> will cause a |
| <a class="link" href="gio-GIOError.html#G-IO-ERROR-INVALID-ARGUMENT:CAPS"><code class="literal">G_IO_ERROR_INVALID_ARGUMENT</code></a> error.</p> |
| <p>On success, the new <a href="../glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a> will be passed to the callback. It is |
| not an error if this is smaller than 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 |
| <em class="parameter"><code>count</code></em> |
| is zero), but never otherwise.</p> |
| <p>Any outstanding I/O request with higher priority (lower numerical |
| value) will be executed before an outstanding request with lower |
| priority. Default priority is <a href="../glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT:CAPS"><code class="literal">G_PRIORITY_DEFAULT</code></a>.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-read-bytes-async.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>A <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>count</p></td> |
| <td class="parameter_description"><p>the number of bytes that will be read from the stream</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>io_priority</p></td> |
| <td class="parameter_description"><p>the <a class="link" href="GAsyncResult.html#io-priority" title="I/O Priority">I/O priority</a> of the request</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>cancellable</p></td> |
| <td class="parameter_description"><p> optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>callback</p></td> |
| <td class="parameter_description"><p> callback to call when the request is satisfied. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>user_data</p></td> |
| <td class="parameter_description"><p> the data to pass to callback function. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-34.html#api-index-2.34">2.34</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-input-stream-read-bytes-finish"></a><h3>g_input_stream_read_bytes_finish ()</h3> |
| <pre class="programlisting"><a href="../glib-Byte-Arrays.html#GBytes"><span class="returnvalue">GBytes</span></a> * |
| g_input_stream_read_bytes_finish (<em class="parameter"><code><a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a> *stream</code></em>, |
| <em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *result</code></em>, |
| <em class="parameter"><code><a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> |
| <p>Finishes an asynchronous stream read-into-<a href="../glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a> operation.</p> |
| <div class="refsect3"> |
| <a name="g-input-stream-read-bytes-finish.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>stream</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>result</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>error</p></td> |
| <td class="parameter_description"><p>a <a href="../glib-Error-Reporting.html#GError"><span class="type">GError</span></a> location to store the error occurring, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to |
| ignore.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-input-stream-read-bytes-finish.returns"></a><h4>Returns</h4> |
| <p> the newly-allocated <a href="../glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a>, or <a href="../glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error</p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-34.html#api-index-2.34">2.34</a></p> |
| </div> |
| </div> |
| <div class="refsect1"> |
| <a name="GInputStream.other_details"></a><h2>Types and Values</h2> |
| <div class="refsect2"> |
| <a name="GInputStream-struct"></a><h3>GInputStream</h3> |
| <pre class="programlisting">typedef struct _GInputStream GInputStream;</pre> |
| <p>Base class for streaming input operations.</p> |
| </div> |
| </div> |
| </div> |
| <div class="footer"> |
| <hr>Generated by GTK-Doc V1.25.1</div> |
| </body> |
| </html> |