gio/auto/
socket_address_enumerator.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, AsyncResult, Cancellable, SocketAddress};
6use glib::{prelude::*, translate::*};
7use std::{boxed::Box as Box_, pin::Pin};
8
9glib::wrapper! {
10    /// `GSocketAddressEnumerator` is an enumerator type for
11    /// [`SocketAddress`][crate::SocketAddress] instances. It is returned by enumeration functions
12    /// such as [`SocketConnectableExt::enumerate()`][crate::prelude::SocketConnectableExt::enumerate()], which returns a
13    /// `GSocketAddressEnumerator` to list each [`SocketAddress`][crate::SocketAddress] which could
14    /// be used to connect to that [`SocketConnectable`][crate::SocketConnectable].
15    ///
16    /// Enumeration is typically a blocking operation, so the asynchronous methods
17    /// [`SocketAddressEnumeratorExt::next_async()`][crate::prelude::SocketAddressEnumeratorExt::next_async()] and
18    /// `Gio::SocketAddressEnumerator::next_finish()` should be used where
19    /// possible.
20    ///
21    /// Each `GSocketAddressEnumerator` can only be enumerated once. Once
22    /// [`SocketAddressEnumeratorExt::next()`][crate::prelude::SocketAddressEnumeratorExt::next()] has returned `NULL`, further
23    /// enumeration with that `GSocketAddressEnumerator` is not possible, and it can
24    /// be unreffed.
25    ///
26    /// This is an Abstract Base Class, you cannot instantiate it.
27    ///
28    /// # Implements
29    ///
30    /// [`SocketAddressEnumeratorExt`][trait@crate::prelude::SocketAddressEnumeratorExt], [`trait@glib::ObjectExt`]
31    #[doc(alias = "GSocketAddressEnumerator")]
32    pub struct SocketAddressEnumerator(Object<ffi::GSocketAddressEnumerator, ffi::GSocketAddressEnumeratorClass>);
33
34    match fn {
35        type_ => || ffi::g_socket_address_enumerator_get_type(),
36    }
37}
38
39impl SocketAddressEnumerator {
40    pub const NONE: Option<&'static SocketAddressEnumerator> = None;
41}
42
43mod sealed {
44    pub trait Sealed {}
45    impl<T: super::IsA<super::SocketAddressEnumerator>> Sealed for T {}
46}
47
48/// Trait containing all [`struct@SocketAddressEnumerator`] methods.
49///
50/// # Implementors
51///
52/// [`ProxyAddressEnumerator`][struct@crate::ProxyAddressEnumerator], [`SocketAddressEnumerator`][struct@crate::SocketAddressEnumerator]
53pub trait SocketAddressEnumeratorExt:
54    IsA<SocketAddressEnumerator> + sealed::Sealed + 'static
55{
56    /// Retrieves the next #GSocketAddress from @self. Note that this
57    /// may block for some amount of time. (Eg, a #GNetworkAddress may need
58    /// to do a DNS lookup before it can return an address.) Use
59    /// g_socket_address_enumerator_next_async() if you need to avoid
60    /// blocking.
61    ///
62    /// If @self is expected to yield addresses, but for some reason
63    /// is unable to (eg, because of a DNS error), then the first call to
64    /// g_socket_address_enumerator_next() will return an appropriate error
65    /// in `*error`. However, if the first call to
66    /// g_socket_address_enumerator_next() succeeds, then any further
67    /// internal errors (other than @cancellable being triggered) will be
68    /// ignored.
69    /// ## `cancellable`
70    /// optional #GCancellable object, [`None`] to ignore.
71    ///
72    /// # Returns
73    ///
74    /// a #GSocketAddress (owned by the caller), or [`None`] on
75    ///     error (in which case `*error` will be set) or if there are no
76    ///     more addresses.
77    #[doc(alias = "g_socket_address_enumerator_next")]
78    fn next(
79        &self,
80        cancellable: Option<&impl IsA<Cancellable>>,
81    ) -> Result<Option<SocketAddress>, glib::Error> {
82        unsafe {
83            let mut error = std::ptr::null_mut();
84            let ret = ffi::g_socket_address_enumerator_next(
85                self.as_ref().to_glib_none().0,
86                cancellable.map(|p| p.as_ref()).to_glib_none().0,
87                &mut error,
88            );
89            if error.is_null() {
90                Ok(from_glib_full(ret))
91            } else {
92                Err(from_glib_full(error))
93            }
94        }
95    }
96
97    /// Asynchronously retrieves the next #GSocketAddress from @self
98    /// and then calls @callback, which must call
99    /// g_socket_address_enumerator_next_finish() to get the result.
100    ///
101    /// It is an error to call this multiple times before the previous callback has finished.
102    /// ## `cancellable`
103    /// optional #GCancellable object, [`None`] to ignore.
104    /// ## `callback`
105    /// a #GAsyncReadyCallback to call
106    ///   when the request is satisfied
107    #[doc(alias = "g_socket_address_enumerator_next_async")]
108    fn next_async<P: FnOnce(Result<Option<SocketAddress>, glib::Error>) + 'static>(
109        &self,
110        cancellable: Option<&impl IsA<Cancellable>>,
111        callback: P,
112    ) {
113        let main_context = glib::MainContext::ref_thread_default();
114        let is_main_context_owner = main_context.is_owner();
115        let has_acquired_main_context = (!is_main_context_owner)
116            .then(|| main_context.acquire().ok())
117            .flatten();
118        assert!(
119            is_main_context_owner || has_acquired_main_context.is_some(),
120            "Async operations only allowed if the thread is owning the MainContext"
121        );
122
123        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
124            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
125        unsafe extern "C" fn next_async_trampoline<
126            P: FnOnce(Result<Option<SocketAddress>, glib::Error>) + 'static,
127        >(
128            _source_object: *mut glib::gobject_ffi::GObject,
129            res: *mut crate::ffi::GAsyncResult,
130            user_data: glib::ffi::gpointer,
131        ) {
132            let mut error = std::ptr::null_mut();
133            let ret = ffi::g_socket_address_enumerator_next_finish(
134                _source_object as *mut _,
135                res,
136                &mut error,
137            );
138            let result = if error.is_null() {
139                Ok(from_glib_full(ret))
140            } else {
141                Err(from_glib_full(error))
142            };
143            let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
144                Box_::from_raw(user_data as *mut _);
145            let callback: P = callback.into_inner();
146            callback(result);
147        }
148        let callback = next_async_trampoline::<P>;
149        unsafe {
150            ffi::g_socket_address_enumerator_next_async(
151                self.as_ref().to_glib_none().0,
152                cancellable.map(|p| p.as_ref()).to_glib_none().0,
153                Some(callback),
154                Box_::into_raw(user_data) as *mut _,
155            );
156        }
157    }
158
159    fn next_future(
160        &self,
161    ) -> Pin<
162        Box_<
163            dyn std::future::Future<Output = Result<Option<SocketAddress>, glib::Error>> + 'static,
164        >,
165    > {
166        Box_::pin(crate::GioFuture::new(
167            self,
168            move |obj, cancellable, send| {
169                obj.next_async(Some(cancellable), move |res| {
170                    send.resolve(res);
171                });
172            },
173        ))
174    }
175}
176
177impl<O: IsA<SocketAddressEnumerator>> SocketAddressEnumeratorExt for O {}