gio/auto/

async_result.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::ffi;
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// `GAsyncResult` provides a base class for implementing asynchronous function results.
    ///
    /// Asynchronous operations are broken up into two separate operations
    /// which are chained together by a `GAsyncReadyCallback`. To begin
    /// an asynchronous operation, provide a `GAsyncReadyCallback` to the
    /// asynchronous function. This callback will be triggered when the
    /// operation has completed, and must be run in a later iteration of
    /// the thread-default main context (see
    /// [`glib::MainContext::push_thread_default()`][crate::glib::MainContext::push_thread_default()]) from where the operation was
    /// initiated. It will be passed a `GAsyncResult` instance filled with the
    /// details of the operation's success or failure, the object the asynchronous
    /// function was started for and any error codes returned. The asynchronous
    /// callback function is then expected to call the corresponding `_finish()`
    /// function, passing the object the function was called for, the
    /// `GAsyncResult` instance, and (optionally) an @error to grab any
    /// error conditions that may have occurred.
    ///
    /// The `_finish()` function for an operation takes the generic result
    /// (of type `GAsyncResult`) and returns the specific result that the
    /// operation in question yields (e.g. a [`FileEnumerator`][crate::FileEnumerator] for a
    /// "enumerate children" operation). If the result or error status of the
    /// operation is not needed, there is no need to call the `_finish()`
    /// function; GIO will take care of cleaning up the result and error
    /// information after the `GAsyncReadyCallback` returns. You can pass
    /// `NULL` for the `GAsyncReadyCallback` if you don't need to take any
    /// action at all after the operation completes. Applications may also
    /// take a reference to the `GAsyncResult` and call `_finish()` later;
    /// however, the `_finish()` function may be called at most once.
    ///
    /// Example of a typical asynchronous operation flow:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// void _theoretical_frobnitz_async (Theoretical         *t,
    ///                                   GCancellable        *c,
    ///                                   GAsyncReadyCallback  cb,
    ///                                   gpointer             u);
    ///
    /// gboolean _theoretical_frobnitz_finish (Theoretical   *t,
    ///                                        GAsyncResult  *res,
    ///                                        GError       **e);
    ///
    /// static void
    /// frobnitz_result_func (GObject      *source_object,
    ///          GAsyncResult *res,
    ///          gpointer      user_data)
    /// {
    ///   gboolean success = FALSE;
    ///
    ///   success = _theoretical_frobnitz_finish (source_object, res, NULL);
    ///
    ///   if (success)
    ///     g_printf ("Hurray!\n");
    ///   else
    ///     g_printf ("Uh oh!\n");
    ///
    ///   ...
    ///
    /// }
    ///
    /// int main (int argc, void *argv[])
    /// {
    ///    ...
    ///
    ///    _theoretical_frobnitz_async (theoretical_data,
    ///                                 NULL,
    ///                                 frobnitz_result_func,
    ///                                 NULL);
    ///
    ///    ...
    /// }
    /// ```
    ///
    /// The callback for an asynchronous operation is called only once, and is
    /// always called, even in the case of a cancelled operation. On cancellation
    /// the result is a `G_IO_ERROR_CANCELLED` error.
    ///
    /// ## I/O Priority
    ///
    /// Many I/O-related asynchronous operations have a priority parameter,
    /// which is used in certain cases to determine the order in which
    /// operations are executed. They are not used to determine system-wide
    /// I/O scheduling. Priorities are integers, with lower numbers indicating
    /// higher priority. It is recommended to choose priorities between
    /// `G_PRIORITY_LOW` and `G_PRIORITY_HIGH`, with `G_PRIORITY_DEFAULT`
    /// as a default.
    ///
    /// # Implements
    ///
    /// [`AsyncResultExt`][trait@crate::prelude::AsyncResultExt]
    #[doc(alias = "GAsyncResult")]
    pub struct AsyncResult(Interface<ffi::GAsyncResult, ffi::GAsyncResultIface>);

    match fn {
        type_ => || ffi::g_async_result_get_type(),
    }
}

impl AsyncResult {
    pub const NONE: Option<&'static AsyncResult> = None;
}

/// Trait containing all [`struct@AsyncResult`] methods.
///
/// # Implementors
///
/// [`AsyncResult`][struct@crate::AsyncResult], [`Task`][struct@crate::Task]
pub trait AsyncResultExt: IsA<AsyncResult> + 'static {
    /// Gets the source object from a [`AsyncResult`][crate::AsyncResult].
    ///
    /// # Returns
    ///
    /// a new reference to the source
    ///    object for the @self, or `NULL` if there is none.
    #[doc(alias = "g_async_result_get_source_object")]
    #[doc(alias = "get_source_object")]
    fn source_object(&self) -> Option<glib::Object> {
        unsafe {
            from_glib_full(ffi::g_async_result_get_source_object(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    //#[doc(alias = "g_async_result_get_user_data")]
    //#[doc(alias = "get_user_data")]
    //fn user_data(&self) -> /*Unimplemented*/Option<Basic: Pointer> {
    //    unsafe { TODO: call ffi:g_async_result_get_user_data() }
    //}

    //#[doc(alias = "g_async_result_is_tagged")]
    //fn is_tagged(&self, source_tag: /*Unimplemented*/Option<Basic: Pointer>) -> bool {
    //    unsafe { TODO: call ffi:g_async_result_is_tagged() }
    //}

    /// If @self is a `Gio::SimpleAsyncResult`, this is equivalent to
    /// `Gio::SimpleAsyncResult::propagate_error()`. Otherwise it returns
    /// `FALSE`.
    ///
    /// This can be used for legacy error handling in async `*_finish()`
    /// wrapper functions that traditionally handled `Gio::SimpleAsyncResult`
    /// error returns themselves rather than calling into the virtual method.
    /// This should not be used in new code; [`AsyncResult`][crate::AsyncResult] errors that are
    /// set by virtual methods should also be extracted by virtual methods,
    /// to enable subclasses to chain up correctly.
    ///
    /// # Returns
    ///
    /// `TRUE` if @error is has been filled in with an error from
    ///   @self, `FALSE` if not.
    #[doc(alias = "g_async_result_legacy_propagate_error")]
    fn legacy_propagate_error(&self) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_async_result_legacy_propagate_error(
                self.as_ref().to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }
}

impl<O: IsA<AsyncResult>> AsyncResultExt for O {}