glib2.0_2.20.1
[mer:glib2_0.git] / docs / reference / gio / xml / ginputstream.xml
1 <?xml version="1.0"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4 <!ENTITY version SYSTEM "version.xml">
5 ]>
6 <refentry id="GInputStream">
7 <refmeta>
8 <refentrytitle role="top_of_page" id="GInputStream.top_of_page">GInputStream</refentrytitle>
9 <manvolnum>3</manvolnum>
10 <refmiscinfo>GIO Library</refmiscinfo>
11 </refmeta>
12
13 <refnamediv>
14 <refname>GInputStream</refname>
15 <refpurpose>Base class for implementing streaming input</refpurpose>
16 </refnamediv>
17
18 <refsynopsisdiv id="GInputStream.synopsis" role="synopsis">
19 <title role="synopsis.title">Synopsis</title>
20
21 <synopsis>
22
23 #include &lt;gio/gio.h&gt;
24
25                     <link linkend="GInputStream-struct">GInputStream</link>;
26 <link linkend="gssize">gssize</link>              <link linkend="g-input-stream-read">g_input_stream_read</link>                 (<link linkend="GInputStream">GInputStream</link> *stream,
27                                                          <link linkend="void">void</link> *buffer,
28                                                          <link linkend="gsize">gsize</link> count,
29                                                          <link linkend="GCancellable">GCancellable</link> *cancellable,
30                                                          <link linkend="GError">GError</link> **error);
31 <link linkend="gboolean">gboolean</link>            <link linkend="g-input-stream-read-all">g_input_stream_read_all</link>             (<link linkend="GInputStream">GInputStream</link> *stream,
32                                                          <link linkend="void">void</link> *buffer,
33                                                          <link linkend="gsize">gsize</link> count,
34                                                          <link linkend="gsize">gsize</link> *bytes_read,
35                                                          <link linkend="GCancellable">GCancellable</link> *cancellable,
36                                                          <link linkend="GError">GError</link> **error);
37 <link linkend="gssize">gssize</link>              <link linkend="g-input-stream-skip">g_input_stream_skip</link>                 (<link linkend="GInputStream">GInputStream</link> *stream,
38                                                          <link linkend="gsize">gsize</link> count,
39                                                          <link linkend="GCancellable">GCancellable</link> *cancellable,
40                                                          <link linkend="GError">GError</link> **error);
41 <link linkend="gboolean">gboolean</link>            <link linkend="g-input-stream-close">g_input_stream_close</link>                (<link linkend="GInputStream">GInputStream</link> *stream,
42                                                          <link linkend="GCancellable">GCancellable</link> *cancellable,
43                                                          <link linkend="GError">GError</link> **error);
44 <link linkend="void">void</link>                <link linkend="g-input-stream-read-async">g_input_stream_read_async</link>           (<link linkend="GInputStream">GInputStream</link> *stream,
45                                                          <link linkend="void">void</link> *buffer,
46                                                          <link linkend="gsize">gsize</link> count,
47                                                          <link linkend="int">int</link> io_priority,
48                                                          <link linkend="GCancellable">GCancellable</link> *cancellable,
49                                                          <link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
50                                                          <link linkend="gpointer">gpointer</link> user_data);
51 <link linkend="gssize">gssize</link>              <link linkend="g-input-stream-read-finish">g_input_stream_read_finish</link>          (<link linkend="GInputStream">GInputStream</link> *stream,
52                                                          <link linkend="GAsyncResult">GAsyncResult</link> *result,
53                                                          <link linkend="GError">GError</link> **error);
54 <link linkend="void">void</link>                <link linkend="g-input-stream-skip-async">g_input_stream_skip_async</link>           (<link linkend="GInputStream">GInputStream</link> *stream,
55                                                          <link linkend="gsize">gsize</link> count,
56                                                          <link linkend="int">int</link> io_priority,
57                                                          <link linkend="GCancellable">GCancellable</link> *cancellable,
58                                                          <link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
59                                                          <link linkend="gpointer">gpointer</link> user_data);
60 <link linkend="gssize">gssize</link>              <link linkend="g-input-stream-skip-finish">g_input_stream_skip_finish</link>          (<link linkend="GInputStream">GInputStream</link> *stream,
61                                                          <link linkend="GAsyncResult">GAsyncResult</link> *result,
62                                                          <link linkend="GError">GError</link> **error);
63 <link linkend="void">void</link>                <link linkend="g-input-stream-close-async">g_input_stream_close_async</link>          (<link linkend="GInputStream">GInputStream</link> *stream,
64                                                          <link linkend="int">int</link> io_priority,
65                                                          <link linkend="GCancellable">GCancellable</link> *cancellable,
66                                                          <link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
67                                                          <link linkend="gpointer">gpointer</link> user_data);
68 <link linkend="gboolean">gboolean</link>            <link linkend="g-input-stream-close-finish">g_input_stream_close_finish</link>         (<link linkend="GInputStream">GInputStream</link> *stream,
69                                                          <link linkend="GAsyncResult">GAsyncResult</link> *result,
70                                                          <link linkend="GError">GError</link> **error);
71 <link linkend="gboolean">gboolean</link>            <link linkend="g-input-stream-is-closed">g_input_stream_is_closed</link>            (<link linkend="GInputStream">GInputStream</link> *stream);
72 <link linkend="gboolean">gboolean</link>            <link linkend="g-input-stream-has-pending">g_input_stream_has_pending</link>          (<link linkend="GInputStream">GInputStream</link> *stream);
73 <link linkend="gboolean">gboolean</link>            <link linkend="g-input-stream-set-pending">g_input_stream_set_pending</link>          (<link linkend="GInputStream">GInputStream</link> *stream,
74                                                          <link linkend="GError">GError</link> **error);
75 <link linkend="void">void</link>                <link linkend="g-input-stream-clear-pending">g_input_stream_clear_pending</link>        (<link linkend="GInputStream">GInputStream</link> *stream);
76 </synopsis>
77 </refsynopsisdiv>
78
79 <refsect1 id="GInputStream.object-hierarchy" role="object_hierarchy">
80 <title role="object_hierarchy.title">Object Hierarchy</title>
81 <synopsis>
82   <link linkend="GObject">GObject</link>
83    +----GInputStream
84          +----<link linkend="GFilterInputStream">GFilterInputStream</link>
85          +----<link linkend="GFileInputStream">GFileInputStream</link>
86          +----<link linkend="GMemoryInputStream">GMemoryInputStream</link>
87          +----<link linkend="GUnixInputStream">GUnixInputStream</link>
88 </synopsis>
89 </refsect1>
90
91
92
93
94
95
96
97
98 <refsect1 id="GInputStream.description" role="desc">
99 <title role="desc.title">Description</title>
100 <para>
101 GInputStream has functions to read from a stream (<link linkend="g-input-stream-read"><function>g_input_stream_read()</function></link>),
102 to close a stream (<link linkend="g-input-stream-close"><function>g_input_stream_close()</function></link>) and to skip some content
103 (<link linkend="g-input-stream-skip"><function>g_input_stream_skip()</function></link>). 
104 </para>
105 <para>
106 To copy the content of an input stream to an output stream without 
107 manually handling the reads and writes, use <link linkend="g-output-stream-splice"><function>g_output_stream_splice()</function></link>. 
108 </para>
109 <para>
110 All of these functions have async variants too.</para>
111 <para>
112 </para>
113 </refsect1>
114
115 <refsect1 id="GInputStream.details" role="details">
116 <title role="details.title">Details</title>
117 <refsect2 id="GInputStream-struct" role="struct">
118 <title>GInputStream</title>
119 <indexterm zone="GInputStream-struct"><primary sortas="InputStream">GInputStream</primary></indexterm><programlisting>typedef struct _GInputStream GInputStream;</programlisting>
120 <para>
121 Base class for streaming input operations.</para>
122 <para>
123 </para></refsect2>
124 <refsect2 id="g-input-stream-read" role="function">
125 <title>g_input_stream_read ()</title>
126 <indexterm zone="g-input-stream-read"><primary sortas="input_stream_read">g_input_stream_read</primary></indexterm><programlisting><link linkend="gssize">gssize</link>              g_input_stream_read                 (<link linkend="GInputStream">GInputStream</link> *stream,
127                                                          <link linkend="void">void</link> *buffer,
128                                                          <link linkend="gsize">gsize</link> count,
129                                                          <link linkend="GCancellable">GCancellable</link> *cancellable,
130                                                          <link linkend="GError">GError</link> **error);</programlisting>
131 <para>
132 Tries to read <parameter>count</parameter> bytes from the stream into the buffer starting at
133 <parameter>buffer</parameter>. Will block during this read.
134 </para>
135 <para>
136 If count is zero returns zero and does nothing. A value of <parameter>count</parameter>
137 larger than <link linkend="G-MAXSSIZE--CAPS"><literal>G_MAXSSIZE</literal></link> will cause a <link linkend="G-IO-ERROR-INVALID-ARGUMENT--CAPS"><literal>G_IO_ERROR_INVALID_ARGUMENT</literal></link> error.
138 </para>
139 <para>
140 On success, the number of bytes read into the buffer is returned.
141 It is not an error if this is not the same as the requested size, as it
142 can happen e.g. near the end of a file. Zero is returned on end of file
143 (or if <parameter>count</parameter> is zero),  but never otherwise.
144 </para>
145 <para>
146 If <parameter>cancellable</parameter> is not NULL, then the operation can be cancelled by
147 triggering the cancellable object from another thread. If the operation
148 was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an
149 operation was partially finished when the operation was cancelled the
150 partial result will be returned, without an error.
151 </para>
152 <para>
153 On error -1 is returned and <parameter>error</parameter> is set accordingly.</para>
154 <para>
155 </para><variablelist role="params">
156 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
157 <listitem><simpara> a <link linkend="GInputStream"><type>GInputStream</type></link>.
158 </simpara></listitem></varlistentry>
159 <varlistentry><term><parameter>buffer</parameter>&#160;:</term>
160 <listitem><simpara> a buffer to read data into (which should be at least count bytes long).
161 </simpara></listitem></varlistentry>
162 <varlistentry><term><parameter>count</parameter>&#160;:</term>
163 <listitem><simpara> the number of bytes that will be read from the stream
164 </simpara></listitem></varlistentry>
165 <varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
166 <listitem><simpara> optional <link linkend="GCancellable"><type>GCancellable</type></link> object, <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore.
167 </simpara></listitem></varlistentry>
168 <varlistentry><term><parameter>error</parameter>&#160;:</term>
169 <listitem><simpara> location to store the error occuring, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore
170 </simpara></listitem></varlistentry>
171 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> Number of bytes read, or -1 on error
172 </simpara></listitem></varlistentry>
173 </variablelist></refsect2>
174 <refsect2 id="g-input-stream-read-all" role="function">
175 <title>g_input_stream_read_all ()</title>
176 <indexterm zone="g-input-stream-read-all"><primary sortas="input_stream_read_all">g_input_stream_read_all</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_input_stream_read_all             (<link linkend="GInputStream">GInputStream</link> *stream,
177                                                          <link linkend="void">void</link> *buffer,
178                                                          <link linkend="gsize">gsize</link> count,
179                                                          <link linkend="gsize">gsize</link> *bytes_read,
180                                                          <link linkend="GCancellable">GCancellable</link> *cancellable,
181                                                          <link linkend="GError">GError</link> **error);</programlisting>
182 <para>
183 Tries to read <parameter>count</parameter> bytes from the stream into the buffer starting at
184 <parameter>buffer</parameter>. Will block during this read.
185 </para>
186 <para>
187 This function is similar to <link linkend="g-input-stream-read"><function>g_input_stream_read()</function></link>, except it tries to
188 read as many bytes as requested, only stopping on an error or end of stream.
189 </para>
190 <para>
191 On a successful read of <parameter>count</parameter> bytes, or if we reached the end of the
192 stream,  <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> is returned, and <parameter>bytes_read</parameter> is set to the number of bytes
193 read into <parameter>buffer</parameter>.
194 </para>
195 <para>
196 If there is an error during the operation <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> is returned and <parameter>error</parameter>
197 is set to indicate the error status, <parameter>bytes_read</parameter> is updated to contain
198 the number of bytes read into <parameter>buffer</parameter> before the error occurred.</para>
199 <para>
200 </para><variablelist role="params">
201 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
202 <listitem><simpara> a <link linkend="GInputStream"><type>GInputStream</type></link>.
203 </simpara></listitem></varlistentry>
204 <varlistentry><term><parameter>buffer</parameter>&#160;:</term>
205 <listitem><simpara> a buffer to read data into (which should be at least count bytes long).
206 </simpara></listitem></varlistentry>
207 <varlistentry><term><parameter>count</parameter>&#160;:</term>
208 <listitem><simpara> the number of bytes that will be read from the stream
209 </simpara></listitem></varlistentry>
210 <varlistentry><term><parameter>bytes_read</parameter>&#160;:</term>
211 <listitem><simpara> location to store the number of bytes that was read from the stream
212 </simpara></listitem></varlistentry>
213 <varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
214 <listitem><simpara> optional <link linkend="GCancellable"><type>GCancellable</type></link> object, <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore.
215 </simpara></listitem></varlistentry>
216 <varlistentry><term><parameter>error</parameter>&#160;:</term>
217 <listitem><simpara> location to store the error occuring, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore
218 </simpara></listitem></varlistentry>
219 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if there was an error
220 </simpara></listitem></varlistentry>
221 </variablelist></refsect2>
222 <refsect2 id="g-input-stream-skip" role="function">
223 <title>g_input_stream_skip ()</title>
224 <indexterm zone="g-input-stream-skip"><primary sortas="input_stream_skip">g_input_stream_skip</primary></indexterm><programlisting><link linkend="gssize">gssize</link>              g_input_stream_skip                 (<link linkend="GInputStream">GInputStream</link> *stream,
225                                                          <link linkend="gsize">gsize</link> count,
226                                                          <link linkend="GCancellable">GCancellable</link> *cancellable,
227                                                          <link linkend="GError">GError</link> **error);</programlisting>
228 <para>
229 Tries to skip <parameter>count</parameter> bytes from the stream. Will block during the operation.
230 </para>
231 <para>
232 This is identical to <link linkend="g-input-stream-read"><function>g_input_stream_read()</function></link>, from a behaviour standpoint,
233 but the bytes that are skipped are not returned to the user. Some
234 streams have an implementation that is more efficient than reading the data.
235 </para>
236 <para>
237 This function is optional for inherited classes, as the default implementation
238 emulates it using read.
239 </para>
240 <para>
241 If <parameter>cancellable</parameter> is not <link linkend="NULL--CAPS"><literal>NULL</literal></link>, then the operation can be cancelled by
242 triggering the cancellable object from another thread. If the operation
243 was cancelled, the error <link linkend="G-IO-ERROR-CANCELLED--CAPS"><literal>G_IO_ERROR_CANCELLED</literal></link> will be returned. If an
244 operation was partially finished when the operation was cancelled the
245 partial result will be returned, without an error.</para>
246 <para>
247 </para><variablelist role="params">
248 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
249 <listitem><simpara> a <link linkend="GInputStream"><type>GInputStream</type></link>.
250 </simpara></listitem></varlistentry>
251 <varlistentry><term><parameter>count</parameter>&#160;:</term>
252 <listitem><simpara> the number of bytes that will be skipped from the stream
253 </simpara></listitem></varlistentry>
254 <varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
255 <listitem><simpara> optional <link linkend="GCancellable"><type>GCancellable</type></link> object, <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore. 
256 </simpara></listitem></varlistentry>
257 <varlistentry><term><parameter>error</parameter>&#160;:</term>
258 <listitem><simpara> location to store the error occuring, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore
259 </simpara></listitem></varlistentry>
260 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> Number of bytes skipped, or -1 on error
261 </simpara></listitem></varlistentry>
262 </variablelist></refsect2>
263 <refsect2 id="g-input-stream-close" role="function">
264 <title>g_input_stream_close ()</title>
265 <indexterm zone="g-input-stream-close"><primary sortas="input_stream_close">g_input_stream_close</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_input_stream_close                (<link linkend="GInputStream">GInputStream</link> *stream,
266                                                          <link linkend="GCancellable">GCancellable</link> *cancellable,
267                                                          <link linkend="GError">GError</link> **error);</programlisting>
268 <para>
269 Closes the stream, releasing resources related to it.
270 </para>
271 <para>
272 Once the stream is closed, all other operations will return <link linkend="G-IO-ERROR-CLOSED--CAPS"><literal>G_IO_ERROR_CLOSED</literal></link>.
273 Closing a stream multiple times will not return an error.
274 </para>
275 <para>
276 Streams will be automatically closed when the last reference
277 is dropped, but you might want to call this function to make sure 
278 resources are released as early as possible.
279 </para>
280 <para>
281 Some streams might keep the backing store of the stream (e.g. a file descriptor)
282 open after the stream is closed. See the documentation for the individual
283 stream for details.
284 </para>
285 <para>
286 On failure the first error that happened will be reported, but the close
287 operation will finish as much as possible. A stream that failed to
288 close will still return <link linkend="G-IO-ERROR-CLOSED--CAPS"><literal>G_IO_ERROR_CLOSED</literal></link> for all operations. Still, it
289 is important to check and report the error to the user.
290 </para>
291 <para>
292 If <parameter>cancellable</parameter> is not NULL, then the operation can be cancelled by
293 triggering the cancellable object from another thread. If the operation
294 was cancelled, the error <link linkend="G-IO-ERROR-CANCELLED--CAPS"><literal>G_IO_ERROR_CANCELLED</literal></link> will be returned.
295 Cancelling a close will still leave the stream closed, but some streams
296 can use a faster close that doesn't block to e.g. check errors.</para>
297 <para>
298 </para><variablelist role="params">
299 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
300 <listitem><simpara> A <link linkend="GInputStream"><type>GInputStream</type></link>.
301 </simpara></listitem></varlistentry>
302 <varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
303 <listitem><simpara> optional <link linkend="GCancellable"><type>GCancellable</type></link> object, <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore.
304 </simpara></listitem></varlistentry>
305 <varlistentry><term><parameter>error</parameter>&#160;:</term>
306 <listitem><simpara> location to store the error occuring, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore
307 </simpara></listitem></varlistentry>
308 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> on failure
309 </simpara></listitem></varlistentry>
310 </variablelist></refsect2>
311 <refsect2 id="g-input-stream-read-async" role="function">
312 <title>g_input_stream_read_async ()</title>
313 <indexterm zone="g-input-stream-read-async"><primary sortas="input_stream_read_async">g_input_stream_read_async</primary></indexterm><programlisting><link linkend="void">void</link>                g_input_stream_read_async           (<link linkend="GInputStream">GInputStream</link> *stream,
314                                                          <link linkend="void">void</link> *buffer,
315                                                          <link linkend="gsize">gsize</link> count,
316                                                          <link linkend="int">int</link> io_priority,
317                                                          <link linkend="GCancellable">GCancellable</link> *cancellable,
318                                                          <link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
319                                                          <link linkend="gpointer">gpointer</link> user_data);</programlisting>
320 <para>
321 Request an asynchronous read of <parameter>count</parameter> bytes from the stream into the buffer
322 starting at <parameter>buffer</parameter>. When the operation is finished <parameter>callback</parameter> will be called. 
323 You can then call <link linkend="g-input-stream-read-finish"><function>g_input_stream_read_finish()</function></link> to get the result of the 
324 operation.
325 </para>
326 <para>
327 During an async request no other sync and async calls are allowed, and will
328 result in <link linkend="G-IO-ERROR-PENDING--CAPS"><literal>G_IO_ERROR_PENDING</literal></link> errors. 
329 </para>
330 <para>
331 A value of <parameter>count</parameter> larger than <link linkend="G-MAXSSIZE--CAPS"><literal>G_MAXSSIZE</literal></link> will cause a <link linkend="G-IO-ERROR-INVALID-ARGUMENT--CAPS"><literal>G_IO_ERROR_INVALID_ARGUMENT</literal></link> error.
332 </para>
333 <para>
334 On success, the number of bytes read into the buffer will be passed to the
335 callback. It is not an error if this is not the same as the requested size, as it
336 can happen e.g. near the end of a file, but generally we try to read
337 as many bytes as requested. Zero is returned on end of file
338 (or if <parameter>count</parameter> is zero),  but never otherwise.
339 </para>
340 <para>
341 Any outstanding i/o request with higher priority (lower numerical value) will
342 be executed before an outstanding request with lower priority. Default
343 priority is <link linkend="G-PRIORITY-DEFAULT--CAPS"><literal>G_PRIORITY_DEFAULT</literal></link>.
344 </para>
345 <para>
346 The asyncronous methods have a default fallback that uses threads to implement
347 asynchronicity, so they are optional for inheriting classes. However, if you
348 override one you must override all.</para>
349 <para>
350 </para><variablelist role="params">
351 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
352 <listitem><simpara> A <link linkend="GInputStream"><type>GInputStream</type></link>.
353 </simpara></listitem></varlistentry>
354 <varlistentry><term><parameter>buffer</parameter>&#160;:</term>
355 <listitem><simpara> a buffer to read data into (which should be at least count bytes long).
356 </simpara></listitem></varlistentry>
357 <varlistentry><term><parameter>count</parameter>&#160;:</term>
358 <listitem><simpara> the number of bytes that will be read from the stream
359 </simpara></listitem></varlistentry>
360 <varlistentry><term><parameter>io_priority</parameter>&#160;:</term>
361 <listitem><simpara> the <link linkend="io-priority">I/O priority</link> 
362 of the request. 
363 </simpara></listitem></varlistentry>
364 <varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
365 <listitem><simpara> optional <link linkend="GCancellable"><type>GCancellable</type></link> object, <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore.
366 </simpara></listitem></varlistentry>
367 <varlistentry><term><parameter>callback</parameter>&#160;:</term>
368 <listitem><simpara> callback to call when the request is satisfied
369 </simpara></listitem></varlistentry>
370 <varlistentry><term><parameter>user_data</parameter>&#160;:</term>
371 <listitem><simpara> the data to pass to callback function
372 </simpara></listitem></varlistentry>
373 </variablelist></refsect2>
374 <refsect2 id="g-input-stream-read-finish" role="function">
375 <title>g_input_stream_read_finish ()</title>
376 <indexterm zone="g-input-stream-read-finish"><primary sortas="input_stream_read_finish">g_input_stream_read_finish</primary></indexterm><programlisting><link linkend="gssize">gssize</link>              g_input_stream_read_finish          (<link linkend="GInputStream">GInputStream</link> *stream,
377                                                          <link linkend="GAsyncResult">GAsyncResult</link> *result,
378                                                          <link linkend="GError">GError</link> **error);</programlisting>
379 <para>
380 Finishes an asynchronous stream read operation.</para>
381 <para>
382 </para><variablelist role="params">
383 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
384 <listitem><simpara> a <link linkend="GInputStream"><type>GInputStream</type></link>.
385 </simpara></listitem></varlistentry>
386 <varlistentry><term><parameter>result</parameter>&#160;:</term>
387 <listitem><simpara> a <link linkend="GAsyncResult"><type>GAsyncResult</type></link>.
388 </simpara></listitem></varlistentry>
389 <varlistentry><term><parameter>error</parameter>&#160;:</term>
390 <listitem><simpara> a <link linkend="GError"><type>GError</type></link> location to store the error occuring, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to 
391 ignore.
392 </simpara></listitem></varlistentry>
393 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> number of bytes read in, or -1 on error.
394 </simpara></listitem></varlistentry>
395 </variablelist></refsect2>
396 <refsect2 id="g-input-stream-skip-async" role="function">
397 <title>g_input_stream_skip_async ()</title>
398 <indexterm zone="g-input-stream-skip-async"><primary sortas="input_stream_skip_async">g_input_stream_skip_async</primary></indexterm><programlisting><link linkend="void">void</link>                g_input_stream_skip_async           (<link linkend="GInputStream">GInputStream</link> *stream,
399                                                          <link linkend="gsize">gsize</link> count,
400                                                          <link linkend="int">int</link> io_priority,
401                                                          <link linkend="GCancellable">GCancellable</link> *cancellable,
402                                                          <link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
403                                                          <link linkend="gpointer">gpointer</link> user_data);</programlisting>
404 <para>
405 Request an asynchronous skip of <parameter>count</parameter> bytes from the stream into the buffer
406 starting at <parameter>buffer</parameter>. When the operation is finished <parameter>callback</parameter> will be called. 
407 You can then call <link linkend="g-input-stream-skip-finish"><function>g_input_stream_skip_finish()</function></link> to get the result of the 
408 operation.
409 </para>
410 <para>
411 During an async request no other sync and async calls are allowed, and will
412 result in <link linkend="G-IO-ERROR-PENDING--CAPS"><literal>G_IO_ERROR_PENDING</literal></link> errors. 
413 </para>
414 <para>
415 A value of <parameter>count</parameter> larger than <link linkend="G-MAXSSIZE--CAPS"><literal>G_MAXSSIZE</literal></link> will cause a <link linkend="G-IO-ERROR-INVALID-ARGUMENT--CAPS"><literal>G_IO_ERROR_INVALID_ARGUMENT</literal></link> error.
416 </para>
417 <para>
418 On success, the number of bytes skipped will be passed to the
419 callback. It is not an error if this is not the same as the requested size, as it
420 can happen e.g. near the end of a file, but generally we try to skip
421 as many bytes as requested. Zero is returned on end of file
422 (or if <parameter>count</parameter> is zero), but never otherwise.
423 </para>
424 <para>
425 Any outstanding i/o request with higher priority (lower numerical value) will
426 be executed before an outstanding request with lower priority. Default
427 priority is <link linkend="G-PRIORITY-DEFAULT--CAPS"><literal>G_PRIORITY_DEFAULT</literal></link>.
428 </para>
429 <para>
430 The asyncronous methods have a default fallback that uses threads to implement
431 asynchronicity, so they are optional for inheriting classes. However, if you
432 override one you must override all.</para>
433 <para>
434 </para><variablelist role="params">
435 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
436 <listitem><simpara> A <link linkend="GInputStream"><type>GInputStream</type></link>.
437 </simpara></listitem></varlistentry>
438 <varlistentry><term><parameter>count</parameter>&#160;:</term>
439 <listitem><simpara> the number of bytes that will be skipped from the stream
440 </simpara></listitem></varlistentry>
441 <varlistentry><term><parameter>io_priority</parameter>&#160;:</term>
442 <listitem><simpara> the <link linkend="io-priority">I/O priority</link> 
443 of the request. 
444 </simpara></listitem></varlistentry>
445 <varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
446 <listitem><simpara> optional <link linkend="GCancellable"><type>GCancellable</type></link> object, <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore. 
447 </simpara></listitem></varlistentry>
448 <varlistentry><term><parameter>callback</parameter>&#160;:</term>
449 <listitem><simpara> callback to call when the request is satisfied
450 </simpara></listitem></varlistentry>
451 <varlistentry><term><parameter>user_data</parameter>&#160;:</term>
452 <listitem><simpara> the data to pass to callback function
453 </simpara></listitem></varlistentry>
454 </variablelist></refsect2>
455 <refsect2 id="g-input-stream-skip-finish" role="function">
456 <title>g_input_stream_skip_finish ()</title>
457 <indexterm zone="g-input-stream-skip-finish"><primary sortas="input_stream_skip_finish">g_input_stream_skip_finish</primary></indexterm><programlisting><link linkend="gssize">gssize</link>              g_input_stream_skip_finish          (<link linkend="GInputStream">GInputStream</link> *stream,
458                                                          <link linkend="GAsyncResult">GAsyncResult</link> *result,
459                                                          <link linkend="GError">GError</link> **error);</programlisting>
460 <para>
461 Finishes a stream skip operation.</para>
462 <para>
463 </para><variablelist role="params">
464 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
465 <listitem><simpara> a <link linkend="GInputStream"><type>GInputStream</type></link>.
466 </simpara></listitem></varlistentry>
467 <varlistentry><term><parameter>result</parameter>&#160;:</term>
468 <listitem><simpara> a <link linkend="GAsyncResult"><type>GAsyncResult</type></link>.
469 </simpara></listitem></varlistentry>
470 <varlistentry><term><parameter>error</parameter>&#160;:</term>
471 <listitem><simpara> a <link linkend="GError"><type>GError</type></link> location to store the error occuring, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to 
472 ignore.
473 </simpara></listitem></varlistentry>
474 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the size of the bytes skipped, or <link linkend="1--CAPS"><literal>-1</literal></link> on error.
475 </simpara></listitem></varlistentry>
476 </variablelist></refsect2>
477 <refsect2 id="g-input-stream-close-async" role="function">
478 <title>g_input_stream_close_async ()</title>
479 <indexterm zone="g-input-stream-close-async"><primary sortas="input_stream_close_async">g_input_stream_close_async</primary></indexterm><programlisting><link linkend="void">void</link>                g_input_stream_close_async          (<link linkend="GInputStream">GInputStream</link> *stream,
480                                                          <link linkend="int">int</link> io_priority,
481                                                          <link linkend="GCancellable">GCancellable</link> *cancellable,
482                                                          <link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
483                                                          <link linkend="gpointer">gpointer</link> user_data);</programlisting>
484 <para>
485 Requests an asynchronous closes of the stream, releasing resources related to it.
486 When the operation is finished <parameter>callback</parameter> will be called. 
487 You can then call <link linkend="g-input-stream-close-finish"><function>g_input_stream_close_finish()</function></link> to get the result of the 
488 operation.
489 </para>
490 <para>
491 For behaviour details see <link linkend="g-input-stream-close"><function>g_input_stream_close()</function></link>.
492 </para>
493 <para>
494 The asyncronous methods have a default fallback that uses threads to implement
495 asynchronicity, so they are optional for inheriting classes. However, if you
496 override one you must override all.</para>
497 <para>
498 </para><variablelist role="params">
499 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
500 <listitem><simpara> A <link linkend="GInputStream"><type>GInputStream</type></link>.
501 </simpara></listitem></varlistentry>
502 <varlistentry><term><parameter>io_priority</parameter>&#160;:</term>
503 <listitem><simpara> the <link linkend="io-priority">I/O priority</link> 
504 of the request. 
505 </simpara></listitem></varlistentry>
506 <varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
507 <listitem><simpara> optional cancellable object
508 </simpara></listitem></varlistentry>
509 <varlistentry><term><parameter>callback</parameter>&#160;:</term>
510 <listitem><simpara> callback to call when the request is satisfied
511 </simpara></listitem></varlistentry>
512 <varlistentry><term><parameter>user_data</parameter>&#160;:</term>
513 <listitem><simpara> the data to pass to callback function
514 </simpara></listitem></varlistentry>
515 </variablelist></refsect2>
516 <refsect2 id="g-input-stream-close-finish" role="function">
517 <title>g_input_stream_close_finish ()</title>
518 <indexterm zone="g-input-stream-close-finish"><primary sortas="input_stream_close_finish">g_input_stream_close_finish</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_input_stream_close_finish         (<link linkend="GInputStream">GInputStream</link> *stream,
519                                                          <link linkend="GAsyncResult">GAsyncResult</link> *result,
520                                                          <link linkend="GError">GError</link> **error);</programlisting>
521 <para>
522 Finishes closing a stream asynchronously, started from <link linkend="g-input-stream-close-async"><function>g_input_stream_close_async()</function></link>.</para>
523 <para>
524 </para><variablelist role="params">
525 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
526 <listitem><simpara> a <link linkend="GInputStream"><type>GInputStream</type></link>.
527 </simpara></listitem></varlistentry>
528 <varlistentry><term><parameter>result</parameter>&#160;:</term>
529 <listitem><simpara> a <link linkend="GAsyncResult"><type>GAsyncResult</type></link>.
530 </simpara></listitem></varlistentry>
531 <varlistentry><term><parameter>error</parameter>&#160;:</term>
532 <listitem><simpara> a <link linkend="GError"><type>GError</type></link> location to store the error occuring, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to 
533 ignore.
534 </simpara></listitem></varlistentry>
535 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the stream was closed successfully.
536 </simpara></listitem></varlistentry>
537 </variablelist></refsect2>
538 <refsect2 id="g-input-stream-is-closed" role="function">
539 <title>g_input_stream_is_closed ()</title>
540 <indexterm zone="g-input-stream-is-closed"><primary sortas="input_stream_is_closed">g_input_stream_is_closed</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_input_stream_is_closed            (<link linkend="GInputStream">GInputStream</link> *stream);</programlisting>
541 <para>
542 Checks if an input stream is closed.</para>
543 <para>
544 </para><variablelist role="params">
545 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
546 <listitem><simpara> input stream.
547 </simpara></listitem></varlistentry>
548 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the stream is closed.
549 </simpara></listitem></varlistentry>
550 </variablelist></refsect2>
551 <refsect2 id="g-input-stream-has-pending" role="function">
552 <title>g_input_stream_has_pending ()</title>
553 <indexterm zone="g-input-stream-has-pending"><primary sortas="input_stream_has_pending">g_input_stream_has_pending</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_input_stream_has_pending          (<link linkend="GInputStream">GInputStream</link> *stream);</programlisting>
554 <para>
555 Checks if an input stream has pending actions.</para>
556 <para>
557 </para><variablelist role="params">
558 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
559 <listitem><simpara> input stream.
560 </simpara></listitem></varlistentry>
561 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>stream</parameter> has pending actions.
562 </simpara></listitem></varlistentry>
563 </variablelist></refsect2>
564 <refsect2 id="g-input-stream-set-pending" role="function">
565 <title>g_input_stream_set_pending ()</title>
566 <indexterm zone="g-input-stream-set-pending"><primary sortas="input_stream_set_pending">g_input_stream_set_pending</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_input_stream_set_pending          (<link linkend="GInputStream">GInputStream</link> *stream,
567                                                          <link linkend="GError">GError</link> **error);</programlisting>
568 <para>
569 Sets <parameter>stream</parameter> to have actions pending. If the pending flag is
570 already set or <parameter>stream</parameter> is closed, it will return <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> and set
571 <parameter>error</parameter>.</para>
572 <para>
573 </para><variablelist role="params">
574 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
575 <listitem><simpara> input stream
576 </simpara></listitem></varlistentry>
577 <varlistentry><term><parameter>error</parameter>&#160;:</term>
578 <listitem><simpara> a <link linkend="GError"><type>GError</type></link> location to store the error occuring, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to 
579 ignore.
580 </simpara></listitem></varlistentry>
581 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if pending was previously unset and is now set.
582 </simpara></listitem></varlistentry>
583 </variablelist></refsect2>
584 <refsect2 id="g-input-stream-clear-pending" role="function">
585 <title>g_input_stream_clear_pending ()</title>
586 <indexterm zone="g-input-stream-clear-pending"><primary sortas="input_stream_clear_pending">g_input_stream_clear_pending</primary></indexterm><programlisting><link linkend="void">void</link>                g_input_stream_clear_pending        (<link linkend="GInputStream">GInputStream</link> *stream);</programlisting>
587 <para>
588 Clears the pending flag on <parameter>stream</parameter>.</para>
589 <para>
590 </para><variablelist role="params">
591 <varlistentry><term><parameter>stream</parameter>&#160;:</term>
592 <listitem><simpara> input stream
593 </simpara></listitem></varlistentry>
594 </variablelist></refsect2>
595
596 </refsect1>
597
598
599
600
601 </refentry>