gio/auto/
async_result.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::ffi;
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9    /// `GAsyncResult` provides a base class for implementing asynchronous function results.
10    ///
11    /// Asynchronous operations are broken up into two separate operations
12    /// which are chained together by a `GAsyncReadyCallback`. To begin
13    /// an asynchronous operation, provide a `GAsyncReadyCallback` to the
14    /// asynchronous function. This callback will be triggered when the
15    /// operation has completed, and must be run in a later iteration of
16    /// the thread-default main context (see
17    /// [`glib::MainContext::push_thread_default()`][crate::glib::MainContext::push_thread_default()]) from where the operation was
18    /// initiated. It will be passed a `GAsyncResult` instance filled with the
19    /// details of the operation's success or failure, the object the asynchronous
20    /// function was started for and any error codes returned. The asynchronous
21    /// callback function is then expected to call the corresponding `_finish()`
22    /// function, passing the object the function was called for, the
23    /// `GAsyncResult` instance, and (optionally) an @error to grab any
24    /// error conditions that may have occurred.
25    ///
26    /// The `_finish()` function for an operation takes the generic result
27    /// (of type `GAsyncResult`) and returns the specific result that the
28    /// operation in question yields (e.g. a [`FileEnumerator`][crate::FileEnumerator] for a
29    /// "enumerate children" operation). If the result or error status of the
30    /// operation is not needed, there is no need to call the `_finish()`
31    /// function; GIO will take care of cleaning up the result and error
32    /// information after the `GAsyncReadyCallback` returns. You can pass
33    /// `NULL` for the `GAsyncReadyCallback` if you don't need to take any
34    /// action at all after the operation completes. Applications may also
35    /// take a reference to the `GAsyncResult` and call `_finish()` later;
36    /// however, the `_finish()` function may be called at most once.
37    ///
38    /// Example of a typical asynchronous operation flow:
39    ///
40    /// **⚠️ The following code is in c ⚠️**
41    ///
42    /// ```c
43    /// void _theoretical_frobnitz_async (Theoretical         *t,
44    ///                                   GCancellable        *c,
45    ///                                   GAsyncReadyCallback  cb,
46    ///                                   gpointer             u);
47    ///
48    /// gboolean _theoretical_frobnitz_finish (Theoretical   *t,
49    ///                                        GAsyncResult  *res,
50    ///                                        GError       **e);
51    ///
52    /// static void
53    /// frobnitz_result_func (GObject      *source_object,
54    ///          GAsyncResult *res,
55    ///          gpointer      user_data)
56    /// {
57    ///   gboolean success = FALSE;
58    ///
59    ///   success = _theoretical_frobnitz_finish (source_object, res, NULL);
60    ///
61    ///   if (success)
62    ///     g_printf ("Hurray!\n");
63    ///   else
64    ///     g_printf ("Uh oh!\n");
65    ///
66    ///   ...
67    ///
68    /// }
69    ///
70    /// int main (int argc, void *argv[])
71    /// {
72    ///    ...
73    ///
74    ///    _theoretical_frobnitz_async (theoretical_data,
75    ///                                 NULL,
76    ///                                 frobnitz_result_func,
77    ///                                 NULL);
78    ///
79    ///    ...
80    /// }
81    /// ```
82    ///
83    /// The callback for an asynchronous operation is called only once, and is
84    /// always called, even in the case of a cancelled operation. On cancellation
85    /// the result is a `G_IO_ERROR_CANCELLED` error.
86    ///
87    /// ## I/O Priority
88    ///
89    /// Many I/O-related asynchronous operations have a priority parameter,
90    /// which is used in certain cases to determine the order in which
91    /// operations are executed. They are not used to determine system-wide
92    /// I/O scheduling. Priorities are integers, with lower numbers indicating
93    /// higher priority. It is recommended to choose priorities between
94    /// `G_PRIORITY_LOW` and `G_PRIORITY_HIGH`, with `G_PRIORITY_DEFAULT`
95    /// as a default.
96    ///
97    /// # Implements
98    ///
99    /// [`AsyncResultExt`][trait@crate::prelude::AsyncResultExt]
100    #[doc(alias = "GAsyncResult")]
101    pub struct AsyncResult(Interface<ffi::GAsyncResult, ffi::GAsyncResultIface>);
102
103    match fn {
104        type_ => || ffi::g_async_result_get_type(),
105    }
106}
107
108impl AsyncResult {
109    pub const NONE: Option<&'static AsyncResult> = None;
110}
111
112mod sealed {
113    pub trait Sealed {}
114    impl<T: super::IsA<super::AsyncResult>> Sealed for T {}
115}
116
117/// Trait containing all [`struct@AsyncResult`] methods.
118///
119/// # Implementors
120///
121/// [`AsyncResult`][struct@crate::AsyncResult], [`Task`][struct@crate::Task]
122pub trait AsyncResultExt: IsA<AsyncResult> + sealed::Sealed + 'static {
123    /// Gets the source object from a [`AsyncResult`][crate::AsyncResult].
124    ///
125    /// # Returns
126    ///
127    /// a new reference to the source
128    ///    object for the @self, or `NULL` if there is none.
129    #[doc(alias = "g_async_result_get_source_object")]
130    #[doc(alias = "get_source_object")]
131    fn source_object(&self) -> Option<glib::Object> {
132        unsafe {
133            from_glib_full(ffi::g_async_result_get_source_object(
134                self.as_ref().to_glib_none().0,
135            ))
136        }
137    }
138
139    //#[doc(alias = "g_async_result_get_user_data")]
140    //#[doc(alias = "get_user_data")]
141    //fn user_data(&self) -> /*Unimplemented*/Option<Basic: Pointer> {
142    //    unsafe { TODO: call ffi:g_async_result_get_user_data() }
143    //}
144
145    //#[doc(alias = "g_async_result_is_tagged")]
146    //fn is_tagged(&self, source_tag: /*Unimplemented*/Option<Basic: Pointer>) -> bool {
147    //    unsafe { TODO: call ffi:g_async_result_is_tagged() }
148    //}
149
150    /// If @self is a `Gio::SimpleAsyncResult`, this is equivalent to
151    /// `Gio::SimpleAsyncResult::propagate_error()`. Otherwise it returns
152    /// `FALSE`.
153    ///
154    /// This can be used for legacy error handling in async `*_finish()`
155    /// wrapper functions that traditionally handled `Gio::SimpleAsyncResult`
156    /// error returns themselves rather than calling into the virtual method.
157    /// This should not be used in new code; [`AsyncResult`][crate::AsyncResult] errors that are
158    /// set by virtual methods should also be extracted by virtual methods,
159    /// to enable subclasses to chain up correctly.
160    ///
161    /// # Returns
162    ///
163    /// `TRUE` if @error is has been filled in with an error from
164    ///   @self, `FALSE` if not.
165    #[doc(alias = "g_async_result_legacy_propagate_error")]
166    fn legacy_propagate_error(&self) -> Result<(), glib::Error> {
167        unsafe {
168            let mut error = std::ptr::null_mut();
169            let is_ok = ffi::g_async_result_legacy_propagate_error(
170                self.as_ref().to_glib_none().0,
171                &mut error,
172            );
173            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
174            if error.is_null() {
175                Ok(())
176            } else {
177                Err(from_glib_full(error))
178            }
179        }
180    }
181}
182
183impl<O: IsA<AsyncResult>> AsyncResultExt for O {}