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