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 {}