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.SimpleAsyncResult; 26 27 private import gio.AsyncResultIF; 28 private import gio.AsyncResultT; 29 private import gio.Cancellable; 30 private import gio.c.functions; 31 public import gio.c.types; 32 private import glib.ConstructionException; 33 private import glib.ErrorG; 34 private import glib.GException; 35 private import glib.Str; 36 private import gobject.ObjectG; 37 public import gtkc.giotypes; 38 39 40 /** 41 * As of GLib 2.46, #GSimpleAsyncResult is deprecated in favor of 42 * #GTask, which provides a simpler API. 43 * 44 * #GSimpleAsyncResult implements #GAsyncResult. 45 * 46 * GSimpleAsyncResult handles #GAsyncReadyCallbacks, error 47 * reporting, operation cancellation and the final state of an operation, 48 * completely transparent to the application. Results can be returned 49 * as a pointer e.g. for functions that return data that is collected 50 * asynchronously, a boolean value for checking the success or failure 51 * of an operation, or a #gssize for operations which return the number 52 * of bytes modified by the operation; all of the simple return cases 53 * are covered. 54 * 55 * Most of the time, an application will not need to know of the details 56 * of this API; it is handled transparently, and any necessary operations 57 * are handled by #GAsyncResult's interface. However, if implementing a 58 * new GIO module, for writing language bindings, or for complex 59 * applications that need better control of how asynchronous operations 60 * are completed, it is important to understand this functionality. 61 * 62 * GSimpleAsyncResults are tagged with the calling function to ensure 63 * that asynchronous functions and their finishing functions are used 64 * together correctly. 65 * 66 * To create a new #GSimpleAsyncResult, call g_simple_async_result_new(). 67 * If the result needs to be created for a #GError, use 68 * g_simple_async_result_new_from_error() or 69 * g_simple_async_result_new_take_error(). If a #GError is not available 70 * (e.g. the asynchronous operation's doesn't take a #GError argument), 71 * but the result still needs to be created for an error condition, use 72 * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va() 73 * if your application or binding requires passing a variable argument list 74 * directly), and the error can then be propagated through the use of 75 * g_simple_async_result_propagate_error(). 76 * 77 * An asynchronous operation can be made to ignore a cancellation event by 78 * calling g_simple_async_result_set_handle_cancellation() with a 79 * #GSimpleAsyncResult for the operation and %FALSE. This is useful for 80 * operations that are dangerous to cancel, such as close (which would 81 * cause a leak if cancelled before being run). 82 * 83 * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop, 84 * or it can use #GThreads. 85 * g_simple_async_result_complete() will finish an I/O task directly 86 * from the point where it is called. g_simple_async_result_complete_in_idle() 87 * will finish it from an idle handler in the 88 * [thread-default main context][g-main-context-push-thread-default] 89 * . g_simple_async_result_run_in_thread() will run the 90 * job in a separate thread and then deliver the result to the 91 * thread-default main context. 92 * 93 * To set the results of an asynchronous function, 94 * g_simple_async_result_set_op_res_gpointer(), 95 * g_simple_async_result_set_op_res_gboolean(), and 96 * g_simple_async_result_set_op_res_gssize() 97 * are provided, setting the operation's result to a gpointer, gboolean, or 98 * gssize, respectively. 99 * 100 * Likewise, to get the result of an asynchronous function, 101 * g_simple_async_result_get_op_res_gpointer(), 102 * g_simple_async_result_get_op_res_gboolean(), and 103 * g_simple_async_result_get_op_res_gssize() are 104 * provided, getting the operation's result as a gpointer, gboolean, and 105 * gssize, respectively. 106 * 107 * For the details of the requirements implementations must respect, see 108 * #GAsyncResult. A typical implementation of an asynchronous operation 109 * using GSimpleAsyncResult looks something like this: 110 * 111 * |[<!-- language="C" --> 112 * static void 113 * baked_cb (Cake *cake, 114 * gpointer user_data) 115 * { 116 * // In this example, this callback is not given a reference to the cake, 117 * // so the GSimpleAsyncResult has to take a reference to it. 118 * GSimpleAsyncResult *result = user_data; 119 * 120 * if (cake == NULL) 121 * g_simple_async_result_set_error (result, 122 * BAKER_ERRORS, 123 * BAKER_ERROR_NO_FLOUR, 124 * "Go to the supermarket"); 125 * else 126 * g_simple_async_result_set_op_res_gpointer (result, 127 * g_object_ref (cake), 128 * g_object_unref); 129 * 130 * 131 * // In this example, we assume that baked_cb is called as a callback from 132 * // the mainloop, so it's safe to complete the operation synchronously here. 133 * // If, however, _baker_prepare_cake () might call its callback without 134 * // first returning to the mainloop — inadvisable, but some APIs do so — 135 * // we would need to use g_simple_async_result_complete_in_idle(). 136 * g_simple_async_result_complete (result); 137 * g_object_unref (result); 138 * } 139 * 140 * void 141 * baker_bake_cake_async (Baker *self, 142 * guint radius, 143 * GAsyncReadyCallback callback, 144 * gpointer user_data) 145 * { 146 * GSimpleAsyncResult *simple; 147 * Cake *cake; 148 * 149 * if (radius < 3) 150 * { 151 * g_simple_async_report_error_in_idle (G_OBJECT (self), 152 * callback, 153 * user_data, 154 * BAKER_ERRORS, 155 * BAKER_ERROR_TOO_SMALL, 156 * "%ucm radius cakes are silly", 157 * radius); 158 * return; 159 * } 160 * 161 * simple = g_simple_async_result_new (G_OBJECT (self), 162 * callback, 163 * user_data, 164 * baker_bake_cake_async); 165 * cake = _baker_get_cached_cake (self, radius); 166 * 167 * if (cake != NULL) 168 * { 169 * g_simple_async_result_set_op_res_gpointer (simple, 170 * g_object_ref (cake), 171 * g_object_unref); 172 * g_simple_async_result_complete_in_idle (simple); 173 * g_object_unref (simple); 174 * // Drop the reference returned by _baker_get_cached_cake(); 175 * // the GSimpleAsyncResult has taken its own reference. 176 * g_object_unref (cake); 177 * return; 178 * } 179 * 180 * _baker_prepare_cake (self, radius, baked_cb, simple); 181 * } 182 * 183 * Cake * 184 * baker_bake_cake_finish (Baker *self, 185 * GAsyncResult *result, 186 * GError **error) 187 * { 188 * GSimpleAsyncResult *simple; 189 * Cake *cake; 190 * 191 * g_return_val_if_fail (g_simple_async_result_is_valid (result, 192 * G_OBJECT (self), 193 * baker_bake_cake_async), 194 * NULL); 195 * 196 * simple = (GSimpleAsyncResult *) result; 197 * 198 * if (g_simple_async_result_propagate_error (simple, error)) 199 * return NULL; 200 * 201 * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple)); 202 * return g_object_ref (cake); 203 * } 204 * ]| 205 */ 206 public class SimpleAsyncResult : ObjectG, AsyncResultIF 207 { 208 /** the main Gtk struct */ 209 protected GSimpleAsyncResult* gSimpleAsyncResult; 210 211 /** Get the main Gtk struct */ 212 public GSimpleAsyncResult* getSimpleAsyncResultStruct(bool transferOwnership = false) 213 { 214 if (transferOwnership) 215 ownedRef = false; 216 return gSimpleAsyncResult; 217 } 218 219 /** the main Gtk struct as a void* */ 220 protected override void* getStruct() 221 { 222 return cast(void*)gSimpleAsyncResult; 223 } 224 225 protected override void setStruct(GObject* obj) 226 { 227 gSimpleAsyncResult = cast(GSimpleAsyncResult*)obj; 228 super.setStruct(obj); 229 } 230 231 /** 232 * Sets our main struct and passes it to the parent class. 233 */ 234 public this (GSimpleAsyncResult* gSimpleAsyncResult, bool ownedRef = false) 235 { 236 this.gSimpleAsyncResult = gSimpleAsyncResult; 237 super(cast(GObject*)gSimpleAsyncResult, ownedRef); 238 } 239 240 // add the AsyncResult capabilities 241 mixin AsyncResultT!(GSimpleAsyncResult); 242 243 244 /** */ 245 public static GType getType() 246 { 247 return g_simple_async_result_get_type(); 248 } 249 250 /** 251 * Creates a #GSimpleAsyncResult. 252 * 253 * The common convention is to create the #GSimpleAsyncResult in the 254 * function that starts the asynchronous operation and use that same 255 * function as the @source_tag. 256 * 257 * If your operation supports cancellation with #GCancellable (which it 258 * probably should) then you should provide the user's cancellable to 259 * g_simple_async_result_set_check_cancellable() immediately after 260 * this function returns. 261 * 262 * Deprecated: Use g_task_new() instead. 263 * 264 * Params: 265 * sourceObject = a #GObject, or %NULL. 266 * callback = a #GAsyncReadyCallback. 267 * userData = user data passed to @callback. 268 * sourceTag = the asynchronous function. 269 * 270 * Returns: a #GSimpleAsyncResult. 271 * 272 * Throws: ConstructionException GTK+ fails to create the object. 273 */ 274 public this(ObjectG sourceObject, GAsyncReadyCallback callback, void* userData, void* sourceTag) 275 { 276 auto p = g_simple_async_result_new((sourceObject is null) ? null : sourceObject.getObjectGStruct(), callback, userData, sourceTag); 277 278 if(p is null) 279 { 280 throw new ConstructionException("null returned by new"); 281 } 282 283 this(cast(GSimpleAsyncResult*) p, true); 284 } 285 286 /** 287 * Creates a #GSimpleAsyncResult from an error condition. 288 * 289 * Deprecated: Use g_task_new() and g_task_return_error() instead. 290 * 291 * Params: 292 * sourceObject = a #GObject, or %NULL. 293 * callback = a #GAsyncReadyCallback. 294 * userData = user data passed to @callback. 295 * error = a #GError 296 * 297 * Returns: a #GSimpleAsyncResult. 298 * 299 * Throws: ConstructionException GTK+ fails to create the object. 300 */ 301 public this(ObjectG sourceObject, GAsyncReadyCallback callback, void* userData, ErrorG error) 302 { 303 auto p = g_simple_async_result_new_from_error((sourceObject is null) ? null : sourceObject.getObjectGStruct(), callback, userData, (error is null) ? null : error.getErrorGStruct()); 304 305 if(p is null) 306 { 307 throw new ConstructionException("null returned by new_from_error"); 308 } 309 310 this(cast(GSimpleAsyncResult*) p, true); 311 } 312 313 /** 314 * Ensures that the data passed to the _finish function of an async 315 * operation is consistent. Three checks are performed. 316 * 317 * First, @result is checked to ensure that it is really a 318 * #GSimpleAsyncResult. Second, @source is checked to ensure that it 319 * matches the source object of @result. Third, @source_tag is 320 * checked to ensure that it is equal to the @source_tag argument given 321 * to g_simple_async_result_new() (which, by convention, is a pointer 322 * to the _async function corresponding to the _finish function from 323 * which this function is called). (Alternatively, if either 324 * @source_tag or @result's source tag is %NULL, then the source tag 325 * check is skipped.) 326 * 327 * Deprecated: Use #GTask and g_task_is_valid() instead. 328 * 329 * Params: 330 * result = the #GAsyncResult passed to the _finish function. 331 * source = the #GObject passed to the _finish function. 332 * sourceTag = the asynchronous function. 333 * 334 * Returns: #TRUE if all checks passed or #FALSE if any failed. 335 * 336 * Since: 2.20 337 */ 338 public static bool isValid(AsyncResultIF result, ObjectG source, void* sourceTag) 339 { 340 return g_simple_async_result_is_valid((result is null) ? null : result.getAsyncResultStruct(), (source is null) ? null : source.getObjectGStruct(), sourceTag) != 0; 341 } 342 343 /** 344 * Completes an asynchronous I/O job immediately. Must be called in 345 * the thread where the asynchronous result was to be delivered, as it 346 * invokes the callback directly. If you are in a different thread use 347 * g_simple_async_result_complete_in_idle(). 348 * 349 * Calling this function takes a reference to @simple for as long as 350 * is needed to complete the call. 351 * 352 * Deprecated: Use #GTask instead. 353 */ 354 public void complete() 355 { 356 g_simple_async_result_complete(gSimpleAsyncResult); 357 } 358 359 /** 360 * Completes an asynchronous function in an idle handler in the 361 * [thread-default main context][g-main-context-push-thread-default] 362 * of the thread that @simple was initially created in 363 * (and re-pushes that context around the invocation of the callback). 364 * 365 * Calling this function takes a reference to @simple for as long as 366 * is needed to complete the call. 367 * 368 * Deprecated: Use #GTask instead. 369 */ 370 public void completeInIdle() 371 { 372 g_simple_async_result_complete_in_idle(gSimpleAsyncResult); 373 } 374 375 /** 376 * Gets the operation result boolean from within the asynchronous result. 377 * 378 * Deprecated: Use #GTask and g_task_propagate_boolean() instead. 379 * 380 * Returns: %TRUE if the operation's result was %TRUE, %FALSE 381 * if the operation's result was %FALSE. 382 */ 383 public bool getOpResGboolean() 384 { 385 return g_simple_async_result_get_op_res_gboolean(gSimpleAsyncResult) != 0; 386 } 387 388 /** 389 * Gets a pointer result as returned by the asynchronous function. 390 * 391 * Deprecated: Use #GTask and g_task_propagate_pointer() instead. 392 * 393 * Returns: a pointer from the result. 394 */ 395 public void* getOpResGpointer() 396 { 397 return g_simple_async_result_get_op_res_gpointer(gSimpleAsyncResult); 398 } 399 400 /** 401 * Gets a gssize from the asynchronous result. 402 * 403 * Deprecated: Use #GTask and g_task_propagate_int() instead. 404 * 405 * Returns: a gssize returned from the asynchronous function. 406 */ 407 public ptrdiff_t getOpResGssize() 408 { 409 return g_simple_async_result_get_op_res_gssize(gSimpleAsyncResult); 410 } 411 412 /** 413 * Gets the source tag for the #GSimpleAsyncResult. 414 * 415 * Deprecated: Use #GTask and g_task_get_source_tag() instead. 416 * 417 * Returns: a #gpointer to the source object for the #GSimpleAsyncResult. 418 */ 419 public void* getSourceTag() 420 { 421 return g_simple_async_result_get_source_tag(gSimpleAsyncResult); 422 } 423 424 /** 425 * Propagates an error from within the simple asynchronous result to 426 * a given destination. 427 * 428 * If the #GCancellable given to a prior call to 429 * g_simple_async_result_set_check_cancellable() is cancelled then this 430 * function will return %TRUE with @dest set appropriately. 431 * 432 * Deprecated: Use #GTask instead. 433 * 434 * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise. 435 * 436 * Throws: GException on failure. 437 */ 438 public bool propagateError() 439 { 440 GError* err = null; 441 442 auto p = g_simple_async_result_propagate_error(gSimpleAsyncResult, &err) != 0; 443 444 if (err !is null) 445 { 446 throw new GException( new ErrorG(err) ); 447 } 448 449 return p; 450 } 451 452 /** 453 * Runs the asynchronous job in a separate thread and then calls 454 * g_simple_async_result_complete_in_idle() on @simple to return 455 * the result to the appropriate main loop. 456 * 457 * Calling this function takes a reference to @simple for as long as 458 * is needed to run the job and report its completion. 459 * 460 * Deprecated: Use #GTask and g_task_run_in_thread() instead. 461 * 462 * Params: 463 * func = a #GSimpleAsyncThreadFunc. 464 * ioPriority = the io priority of the request. 465 * cancellable = optional #GCancellable object, %NULL to ignore. 466 */ 467 public void runInThread(GSimpleAsyncThreadFunc func, int ioPriority, Cancellable cancellable) 468 { 469 g_simple_async_result_run_in_thread(gSimpleAsyncResult, func, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct()); 470 } 471 472 /** 473 * Sets a #GCancellable to check before dispatching results. 474 * 475 * This function has one very specific purpose: the provided cancellable 476 * is checked at the time of g_simple_async_result_propagate_error() If 477 * it is cancelled, these functions will return an "Operation was 478 * cancelled" error (%G_IO_ERROR_CANCELLED). 479 * 480 * Implementors of cancellable asynchronous functions should use this in 481 * order to provide a guarantee to their callers that cancelling an 482 * async operation will reliably result in an error being returned for 483 * that operation (even if a positive result for the operation has 484 * already been sent as an idle to the main context to be dispatched). 485 * 486 * The checking described above is done regardless of any call to the 487 * unrelated g_simple_async_result_set_handle_cancellation() function. 488 * 489 * Deprecated: Use #GTask instead. 490 * 491 * Params: 492 * checkCancellable = a #GCancellable to check, or %NULL to unset 493 * 494 * Since: 2.32 495 */ 496 public void setCheckCancellable(Cancellable checkCancellable) 497 { 498 g_simple_async_result_set_check_cancellable(gSimpleAsyncResult, (checkCancellable is null) ? null : checkCancellable.getCancellableStruct()); 499 } 500 501 /** 502 * Sets an error within the asynchronous result without a #GError. 503 * Unless writing a binding, see g_simple_async_result_set_error(). 504 * 505 * Deprecated: Use #GTask and g_task_return_error() instead. 506 * 507 * Params: 508 * domain = a #GQuark (usually #G_IO_ERROR). 509 * code = an error code. 510 * format = a formatted error reporting string. 511 * args = va_list of arguments. 512 */ 513 public void setErrorVa(GQuark domain, int code, string format, void* args) 514 { 515 g_simple_async_result_set_error_va(gSimpleAsyncResult, domain, code, Str.toStringz(format), args); 516 } 517 518 /** 519 * Sets the result from a #GError. 520 * 521 * Deprecated: Use #GTask and g_task_return_error() instead. 522 * 523 * Params: 524 * error = #GError. 525 */ 526 public void setFromError(ErrorG error) 527 { 528 g_simple_async_result_set_from_error(gSimpleAsyncResult, (error is null) ? null : error.getErrorGStruct()); 529 } 530 531 /** 532 * Sets whether to handle cancellation within the asynchronous operation. 533 * 534 * This function has nothing to do with 535 * g_simple_async_result_set_check_cancellable(). It only refers to the 536 * #GCancellable passed to g_simple_async_result_run_in_thread(). 537 * 538 * Params: 539 * handleCancellation = a #gboolean. 540 */ 541 public void setHandleCancellation(bool handleCancellation) 542 { 543 g_simple_async_result_set_handle_cancellation(gSimpleAsyncResult, handleCancellation); 544 } 545 546 /** 547 * Sets the operation result to a boolean within the asynchronous result. 548 * 549 * Deprecated: Use #GTask and g_task_return_boolean() instead. 550 * 551 * Params: 552 * opRes = a #gboolean. 553 */ 554 public void setOpResGboolean(bool opRes) 555 { 556 g_simple_async_result_set_op_res_gboolean(gSimpleAsyncResult, opRes); 557 } 558 559 /** 560 * Sets the operation result within the asynchronous result to a pointer. 561 * 562 * Deprecated: Use #GTask and g_task_return_pointer() instead. 563 * 564 * Params: 565 * opRes = a pointer result from an asynchronous function. 566 * destroyOpRes = a #GDestroyNotify function. 567 */ 568 public void setOpResGpointer(void* opRes, GDestroyNotify destroyOpRes) 569 { 570 g_simple_async_result_set_op_res_gpointer(gSimpleAsyncResult, opRes, destroyOpRes); 571 } 572 573 /** 574 * Sets the operation result within the asynchronous result to 575 * the given @op_res. 576 * 577 * Deprecated: Use #GTask and g_task_return_int() instead. 578 * 579 * Params: 580 * opRes = a #gssize. 581 */ 582 public void setOpResGssize(ptrdiff_t opRes) 583 { 584 g_simple_async_result_set_op_res_gssize(gSimpleAsyncResult, opRes); 585 } 586 587 /** 588 * Sets the result from @error, and takes over the caller's ownership 589 * of @error, so the caller does not need to free it any more. 590 * 591 * Deprecated: Use #GTask and g_task_return_error() instead. 592 * 593 * Params: 594 * error = a #GError 595 * 596 * Since: 2.28 597 */ 598 public void takeError(ErrorG error) 599 { 600 g_simple_async_result_take_error(gSimpleAsyncResult, (error is null) ? null : error.getErrorGStruct()); 601 } 602 603 /** 604 * Reports an error in an idle function. Similar to 605 * g_simple_async_report_error_in_idle(), but takes a #GError rather 606 * than building a new one. 607 * 608 * Deprecated: Use g_task_report_error(). 609 * 610 * Params: 611 * object = a #GObject, or %NULL 612 * callback = a #GAsyncReadyCallback. 613 * userData = user data passed to @callback. 614 * error = the #GError to report 615 */ 616 public static void simpleAsyncReportGerrorInIdle(ObjectG object, GAsyncReadyCallback callback, void* userData, ErrorG error) 617 { 618 g_simple_async_report_gerror_in_idle((object is null) ? null : object.getObjectGStruct(), callback, userData, (error is null) ? null : error.getErrorGStruct()); 619 } 620 621 /** 622 * Reports an error in an idle function. Similar to 623 * g_simple_async_report_gerror_in_idle(), but takes over the caller's 624 * ownership of @error, so the caller does not have to free it any more. 625 * 626 * Deprecated: Use g_task_report_error(). 627 * 628 * Params: 629 * object = a #GObject, or %NULL 630 * callback = a #GAsyncReadyCallback. 631 * userData = user data passed to @callback. 632 * error = the #GError to report 633 * 634 * Since: 2.28 635 */ 636 public static void simpleAsyncReportTakeGerrorInIdle(ObjectG object, GAsyncReadyCallback callback, void* userData, ErrorG error) 637 { 638 g_simple_async_report_take_gerror_in_idle((object is null) ? null : object.getObjectGStruct(), callback, userData, (error is null) ? null : error.getErrorGStruct()); 639 } 640 }