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.36, #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() 212 { 213 return gSimpleAsyncResult; 214 } 215 216 /** the main Gtk struct as a void* */ 217 protected override void* getStruct() 218 { 219 return cast(void*)gSimpleAsyncResult; 220 } 221 222 protected override void setStruct(GObject* obj) 223 { 224 gSimpleAsyncResult = cast(GSimpleAsyncResult*)obj; 225 super.setStruct(obj); 226 } 227 228 /** 229 * Sets our main struct and passes it to the parent class. 230 */ 231 public this (GSimpleAsyncResult* gSimpleAsyncResult, bool ownedRef = false) 232 { 233 this.gSimpleAsyncResult = gSimpleAsyncResult; 234 super(cast(GObject*)gSimpleAsyncResult, ownedRef); 235 } 236 237 // add the AsyncResult capabilities 238 mixin AsyncResultT!(GSimpleAsyncResult); 239 240 /** 241 */ 242 243 public static GType getType() 244 { 245 return g_simple_async_result_get_type(); 246 } 247 248 /** 249 * Creates a #GSimpleAsyncResult. 250 * 251 * The common convention is to create the #GSimpleAsyncResult in the 252 * function that starts the asynchronous operation and use that same 253 * function as the @source_tag. 254 * 255 * If your operation supports cancellation with #GCancellable (which it 256 * probably should) then you should provide the user's cancellable to 257 * g_simple_async_result_set_check_cancellable() immediately after 258 * this function returns. 259 * 260 * Params: 261 * sourceObject = a #GObject, or %NULL. 262 * callback = a #GAsyncReadyCallback. 263 * userData = user data passed to @callback. 264 * sourceTag = the asynchronous function. 265 * 266 * Return: a #GSimpleAsyncResult. 267 * 268 * Throws: ConstructionException GTK+ fails to create the object. 269 */ 270 public this(ObjectG sourceObject, GAsyncReadyCallback callback, void* userData, void* sourceTag) 271 { 272 auto p = g_simple_async_result_new((sourceObject is null) ? null : sourceObject.getObjectGStruct(), callback, userData, sourceTag); 273 274 if(p is null) 275 { 276 throw new ConstructionException("null returned by new"); 277 } 278 279 this(cast(GSimpleAsyncResult*) p, true); 280 } 281 282 /** 283 * Creates a #GSimpleAsyncResult from an error condition. 284 * 285 * Params: 286 * sourceObject = a #GObject, or %NULL. 287 * callback = a #GAsyncReadyCallback. 288 * userData = user data passed to @callback. 289 * error = a #GError 290 * 291 * Return: a #GSimpleAsyncResult. 292 * 293 * Throws: ConstructionException GTK+ fails to create the object. 294 */ 295 public this(ObjectG sourceObject, GAsyncReadyCallback callback, void* userData, ErrorG error) 296 { 297 auto p = g_simple_async_result_new_from_error((sourceObject is null) ? null : sourceObject.getObjectGStruct(), callback, userData, (error is null) ? null : error.getErrorGStruct()); 298 299 if(p is null) 300 { 301 throw new ConstructionException("null returned by new_from_error"); 302 } 303 304 this(cast(GSimpleAsyncResult*) p, true); 305 } 306 307 /** 308 * Ensures that the data passed to the _finish function of an async 309 * operation is consistent. Three checks are performed. 310 * 311 * First, @result is checked to ensure that it is really a 312 * #GSimpleAsyncResult. Second, @source is checked to ensure that it 313 * matches the source object of @result. Third, @source_tag is 314 * checked to ensure that it is equal to the @source_tag argument given 315 * to g_simple_async_result_new() (which, by convention, is a pointer 316 * to the _async function corresponding to the _finish function from 317 * which this function is called). (Alternatively, if either 318 * @source_tag or @result's source tag is %NULL, then the source tag 319 * check is skipped.) 320 * 321 * Params: 322 * result = the #GAsyncResult passed to the _finish function. 323 * source = the #GObject passed to the _finish function. 324 * sourceTag = the asynchronous function. 325 * 326 * Return: #TRUE if all checks passed or #FALSE if any failed. 327 * 328 * Since: 2.20 329 */ 330 public static bool isValid(AsyncResultIF result, ObjectG source, void* sourceTag) 331 { 332 return g_simple_async_result_is_valid((result is null) ? null : result.getAsyncResultStruct(), (source is null) ? null : source.getObjectGStruct(), sourceTag) != 0; 333 } 334 335 /** 336 * Completes an asynchronous I/O job immediately. Must be called in 337 * the thread where the asynchronous result was to be delivered, as it 338 * invokes the callback directly. If you are in a different thread use 339 * g_simple_async_result_complete_in_idle(). 340 * 341 * Calling this function takes a reference to @simple for as long as 342 * is needed to complete the call. 343 */ 344 public void complete() 345 { 346 g_simple_async_result_complete(gSimpleAsyncResult); 347 } 348 349 /** 350 * Completes an asynchronous function in an idle handler in the 351 * [thread-default main context][g-main-context-push-thread-default] 352 * of the thread that @simple was initially created in 353 * (and re-pushes that context around the invocation of the callback). 354 * 355 * Calling this function takes a reference to @simple for as long as 356 * is needed to complete the call. 357 */ 358 public void completeInIdle() 359 { 360 g_simple_async_result_complete_in_idle(gSimpleAsyncResult); 361 } 362 363 /** 364 * Gets the operation result boolean from within the asynchronous result. 365 * 366 * Return: %TRUE if the operation's result was %TRUE, %FALSE 367 * if the operation's result was %FALSE. 368 */ 369 public bool getOpResGboolean() 370 { 371 return g_simple_async_result_get_op_res_gboolean(gSimpleAsyncResult) != 0; 372 } 373 374 /** 375 * Gets a pointer result as returned by the asynchronous function. 376 * 377 * Return: a pointer from the result. 378 */ 379 public void* getOpResGpointer() 380 { 381 return g_simple_async_result_get_op_res_gpointer(gSimpleAsyncResult); 382 } 383 384 /** 385 * Gets a gssize from the asynchronous result. 386 * 387 * Return: a gssize returned from the asynchronous function. 388 */ 389 public ptrdiff_t getOpResGssize() 390 { 391 return g_simple_async_result_get_op_res_gssize(gSimpleAsyncResult); 392 } 393 394 /** 395 * Gets the source tag for the #GSimpleAsyncResult. 396 * 397 * Return: a #gpointer to the source object for the #GSimpleAsyncResult. 398 */ 399 public void* getSourceTag() 400 { 401 return g_simple_async_result_get_source_tag(gSimpleAsyncResult); 402 } 403 404 /** 405 * Propagates an error from within the simple asynchronous result to 406 * a given destination. 407 * 408 * If the #GCancellable given to a prior call to 409 * g_simple_async_result_set_check_cancellable() is cancelled then this 410 * function will return %TRUE with @dest set appropriately. 411 * 412 * Return: %TRUE if the error was propagated to @dest. %FALSE otherwise. 413 * 414 * Throws: GException on failure. 415 */ 416 public bool propagateError() 417 { 418 GError* err = null; 419 420 auto p = g_simple_async_result_propagate_error(gSimpleAsyncResult, &err) != 0; 421 422 if (err !is null) 423 { 424 throw new GException( new ErrorG(err) ); 425 } 426 427 return p; 428 } 429 430 /** 431 * Runs the asynchronous job in a separate thread and then calls 432 * g_simple_async_result_complete_in_idle() on @simple to return 433 * the result to the appropriate main loop. 434 * 435 * Calling this function takes a reference to @simple for as long as 436 * is needed to run the job and report its completion. 437 * 438 * Params: 439 * func = a #GSimpleAsyncThreadFunc. 440 * ioPriority = the io priority of the request. 441 * cancellable = optional #GCancellable object, %NULL to ignore. 442 */ 443 public void runInThread(GSimpleAsyncThreadFunc func, int ioPriority, Cancellable cancellable) 444 { 445 g_simple_async_result_run_in_thread(gSimpleAsyncResult, func, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct()); 446 } 447 448 /** 449 * Sets a #GCancellable to check before dispatching results. 450 * 451 * This function has one very specific purpose: the provided cancellable 452 * is checked at the time of g_simple_async_result_propagate_error() If 453 * it is cancelled, these functions will return an "Operation was 454 * cancelled" error (%G_IO_ERROR_CANCELLED). 455 * 456 * Implementors of cancellable asynchronous functions should use this in 457 * order to provide a guarantee to their callers that cancelling an 458 * async operation will reliably result in an error being returned for 459 * that operation (even if a positive result for the operation has 460 * already been sent as an idle to the main context to be dispatched). 461 * 462 * The checking described above is done regardless of any call to the 463 * unrelated g_simple_async_result_set_handle_cancellation() function. 464 * 465 * Params: 466 * checkCancellable = a #GCancellable to check, or %NULL to unset 467 * 468 * Since: 2.32 469 */ 470 public void setCheckCancellable(Cancellable checkCancellable) 471 { 472 g_simple_async_result_set_check_cancellable(gSimpleAsyncResult, (checkCancellable is null) ? null : checkCancellable.getCancellableStruct()); 473 } 474 475 /** 476 * Sets an error within the asynchronous result without a #GError. 477 * Unless writing a binding, see g_simple_async_result_set_error(). 478 * 479 * Params: 480 * domain = a #GQuark (usually #G_IO_ERROR). 481 * code = an error code. 482 * format = a formatted error reporting string. 483 * args = va_list of arguments. 484 */ 485 public void setErrorVa(GQuark domain, int code, string format, void* args) 486 { 487 g_simple_async_result_set_error_va(gSimpleAsyncResult, domain, code, Str.toStringz(format), args); 488 } 489 490 /** 491 * Sets the result from a #GError. 492 * 493 * Params: 494 * error = #GError. 495 */ 496 public void setFromError(ErrorG error) 497 { 498 g_simple_async_result_set_from_error(gSimpleAsyncResult, (error is null) ? null : error.getErrorGStruct()); 499 } 500 501 /** 502 * Sets whether to handle cancellation within the asynchronous operation. 503 * 504 * This function has nothing to do with 505 * g_simple_async_result_set_check_cancellable(). It only refers to the 506 * #GCancellable passed to g_simple_async_result_run_in_thread(). 507 * 508 * Params: 509 * handleCancellation = a #gboolean. 510 */ 511 public void setHandleCancellation(bool handleCancellation) 512 { 513 g_simple_async_result_set_handle_cancellation(gSimpleAsyncResult, handleCancellation); 514 } 515 516 /** 517 * Sets the operation result to a boolean within the asynchronous result. 518 * 519 * Params: 520 * opRes = a #gboolean. 521 */ 522 public void setOpResGboolean(bool opRes) 523 { 524 g_simple_async_result_set_op_res_gboolean(gSimpleAsyncResult, opRes); 525 } 526 527 /** 528 * Sets the operation result within the asynchronous result to a pointer. 529 * 530 * Params: 531 * opRes = a pointer result from an asynchronous function. 532 * destroyOpRes = a #GDestroyNotify function. 533 */ 534 public void setOpResGpointer(void* opRes, GDestroyNotify destroyOpRes) 535 { 536 g_simple_async_result_set_op_res_gpointer(gSimpleAsyncResult, opRes, destroyOpRes); 537 } 538 539 /** 540 * Sets the operation result within the asynchronous result to 541 * the given @op_res. 542 * 543 * Params: 544 * opRes = a #gssize. 545 */ 546 public void setOpResGssize(ptrdiff_t opRes) 547 { 548 g_simple_async_result_set_op_res_gssize(gSimpleAsyncResult, opRes); 549 } 550 551 /** 552 * Sets the result from @error, and takes over the caller's ownership 553 * of @error, so the caller does not need to free it any more. 554 * 555 * Params: 556 * error = a #GError 557 * 558 * Since: 2.28 559 */ 560 public void takeError(ErrorG error) 561 { 562 g_simple_async_result_take_error(gSimpleAsyncResult, (error is null) ? null : error.getErrorGStruct()); 563 } 564 565 /** 566 * Reports an error in an idle function. Similar to 567 * g_simple_async_report_error_in_idle(), but takes a #GError rather 568 * than building a new one. 569 * 570 * Params: 571 * object = a #GObject, or %NULL 572 * callback = a #GAsyncReadyCallback. 573 * userData = user data passed to @callback. 574 * error = the #GError to report 575 */ 576 public static void simpleAsyncReportGerrorInIdle(ObjectG object, GAsyncReadyCallback callback, void* userData, ErrorG error) 577 { 578 g_simple_async_report_gerror_in_idle((object is null) ? null : object.getObjectGStruct(), callback, userData, (error is null) ? null : error.getErrorGStruct()); 579 } 580 581 /** 582 * Reports an error in an idle function. Similar to 583 * g_simple_async_report_gerror_in_idle(), but takes over the caller's 584 * ownership of @error, so the caller does not have to free it any more. 585 * 586 * Params: 587 * object = a #GObject, or %NULL 588 * callback = a #GAsyncReadyCallback. 589 * userData = user data passed to @callback. 590 * error = the #GError to report 591 * 592 * Since: 2.28 593 */ 594 public static void simpleAsyncReportTakeGerrorInIdle(ObjectG object, GAsyncReadyCallback callback, void* userData, ErrorG error) 595 { 596 g_simple_async_report_take_gerror_in_idle((object is null) ? null : object.getObjectGStruct(), callback, userData, (error is null) ? null : error.getErrorGStruct()); 597 } 598 }