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