source: appstream-generator/build/girepo/gio/InputStream.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

File size: 22.4 KB
Line 
1/*
2 * Licensed under the GNU Lesser General Public License Version 3
3 *
4 * This library is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation, either version 3 of the license, or
7 * (at your option) any later version.
8 *
9 * This software is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
16 */
17
18// generated automatically - do not change
19
20
21module gio.InputStream;
22
23private import gi.gio;
24public  import gi.giotypes;
25private import gio.AsyncResultIF;
26private import gio.Cancellable;
27private import glib.Bytes;
28private import glib.ErrorG;
29private import glib.GException;
30private import gobject.ObjectG;
31
32
33/**
34 * #GInputStream has functions to read from a stream (g_input_stream_read()),
35 * to close a stream (g_input_stream_close()) and to skip some content
36 * (g_input_stream_skip()).
37 *
38 * To copy the content of an input stream to an output stream without
39 * manually handling the reads and writes, use g_output_stream_splice().
40 *
41 * All of these functions have async variants too.
42 */
43public class InputStream : ObjectG
44{
45        /** the main Gtk struct */
46        protected GInputStream* gInputStream;
47
48        /** Get the main Gtk struct */
49        public GInputStream* getInputStreamStruct()
50        {
51                return gInputStream;
52        }
53
54        /** the main Gtk struct as a void* */
55        protected override void* getStruct()
56        {
57                return cast(void*)gInputStream;
58        }
59
60        protected override void setStruct(GObject* obj)
61        {
62                gInputStream = cast(GInputStream*)obj;
63                super.setStruct(obj);
64        }
65
66        /**
67         * Sets our main struct and passes it to the parent class.
68         */
69        public this (GInputStream* gInputStream, bool ownedRef = false)
70        {
71                this.gInputStream = gInputStream;
72                super(cast(GObject*)gInputStream, ownedRef);
73        }
74
75
76        /** */
77        public static GType getType()
78        {
79                return g_input_stream_get_type();
80        }
81
82        /**
83         * Clears the pending flag on @stream.
84         */
85        public void clearPending()
86        {
87                g_input_stream_clear_pending(gInputStream);
88        }
89
90        /**
91         * Closes the stream, releasing resources related to it.
92         *
93         * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
94         * Closing a stream multiple times will not return an error.
95         *
96         * Streams will be automatically closed when the last reference
97         * is dropped, but you might want to call this function to make sure
98         * resources are released as early as possible.
99         *
100         * Some streams might keep the backing store of the stream (e.g. a file descriptor)
101         * open after the stream is closed. See the documentation for the individual
102         * stream for details.
103         *
104         * On failure the first error that happened will be reported, but the close
105         * operation will finish as much as possible. A stream that failed to
106         * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
107         * is important to check and report the error to the user.
108         *
109         * If @cancellable is not %NULL, then the operation can be cancelled by
110         * triggering the cancellable object from another thread. If the operation
111         * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
112         * Cancelling a close will still leave the stream closed, but some streams
113         * can use a faster close that doesn't block to e.g. check errors.
114         *
115         * Params:
116         *     cancellable = optional #GCancellable object, %NULL to ignore.
117         *
118         * Returns: %TRUE on success, %FALSE on failure
119         *
120         * Throws: GException on failure.
121         */
122        public bool close(Cancellable cancellable)
123        {
124                GError* err = null;
125               
126                auto p = g_input_stream_close(gInputStream, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0;
127               
128                if (err !is null)
129                {
130                        throw new GException( new ErrorG(err) );
131                }
132               
133                return p;
134        }
135
136        /**
137         * Requests an asynchronous closes of the stream, releasing resources related to it.
138         * When the operation is finished @callback will be called.
139         * You can then call g_input_stream_close_finish() to get the result of the
140         * operation.
141         *
142         * For behaviour details see g_input_stream_close().
143         *
144         * The asyncronous methods have a default fallback that uses threads to implement
145         * asynchronicity, so they are optional for inheriting classes. However, if you
146         * override one you must override all.
147         *
148         * Params:
149         *     ioPriority = the [I/O priority][io-priority] of the request
150         *     cancellable = optional cancellable object
151         *     callback = callback to call when the request is satisfied
152         *     userData = the data to pass to callback function
153         */
154        public void closeAsync(int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
155        {
156                g_input_stream_close_async(gInputStream, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
157        }
158
159        /**
160         * Finishes closing a stream asynchronously, started from g_input_stream_close_async().
161         *
162         * Params:
163         *     result = a #GAsyncResult.
164         *
165         * Returns: %TRUE if the stream was closed successfully.
166         *
167         * Throws: GException on failure.
168         */
169        public bool closeFinish(AsyncResultIF result)
170        {
171                GError* err = null;
172               
173                auto p = g_input_stream_close_finish(gInputStream, (result is null) ? null : result.getAsyncResultStruct(), &err) != 0;
174               
175                if (err !is null)
176                {
177                        throw new GException( new ErrorG(err) );
178                }
179               
180                return p;
181        }
182
183        /**
184         * Checks if an input stream has pending actions.
185         *
186         * Returns: %TRUE if @stream has pending actions.
187         */
188        public bool hasPending()
189        {
190                return g_input_stream_has_pending(gInputStream) != 0;
191        }
192
193        /**
194         * Checks if an input stream is closed.
195         *
196         * Returns: %TRUE if the stream is closed.
197         */
198        public bool isClosed()
199        {
200                return g_input_stream_is_closed(gInputStream) != 0;
201        }
202
203        /**
204         * Tries to read @count bytes from the stream into the buffer starting at
205         * @buffer. Will block during this read.
206         *
207         * If count is zero returns zero and does nothing. A value of @count
208         * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
209         *
210         * On success, the number of bytes read into the buffer is returned.
211         * It is not an error if this is not the same as the requested size, as it
212         * can happen e.g. near the end of a file. Zero is returned on end of file
213         * (or if @count is zero),  but never otherwise.
214         *
215         * The returned @buffer is not a nul-terminated string, it can contain nul bytes
216         * at any position, and this function doesn't nul-terminate the @buffer.
217         *
218         * If @cancellable is not %NULL, then the operation can be cancelled by
219         * triggering the cancellable object from another thread. If the operation
220         * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
221         * operation was partially finished when the operation was cancelled the
222         * partial result will be returned, without an error.
223         *
224         * On error -1 is returned and @error is set accordingly.
225         *
226         * Params:
227         *     buffer = a buffer to
228         *         read data into (which should be at least count bytes long).
229         *     count = the number of bytes that will be read from the stream
230         *     cancellable = optional #GCancellable object, %NULL to ignore.
231         *
232         * Returns: Number of bytes read, or -1 on error, or 0 on end of file.
233         *
234         * Throws: GException on failure.
235         */
236        public ptrdiff_t read(ubyte[] buffer, Cancellable cancellable)
237        {
238                GError* err = null;
239               
240                auto p = g_input_stream_read(gInputStream, buffer.ptr, cast(size_t)buffer.length, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
241               
242                if (err !is null)
243                {
244                        throw new GException( new ErrorG(err) );
245                }
246               
247                return p;
248        }
249
250        /**
251         * Tries to read @count bytes from the stream into the buffer starting at
252         * @buffer. Will block during this read.
253         *
254         * This function is similar to g_input_stream_read(), except it tries to
255         * read as many bytes as requested, only stopping on an error or end of stream.
256         *
257         * On a successful read of @count bytes, or if we reached the end of the
258         * stream,  %TRUE is returned, and @bytes_read is set to the number of bytes
259         * read into @buffer.
260         *
261         * If there is an error during the operation %FALSE is returned and @error
262         * is set to indicate the error status.
263         *
264         * As a special exception to the normal conventions for functions that
265         * use #GError, if this function returns %FALSE (and sets @error) then
266         * @bytes_read will be set to the number of bytes that were successfully
267         * read before the error was encountered.  This functionality is only
268         * available from C.  If you need it from another language then you must
269         * write your own loop around g_input_stream_read().
270         *
271         * Params:
272         *     buffer = a buffer to
273         *         read data into (which should be at least count bytes long).
274         *     count = the number of bytes that will be read from the stream
275         *     bytesRead = location to store the number of bytes that was read from the stream
276         *     cancellable = optional #GCancellable object, %NULL to ignore.
277         *
278         * Returns: %TRUE on success, %FALSE if there was an error
279         *
280         * Throws: GException on failure.
281         */
282        public bool readAll(ubyte[] buffer, out size_t bytesRead, Cancellable cancellable)
283        {
284                GError* err = null;
285               
286                auto p = g_input_stream_read_all(gInputStream, buffer.ptr, cast(size_t)buffer.length, &bytesRead, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0;
287               
288                if (err !is null)
289                {
290                        throw new GException( new ErrorG(err) );
291                }
292               
293                return p;
294        }
295
296        /**
297         * Request an asynchronous read of @count bytes from the stream into the
298         * buffer starting at @buffer.
299         *
300         * This is the asynchronous equivalent of g_input_stream_read_all().
301         *
302         * Call g_input_stream_read_all_finish() to collect the result.
303         *
304         * Any outstanding I/O request with higher priority (lower numerical
305         * value) will be executed before an outstanding request with lower
306         * priority. Default priority is %G_PRIORITY_DEFAULT.
307         *
308         * Params:
309         *     buffer = a buffer to
310         *         read data into (which should be at least count bytes long)
311         *     count = the number of bytes that will be read from the stream
312         *     ioPriority = the [I/O priority][io-priority] of the request
313         *     cancellable = optional #GCancellable object, %NULL to ignore
314         *     callback = callback to call when the request is satisfied
315         *     userData = the data to pass to callback function
316         *
317         * Since: 2.44
318         */
319        public void readAllAsync(ubyte[] buffer, int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
320        {
321                g_input_stream_read_all_async(gInputStream, buffer.ptr, cast(size_t)buffer.length, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
322        }
323
324        /**
325         * Finishes an asynchronous stream read operation started with
326         * g_input_stream_read_all_async().
327         *
328         * As a special exception to the normal conventions for functions that
329         * use #GError, if this function returns %FALSE (and sets @error) then
330         * @bytes_read will be set to the number of bytes that were successfully
331         * read before the error was encountered.  This functionality is only
332         * available from C.  If you need it from another language then you must
333         * write your own loop around g_input_stream_read_async().
334         *
335         * Params:
336         *     result = a #GAsyncResult
337         *     bytesRead = location to store the number of bytes that was read from the stream
338         *
339         * Returns: %TRUE on success, %FALSE if there was an error
340         *
341         * Since: 2.44
342         *
343         * Throws: GException on failure.
344         */
345        public bool readAllFinish(AsyncResultIF result, out size_t bytesRead)
346        {
347                GError* err = null;
348               
349                auto p = g_input_stream_read_all_finish(gInputStream, (result is null) ? null : result.getAsyncResultStruct(), &bytesRead, &err) != 0;
350               
351                if (err !is null)
352                {
353                        throw new GException( new ErrorG(err) );
354                }
355               
356                return p;
357        }
358
359        /**
360         * Request an asynchronous read of @count bytes from the stream into the buffer
361         * starting at @buffer. When the operation is finished @callback will be called.
362         * You can then call g_input_stream_read_finish() to get the result of the
363         * operation.
364         *
365         * During an async request no other sync and async calls are allowed on @stream, and will
366         * result in %G_IO_ERROR_PENDING errors.
367         *
368         * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
369         *
370         * On success, the number of bytes read into the buffer will be passed to the
371         * callback. It is not an error if this is not the same as the requested size, as it
372         * can happen e.g. near the end of a file, but generally we try to read
373         * as many bytes as requested. Zero is returned on end of file
374         * (or if @count is zero),  but never otherwise.
375         *
376         * Any outstanding i/o request with higher priority (lower numerical value) will
377         * be executed before an outstanding request with lower priority. Default
378         * priority is %G_PRIORITY_DEFAULT.
379         *
380         * The asyncronous methods have a default fallback that uses threads to implement
381         * asynchronicity, so they are optional for inheriting classes. However, if you
382         * override one you must override all.
383         *
384         * Params:
385         *     buffer = a buffer to
386         *         read data into (which should be at least count bytes long).
387         *     count = the number of bytes that will be read from the stream
388         *     ioPriority = the [I/O priority][io-priority]
389         *         of the request.
390         *     cancellable = optional #GCancellable object, %NULL to ignore.
391         *     callback = callback to call when the request is satisfied
392         *     userData = the data to pass to callback function
393         */
394        public void readAsync(ubyte[] buffer, int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
395        {
396                g_input_stream_read_async(gInputStream, buffer.ptr, cast(size_t)buffer.length, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
397        }
398
399        /**
400         * Like g_input_stream_read(), this tries to read @count bytes from
401         * the stream in a blocking fashion. However, rather than reading into
402         * a user-supplied buffer, this will create a new #GBytes containing
403         * the data that was read. This may be easier to use from language
404         * bindings.
405         *
406         * If count is zero, returns a zero-length #GBytes and does nothing. A
407         * value of @count larger than %G_MAXSSIZE will cause a
408         * %G_IO_ERROR_INVALID_ARGUMENT error.
409         *
410         * On success, a new #GBytes is returned. It is not an error if the
411         * size of this object is not the same as the requested size, as it
412         * can happen e.g. near the end of a file. A zero-length #GBytes is
413         * returned on end of file (or if @count is zero), but never
414         * otherwise.
415         *
416         * If @cancellable is not %NULL, then the operation can be cancelled by
417         * triggering the cancellable object from another thread. If the operation
418         * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
419         * operation was partially finished when the operation was cancelled the
420         * partial result will be returned, without an error.
421         *
422         * On error %NULL is returned and @error is set accordingly.
423         *
424         * Params:
425         *     count = maximum number of bytes that will be read from the stream. Common
426         *         values include 4096 and 8192.
427         *     cancellable = optional #GCancellable object, %NULL to ignore.
428         *
429         * Returns: a new #GBytes, or %NULL on error
430         *
431         * Since: 2.34
432         *
433         * Throws: GException on failure.
434         */
435        public Bytes readBytes(size_t count, Cancellable cancellable)
436        {
437                GError* err = null;
438               
439                auto p = g_input_stream_read_bytes(gInputStream, count, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
440               
441                if (err !is null)
442                {
443                        throw new GException( new ErrorG(err) );
444                }
445               
446                if(p is null)
447                {
448                        return null;
449                }
450               
451                return new Bytes(cast(GBytes*) p, true);
452        }
453
454        /**
455         * Request an asynchronous read of @count bytes from the stream into a
456         * new #GBytes. When the operation is finished @callback will be
457         * called. You can then call g_input_stream_read_bytes_finish() to get the
458         * result of the operation.
459         *
460         * During an async request no other sync and async calls are allowed
461         * on @stream, and will result in %G_IO_ERROR_PENDING errors.
462         *
463         * A value of @count larger than %G_MAXSSIZE will cause a
464         * %G_IO_ERROR_INVALID_ARGUMENT error.
465         *
466         * On success, the new #GBytes will be passed to the callback. It is
467         * not an error if this is smaller than the requested size, as it can
468         * happen e.g. near the end of a file, but generally we try to read as
469         * many bytes as requested. Zero is returned on end of file (or if
470         * @count is zero), but never otherwise.
471         *
472         * Any outstanding I/O request with higher priority (lower numerical
473         * value) will be executed before an outstanding request with lower
474         * priority. Default priority is %G_PRIORITY_DEFAULT.
475         *
476         * Params:
477         *     count = the number of bytes that will be read from the stream
478         *     ioPriority = the [I/O priority][io-priority] of the request
479         *     cancellable = optional #GCancellable object, %NULL to ignore.
480         *     callback = callback to call when the request is satisfied
481         *     userData = the data to pass to callback function
482         *
483         * Since: 2.34
484         */
485        public void readBytesAsync(size_t count, int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
486        {
487                g_input_stream_read_bytes_async(gInputStream, count, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
488        }
489
490        /**
491         * Finishes an asynchronous stream read-into-#GBytes operation.
492         *
493         * Params:
494         *     result = a #GAsyncResult.
495         *
496         * Returns: the newly-allocated #GBytes, or %NULL on error
497         *
498         * Since: 2.34
499         *
500         * Throws: GException on failure.
501         */
502        public Bytes readBytesFinish(AsyncResultIF result)
503        {
504                GError* err = null;
505               
506                auto p = g_input_stream_read_bytes_finish(gInputStream, (result is null) ? null : result.getAsyncResultStruct(), &err);
507               
508                if (err !is null)
509                {
510                        throw new GException( new ErrorG(err) );
511                }
512               
513                if(p is null)
514                {
515                        return null;
516                }
517               
518                return new Bytes(cast(GBytes*) p, true);
519        }
520
521        /**
522         * Finishes an asynchronous stream read operation.
523         *
524         * Params:
525         *     result = a #GAsyncResult.
526         *
527         * Returns: number of bytes read in, or -1 on error, or 0 on end of file.
528         *
529         * Throws: GException on failure.
530         */
531        public ptrdiff_t readFinish(AsyncResultIF result)
532        {
533                GError* err = null;
534               
535                auto p = g_input_stream_read_finish(gInputStream, (result is null) ? null : result.getAsyncResultStruct(), &err);
536               
537                if (err !is null)
538                {
539                        throw new GException( new ErrorG(err) );
540                }
541               
542                return p;
543        }
544
545        /**
546         * Sets @stream to have actions pending. If the pending flag is
547         * already set or @stream is closed, it will return %FALSE and set
548         * @error.
549         *
550         * Returns: %TRUE if pending was previously unset and is now set.
551         *
552         * Throws: GException on failure.
553         */
554        public bool setPending()
555        {
556                GError* err = null;
557               
558                auto p = g_input_stream_set_pending(gInputStream, &err) != 0;
559               
560                if (err !is null)
561                {
562                        throw new GException( new ErrorG(err) );
563                }
564               
565                return p;
566        }
567
568        /**
569         * Tries to skip @count bytes from the stream. Will block during the operation.
570         *
571         * This is identical to g_input_stream_read(), from a behaviour standpoint,
572         * but the bytes that are skipped are not returned to the user. Some
573         * streams have an implementation that is more efficient than reading the data.
574         *
575         * This function is optional for inherited classes, as the default implementation
576         * emulates it using read.
577         *
578         * If @cancellable is not %NULL, then the operation can be cancelled by
579         * triggering the cancellable object from another thread. If the operation
580         * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
581         * operation was partially finished when the operation was cancelled the
582         * partial result will be returned, without an error.
583         *
584         * Params:
585         *     count = the number of bytes that will be skipped from the stream
586         *     cancellable = optional #GCancellable object, %NULL to ignore.
587         *
588         * Returns: Number of bytes skipped, or -1 on error
589         *
590         * Throws: GException on failure.
591         */
592        public ptrdiff_t skip(size_t count, Cancellable cancellable)
593        {
594                GError* err = null;
595               
596                auto p = g_input_stream_skip(gInputStream, count, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
597               
598                if (err !is null)
599                {
600                        throw new GException( new ErrorG(err) );
601                }
602               
603                return p;
604        }
605
606        /**
607         * Request an asynchronous skip of @count bytes from the stream.
608         * When the operation is finished @callback will be called.
609         * You can then call g_input_stream_skip_finish() to get the result
610         * of the operation.
611         *
612         * During an async request no other sync and async calls are allowed,
613         * and will result in %G_IO_ERROR_PENDING errors.
614         *
615         * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
616         *
617         * On success, the number of bytes skipped will be passed to the callback.
618         * It is not an error if this is not the same as the requested size, as it
619         * can happen e.g. near the end of a file, but generally we try to skip
620         * as many bytes as requested. Zero is returned on end of file
621         * (or if @count is zero), but never otherwise.
622         *
623         * Any outstanding i/o request with higher priority (lower numerical value)
624         * will be executed before an outstanding request with lower priority.
625         * Default priority is %G_PRIORITY_DEFAULT.
626         *
627         * The asynchronous methods have a default fallback that uses threads to
628         * implement asynchronicity, so they are optional for inheriting classes.
629         * However, if you override one, you must override all.
630         *
631         * Params:
632         *     count = the number of bytes that will be skipped from the stream
633         *     ioPriority = the [I/O priority][io-priority] of the request
634         *     cancellable = optional #GCancellable object, %NULL to ignore.
635         *     callback = callback to call when the request is satisfied
636         *     userData = the data to pass to callback function
637         */
638        public void skipAsync(size_t count, int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
639        {
640                g_input_stream_skip_async(gInputStream, count, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
641        }
642
643        /**
644         * Finishes a stream skip operation.
645         *
646         * Params:
647         *     result = a #GAsyncResult.
648         *
649         * Returns: the size of the bytes skipped, or %-1 on error.
650         *
651         * Throws: GException on failure.
652         */
653        public ptrdiff_t skipFinish(AsyncResultIF result)
654        {
655                GError* err = null;
656               
657                auto p = g_input_stream_skip_finish(gInputStream, (result is null) ? null : result.getAsyncResultStruct(), &err);
658               
659                if (err !is null)
660                {
661                        throw new GException( new ErrorG(err) );
662                }
663               
664                return p;
665        }
666}
Note: See TracBrowser for help on using the repository browser.