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 glib.ErrorG; 32 private import glib.GException; 33 private import gobject.ObjectG; 34 private import gtkc.gio; 35 public import gtkc.giotypes; 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 public class IOStream : ObjectG 87 { 88 /** the main Gtk struct */ 89 protected GIOStream* gIOStream; 90 91 /** Get the main Gtk struct */ 92 public GIOStream* getIOStreamStruct(bool transferOwnership = false) 93 { 94 if (transferOwnership) 95 ownedRef = false; 96 return gIOStream; 97 } 98 99 /** the main Gtk struct as a void* */ 100 protected override void* getStruct() 101 { 102 return cast(void*)gIOStream; 103 } 104 105 protected override void setStruct(GObject* obj) 106 { 107 gIOStream = cast(GIOStream*)obj; 108 super.setStruct(obj); 109 } 110 111 /** 112 * Sets our main struct and passes it to the parent class. 113 */ 114 public this (GIOStream* gIOStream, bool ownedRef = false) 115 { 116 this.gIOStream = gIOStream; 117 super(cast(GObject*)gIOStream, ownedRef); 118 } 119 120 121 /** */ 122 public static GType getType() 123 { 124 return g_io_stream_get_type(); 125 } 126 127 /** 128 * Finishes an asynchronous io stream splice operation. 129 * 130 * Params: 131 * result = a #GAsyncResult. 132 * 133 * Returns: %TRUE on success, %FALSE otherwise. 134 * 135 * Since: 2.28 136 * 137 * Throws: GException on failure. 138 */ 139 public static bool spliceFinish(AsyncResultIF result) 140 { 141 GError* err = null; 142 143 auto p = g_io_stream_splice_finish((result is null) ? null : result.getAsyncResultStruct(), &err) != 0; 144 145 if (err !is null) 146 { 147 throw new GException( new ErrorG(err) ); 148 } 149 150 return p; 151 } 152 153 /** 154 * Clears the pending flag on @stream. 155 * 156 * Since: 2.22 157 */ 158 public void clearPending() 159 { 160 g_io_stream_clear_pending(gIOStream); 161 } 162 163 /** 164 * Closes the stream, releasing resources related to it. This will also 165 * close the individual input and output streams, if they are not already 166 * closed. 167 * 168 * Once the stream is closed, all other operations will return 169 * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not 170 * return an error. 171 * 172 * Closing a stream will automatically flush any outstanding buffers 173 * in the stream. 174 * 175 * Streams will be automatically closed when the last reference 176 * is dropped, but you might want to call this function to make sure 177 * resources are released as early as possible. 178 * 179 * Some streams might keep the backing store of the stream (e.g. a file 180 * descriptor) open after the stream is closed. See the documentation for 181 * the individual stream for details. 182 * 183 * On failure the first error that happened will be reported, but the 184 * close operation will finish as much as possible. A stream that failed 185 * to close will still return %G_IO_ERROR_CLOSED for all operations. 186 * Still, it is important to check and report the error to the user, 187 * otherwise there might be a loss of data as all data might not be written. 188 * 189 * If @cancellable is not NULL, then the operation can be cancelled by 190 * triggering the cancellable object from another thread. If the operation 191 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 192 * Cancelling a close will still leave the stream closed, but some streams 193 * can use a faster close that doesn't block to e.g. check errors. 194 * 195 * The default implementation of this method just calls close on the 196 * individual input/output streams. 197 * 198 * Params: 199 * cancellable = optional #GCancellable object, %NULL to ignore 200 * 201 * Returns: %TRUE on success, %FALSE on failure 202 * 203 * Since: 2.22 204 * 205 * Throws: GException on failure. 206 */ 207 public bool close(Cancellable cancellable) 208 { 209 GError* err = null; 210 211 auto p = g_io_stream_close(gIOStream, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0; 212 213 if (err !is null) 214 { 215 throw new GException( new ErrorG(err) ); 216 } 217 218 return p; 219 } 220 221 /** 222 * Requests an asynchronous close of the stream, releasing resources 223 * related to it. When the operation is finished @callback will be 224 * called. You can then call g_io_stream_close_finish() to get 225 * the result of the operation. 226 * 227 * For behaviour details see g_io_stream_close(). 228 * 229 * The asynchronous methods have a default fallback that uses threads 230 * to implement asynchronicity, so they are optional for inheriting 231 * classes. However, if you override one you must override all. 232 * 233 * Params: 234 * ioPriority = the io priority of the request 235 * cancellable = optional cancellable object 236 * callback = callback to call when the request is satisfied 237 * userData = the data to pass to callback function 238 * 239 * Since: 2.22 240 */ 241 public void closeAsync(int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData) 242 { 243 g_io_stream_close_async(gIOStream, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData); 244 } 245 246 /** 247 * Closes a stream. 248 * 249 * Params: 250 * result = a #GAsyncResult 251 * 252 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise. 253 * 254 * Since: 2.22 255 * 256 * Throws: GException on failure. 257 */ 258 public bool closeFinish(AsyncResultIF result) 259 { 260 GError* err = null; 261 262 auto p = g_io_stream_close_finish(gIOStream, (result is null) ? null : result.getAsyncResultStruct(), &err) != 0; 263 264 if (err !is null) 265 { 266 throw new GException( new ErrorG(err) ); 267 } 268 269 return p; 270 } 271 272 /** 273 * Gets the input stream for this object. This is used 274 * for reading. 275 * 276 * Returns: a #GInputStream, owned by the #GIOStream. 277 * Do not free. 278 * 279 * Since: 2.22 280 */ 281 public InputStream getInputStream() 282 { 283 auto p = g_io_stream_get_input_stream(gIOStream); 284 285 if(p is null) 286 { 287 return null; 288 } 289 290 return ObjectG.getDObject!(InputStream)(cast(GInputStream*) p); 291 } 292 293 /** 294 * Gets the output stream for this object. This is used for 295 * writing. 296 * 297 * Returns: a #GOutputStream, owned by the #GIOStream. 298 * Do not free. 299 * 300 * Since: 2.22 301 */ 302 public OutputStream getOutputStream() 303 { 304 auto p = g_io_stream_get_output_stream(gIOStream); 305 306 if(p is null) 307 { 308 return null; 309 } 310 311 return ObjectG.getDObject!(OutputStream)(cast(GOutputStream*) p); 312 } 313 314 /** 315 * Checks if a stream has pending actions. 316 * 317 * Returns: %TRUE if @stream has pending actions. 318 * 319 * Since: 2.22 320 */ 321 public bool hasPending() 322 { 323 return g_io_stream_has_pending(gIOStream) != 0; 324 } 325 326 /** 327 * Checks if a stream is closed. 328 * 329 * Returns: %TRUE if the stream is closed. 330 * 331 * Since: 2.22 332 */ 333 public bool isClosed() 334 { 335 return g_io_stream_is_closed(gIOStream) != 0; 336 } 337 338 /** 339 * Sets @stream to have actions pending. If the pending flag is 340 * already set or @stream is closed, it will return %FALSE and set 341 * @error. 342 * 343 * Returns: %TRUE if pending was previously unset and is now set. 344 * 345 * Since: 2.22 346 * 347 * Throws: GException on failure. 348 */ 349 public bool setPending() 350 { 351 GError* err = null; 352 353 auto p = g_io_stream_set_pending(gIOStream, &err) != 0; 354 355 if (err !is null) 356 { 357 throw new GException( new ErrorG(err) ); 358 } 359 360 return p; 361 } 362 363 /** 364 * Asyncronously splice the output stream of @stream1 to the input stream of 365 * @stream2, and splice the output stream of @stream2 to the input stream of 366 * @stream1. 367 * 368 * When the operation is finished @callback will be called. 369 * You can then call g_io_stream_splice_finish() to get the 370 * result of the operation. 371 * 372 * Params: 373 * stream2 = a #GIOStream. 374 * flags = a set of #GIOStreamSpliceFlags. 375 * ioPriority = the io priority of the request. 376 * cancellable = optional #GCancellable object, %NULL to ignore. 377 * callback = a #GAsyncReadyCallback. 378 * userData = user data passed to @callback. 379 * 380 * Since: 2.28 381 */ 382 public void spliceAsync(IOStream stream2, GIOStreamSpliceFlags flags, int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData) 383 { 384 g_io_stream_splice_async(gIOStream, (stream2 is null) ? null : stream2.getIOStreamStruct(), flags, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData); 385 } 386 }