// 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 glib::{prelude::*, translate::*};
use std::{fmt, ptr};

glib::wrapper! {
    /// 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][g-main-context-push-thread-default]
    /// from where the operation was initiated. It will be passed a
    /// [`AsyncResult`][crate::AsyncResult] 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
    /// [`AsyncResult`][crate::AsyncResult] 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 [`AsyncResult`][crate::AsyncResult]) 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
    /// [`None`] 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 [`AsyncResult`][crate::AsyncResult] 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 [`IOErrorEnum::Cancelled`][crate::IOErrorEnum::Cancelled] error.
    ///
    /// ## I/O Priority # {`io`-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;
}

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::AsyncResult>> Sealed for T {}
}

/// Trait containing all [`struct@AsyncResult`] methods.
///
/// # Implementors
///
/// [`AsyncResult`][struct@crate::AsyncResult], [`Task`][struct@crate::Task]
pub trait AsyncResultExt: IsA<AsyncResult> + sealed::Sealed + 'static {
    /// Gets the source object from a [`AsyncResult`][crate::AsyncResult].
    ///
    /// # Returns
    ///
    /// a new reference to the source
    ///  object for the `self`, or [`None`] 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 `GSimpleAsyncResult`, this is equivalent to
    /// `g_simple_async_result_propagate_error()`. Otherwise it returns
    /// [`false`].
    ///
    /// This can be used for legacy error handling in async *`_finish()`
    /// wrapper functions that traditionally handled `GSimpleAsyncResult`
    /// 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 = 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 {}

impl fmt::Display for AsyncResult {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("AsyncResult")
    }
}