1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gio.IOStream;
26 
27 private import gio.AsyncResultIF;
28 private import gio.Cancellable;
29 private import gio.InputStream;
30 private import gio.OutputStream;
31 private import gio.c.functions;
32 public  import gio.c.types;
33 private import glib.ErrorG;
34 private import glib.GException;
35 private import gobject.ObjectG;
36 public  import gtkc.giotypes;
37 
38 
39 /**
40  * GIOStream represents an object that has both read and write streams.
41  * Generally the two streams act as separate input and output streams,
42  * but they share some common resources and state. For instance, for
43  * seekable streams, both streams may use the same position.
44  * 
45  * Examples of #GIOStream objects are #GSocketConnection, which represents
46  * a two-way network connection; and #GFileIOStream, which represents a
47  * file handle opened in read-write mode.
48  * 
49  * To do the actual reading and writing you need to get the substreams
50  * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
51  * 
52  * The #GIOStream object owns the input and the output streams, not the other
53  * way around, so keeping the substreams alive will not keep the #GIOStream
54  * object alive. If the #GIOStream object is freed it will be closed, thus
55  * closing the substreams, so even if the substreams stay alive they will
56  * always return %G_IO_ERROR_CLOSED for all operations.
57  * 
58  * To close a stream use g_io_stream_close() which will close the common
59  * stream object and also the individual substreams. You can also close
60  * the substreams themselves. In most cases this only marks the
61  * substream as closed, so further I/O on it fails but common state in the
62  * #GIOStream may still be open. However, some streams may support
63  * "half-closed" states where one direction of the stream is actually shut down.
64  * 
65  * Operations on #GIOStreams cannot be started while another operation on the
66  * #GIOStream or its substreams is in progress. Specifically, an application can
67  * read from the #GInputStream and write to the #GOutputStream simultaneously
68  * (either in separate threads, or as asynchronous operations in the same
69  * thread), but an application cannot start any #GIOStream operation while there
70  * is a #GIOStream, #GInputStream or #GOutputStream operation in progress, and
71  * an application can’t start any #GInputStream or #GOutputStream operation
72  * while there is a #GIOStream operation in progress.
73  * 
74  * This is a product of individual stream operations being associated with a
75  * given #GMainContext (the thread-default context at the time the operation was
76  * started), rather than entire streams being associated with a single
77  * #GMainContext.
78  * 
79  * GIO may run operations on #GIOStreams from other (worker) threads, and this
80  * may be exposed to application code in the behaviour of wrapper streams, such
81  * as #GBufferedInputStream or #GTlsConnection. With such wrapper APIs,
82  * application code may only run operations on the base (wrapped) stream when
83  * the wrapper stream is idle. Note that the semantics of such operations may
84  * not be well-defined due to the state the wrapper stream leaves the base
85  * stream in (though they are guaranteed not to crash).
86  *
87  * Since: 2.22
88  */
89 public class IOStream : ObjectG
90 {
91 	/** the main Gtk struct */
92 	protected GIOStream* gIOStream;
93 
94 	/** Get the main Gtk struct */
95 	public GIOStream* getIOStreamStruct(bool transferOwnership = false)
96 	{
97 		if (transferOwnership)
98 			ownedRef = false;
99 		return gIOStream;
100 	}
101 
102 	/** the main Gtk struct as a void* */
103 	protected override void* getStruct()
104 	{
105 		return cast(void*)gIOStream;
106 	}
107 
108 	/**
109 	 * Sets our main struct and passes it to the parent class.
110 	 */
111 	public this (GIOStream* gIOStream, bool ownedRef = false)
112 	{
113 		this.gIOStream = gIOStream;
114 		super(cast(GObject*)gIOStream, ownedRef);
115 	}
116 
117 
118 	/** */
119 	public static GType getType()
120 	{
121 		return g_io_stream_get_type();
122 	}
123 
124 	/**
125 	 * Finishes an asynchronous io stream splice operation.
126 	 *
127 	 * Params:
128 	 *     result = a #GAsyncResult.
129 	 *
130 	 * Returns: %TRUE on success, %FALSE otherwise.
131 	 *
132 	 * Since: 2.28
133 	 *
134 	 * Throws: GException on failure.
135 	 */
136 	public static bool spliceFinish(AsyncResultIF result)
137 	{
138 		GError* err = null;
139 
140 		auto __p = g_io_stream_splice_finish((result is null) ? null : result.getAsyncResultStruct(), &err) != 0;
141 
142 		if (err !is null)
143 		{
144 			throw new GException( new ErrorG(err) );
145 		}
146 
147 		return __p;
148 	}
149 
150 	/**
151 	 * Clears the pending flag on @stream.
152 	 *
153 	 * Since: 2.22
154 	 */
155 	public void clearPending()
156 	{
157 		g_io_stream_clear_pending(gIOStream);
158 	}
159 
160 	/**
161 	 * Closes the stream, releasing resources related to it. This will also
162 	 * close the individual input and output streams, if they are not already
163 	 * closed.
164 	 *
165 	 * Once the stream is closed, all other operations will return
166 	 * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not
167 	 * return an error.
168 	 *
169 	 * Closing a stream will automatically flush any outstanding buffers
170 	 * in the stream.
171 	 *
172 	 * Streams will be automatically closed when the last reference
173 	 * is dropped, but you might want to call this function to make sure
174 	 * resources are released as early as possible.
175 	 *
176 	 * Some streams might keep the backing store of the stream (e.g. a file
177 	 * descriptor) open after the stream is closed. See the documentation for
178 	 * the individual stream for details.
179 	 *
180 	 * On failure the first error that happened will be reported, but the
181 	 * close operation will finish as much as possible. A stream that failed
182 	 * to close will still return %G_IO_ERROR_CLOSED for all operations.
183 	 * Still, it is important to check and report the error to the user,
184 	 * otherwise there might be a loss of data as all data might not be written.
185 	 *
186 	 * If @cancellable is not NULL, then the operation can be cancelled by
187 	 * triggering the cancellable object from another thread. If the operation
188 	 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
189 	 * Cancelling a close will still leave the stream closed, but some streams
190 	 * can use a faster close that doesn't block to e.g. check errors.
191 	 *
192 	 * The default implementation of this method just calls close on the
193 	 * individual input/output streams.
194 	 *
195 	 * Params:
196 	 *     cancellable = optional #GCancellable object, %NULL to ignore
197 	 *
198 	 * Returns: %TRUE on success, %FALSE on failure
199 	 *
200 	 * Since: 2.22
201 	 *
202 	 * Throws: GException on failure.
203 	 */
204 	public bool close(Cancellable cancellable)
205 	{
206 		GError* err = null;
207 
208 		auto __p = g_io_stream_close(gIOStream, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0;
209 
210 		if (err !is null)
211 		{
212 			throw new GException( new ErrorG(err) );
213 		}
214 
215 		return __p;
216 	}
217 
218 	/**
219 	 * Requests an asynchronous close of the stream, releasing resources
220 	 * related to it. When the operation is finished @callback will be
221 	 * called. You can then call g_io_stream_close_finish() to get
222 	 * the result of the operation.
223 	 *
224 	 * For behaviour details see g_io_stream_close().
225 	 *
226 	 * The asynchronous methods have a default fallback that uses threads
227 	 * to implement asynchronicity, so they are optional for inheriting
228 	 * classes. However, if you override one you must override all.
229 	 *
230 	 * Params:
231 	 *     ioPriority = the io priority of the request
232 	 *     cancellable = optional cancellable object
233 	 *     callback = callback to call when the request is satisfied
234 	 *     userData = the data to pass to callback function
235 	 *
236 	 * Since: 2.22
237 	 */
238 	public void closeAsync(int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
239 	{
240 		g_io_stream_close_async(gIOStream, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
241 	}
242 
243 	/**
244 	 * Closes a stream.
245 	 *
246 	 * Params:
247 	 *     result = a #GAsyncResult
248 	 *
249 	 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
250 	 *
251 	 * Since: 2.22
252 	 *
253 	 * Throws: GException on failure.
254 	 */
255 	public bool closeFinish(AsyncResultIF result)
256 	{
257 		GError* err = null;
258 
259 		auto __p = g_io_stream_close_finish(gIOStream, (result is null) ? null : result.getAsyncResultStruct(), &err) != 0;
260 
261 		if (err !is null)
262 		{
263 			throw new GException( new ErrorG(err) );
264 		}
265 
266 		return __p;
267 	}
268 
269 	/**
270 	 * Gets the input stream for this object. This is used
271 	 * for reading.
272 	 *
273 	 * Returns: a #GInputStream, owned by the #GIOStream.
274 	 *     Do not free.
275 	 *
276 	 * Since: 2.22
277 	 */
278 	public InputStream getInputStream()
279 	{
280 		auto __p = g_io_stream_get_input_stream(gIOStream);
281 
282 		if(__p is null)
283 		{
284 			return null;
285 		}
286 
287 		return ObjectG.getDObject!(InputStream)(cast(GInputStream*) __p);
288 	}
289 
290 	/**
291 	 * Gets the output stream for this object. This is used for
292 	 * writing.
293 	 *
294 	 * Returns: a #GOutputStream, owned by the #GIOStream.
295 	 *     Do not free.
296 	 *
297 	 * Since: 2.22
298 	 */
299 	public OutputStream getOutputStream()
300 	{
301 		auto __p = g_io_stream_get_output_stream(gIOStream);
302 
303 		if(__p is null)
304 		{
305 			return null;
306 		}
307 
308 		return ObjectG.getDObject!(OutputStream)(cast(GOutputStream*) __p);
309 	}
310 
311 	/**
312 	 * Checks if a stream has pending actions.
313 	 *
314 	 * Returns: %TRUE if @stream has pending actions.
315 	 *
316 	 * Since: 2.22
317 	 */
318 	public bool hasPending()
319 	{
320 		return g_io_stream_has_pending(gIOStream) != 0;
321 	}
322 
323 	/**
324 	 * Checks if a stream is closed.
325 	 *
326 	 * Returns: %TRUE if the stream is closed.
327 	 *
328 	 * Since: 2.22
329 	 */
330 	public bool isClosed()
331 	{
332 		return g_io_stream_is_closed(gIOStream) != 0;
333 	}
334 
335 	/**
336 	 * Sets @stream to have actions pending. If the pending flag is
337 	 * already set or @stream is closed, it will return %FALSE and set
338 	 * @error.
339 	 *
340 	 * Returns: %TRUE if pending was previously unset and is now set.
341 	 *
342 	 * Since: 2.22
343 	 *
344 	 * Throws: GException on failure.
345 	 */
346 	public bool setPending()
347 	{
348 		GError* err = null;
349 
350 		auto __p = g_io_stream_set_pending(gIOStream, &err) != 0;
351 
352 		if (err !is null)
353 		{
354 			throw new GException( new ErrorG(err) );
355 		}
356 
357 		return __p;
358 	}
359 
360 	/**
361 	 * Asyncronously splice the output stream of @stream1 to the input stream of
362 	 * @stream2, and splice the output stream of @stream2 to the input stream of
363 	 * @stream1.
364 	 *
365 	 * When the operation is finished @callback will be called.
366 	 * You can then call g_io_stream_splice_finish() to get the
367 	 * result of the operation.
368 	 *
369 	 * Params:
370 	 *     stream2 = a #GIOStream.
371 	 *     flags = a set of #GIOStreamSpliceFlags.
372 	 *     ioPriority = the io priority of the request.
373 	 *     cancellable = optional #GCancellable object, %NULL to ignore.
374 	 *     callback = a #GAsyncReadyCallback.
375 	 *     userData = user data passed to @callback.
376 	 *
377 	 * Since: 2.28
378 	 */
379 	public void spliceAsync(IOStream stream2, GIOStreamSpliceFlags flags, int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
380 	{
381 		g_io_stream_splice_async(gIOStream, (stream2 is null) ? null : stream2.getIOStreamStruct(), flags, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
382 	}
383 }