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