gio/auto/
socket_connectable.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, SocketAddressEnumerator};
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9    /// Objects that describe one or more potential socket endpoints
10    /// implement `GSocketConnectable`. Callers can then use
11    /// [`SocketConnectableExt::enumerate()`][crate::prelude::SocketConnectableExt::enumerate()] to get a
12    /// [`SocketAddressEnumerator`][crate::SocketAddressEnumerator] to try out each socket address in turn
13    /// until one succeeds, as shown in the sample code below.
14    ///
15    /// **⚠️ The following code is in c ⚠️**
16    ///
17    /// ```c
18    /// MyConnectionType *
19    /// connect_to_host (const char    *hostname,
20    ///                  guint16        port,
21    ///                  GCancellable  *cancellable,
22    ///                  GError       **error)
23    /// {
24    ///   MyConnection *conn = NULL;
25    ///   GSocketConnectable *addr;
26    ///   GSocketAddressEnumerator *enumerator;
27    ///   GSocketAddress *sockaddr;
28    ///   GError *conn_error = NULL;
29    ///
30    ///   addr = g_network_address_new (hostname, port);
31    ///   enumerator = g_socket_connectable_enumerate (addr);
32    ///   g_object_unref (addr);
33    ///
34    ///   // Try each sockaddr until we succeed. Record the first connection error,
35    ///   // but not any further ones (since they'll probably be basically the same
36    ///   // as the first).
37    ///   while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
38    ///     {
39    ///       conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
40    ///       g_object_unref (sockaddr);
41    ///     }
42    ///   g_object_unref (enumerator);
43    ///
44    ///   if (conn)
45    ///     {
46    ///       if (conn_error)
47    ///         {
48    ///           // We couldn't connect to the first address, but we succeeded
49    ///           // in connecting to a later address.
50    ///           g_error_free (conn_error);
51    ///         }
52    ///       return conn;
53    ///     }
54    ///   else if (error)
55    ///     {
56    ///       /// Either initial lookup failed, or else the caller cancelled us.
57    ///       if (conn_error)
58    ///         g_error_free (conn_error);
59    ///       return NULL;
60    ///     }
61    ///   else
62    ///     {
63    ///       g_error_propagate (error, conn_error);
64    ///       return NULL;
65    ///     }
66    /// }
67    /// ```
68    ///
69    /// # Implements
70    ///
71    /// [`SocketConnectableExt`][trait@crate::prelude::SocketConnectableExt]
72    #[doc(alias = "GSocketConnectable")]
73    pub struct SocketConnectable(Interface<ffi::GSocketConnectable, ffi::GSocketConnectableIface>);
74
75    match fn {
76        type_ => || ffi::g_socket_connectable_get_type(),
77    }
78}
79
80impl SocketConnectable {
81    pub const NONE: Option<&'static SocketConnectable> = None;
82}
83
84mod sealed {
85    pub trait Sealed {}
86    impl<T: super::IsA<super::SocketConnectable>> Sealed for T {}
87}
88
89/// Trait containing all [`struct@SocketConnectable`] methods.
90///
91/// # Implementors
92///
93/// [`InetSocketAddress`][struct@crate::InetSocketAddress], [`NativeSocketAddress`][struct@crate::NativeSocketAddress], [`NetworkAddress`][struct@crate::NetworkAddress], [`NetworkService`][struct@crate::NetworkService], [`ProxyAddress`][struct@crate::ProxyAddress], [`SocketAddress`][struct@crate::SocketAddress], [`SocketConnectable`][struct@crate::SocketConnectable], [`UnixSocketAddress`][struct@crate::UnixSocketAddress]
94pub trait SocketConnectableExt: IsA<SocketConnectable> + sealed::Sealed + 'static {
95    /// Creates a #GSocketAddressEnumerator for @self.
96    ///
97    /// # Returns
98    ///
99    /// a new #GSocketAddressEnumerator.
100    #[doc(alias = "g_socket_connectable_enumerate")]
101    fn enumerate(&self) -> SocketAddressEnumerator {
102        unsafe {
103            from_glib_full(ffi::g_socket_connectable_enumerate(
104                self.as_ref().to_glib_none().0,
105            ))
106        }
107    }
108
109    /// Creates a #GSocketAddressEnumerator for @self that will
110    /// return a #GProxyAddress for each of its addresses that you must connect
111    /// to via a proxy.
112    ///
113    /// If @self does not implement
114    /// g_socket_connectable_proxy_enumerate(), this will fall back to
115    /// calling g_socket_connectable_enumerate().
116    ///
117    /// # Returns
118    ///
119    /// a new #GSocketAddressEnumerator.
120    #[doc(alias = "g_socket_connectable_proxy_enumerate")]
121    fn proxy_enumerate(&self) -> SocketAddressEnumerator {
122        unsafe {
123            from_glib_full(ffi::g_socket_connectable_proxy_enumerate(
124                self.as_ref().to_glib_none().0,
125            ))
126        }
127    }
128
129    /// Format a #GSocketConnectable as a string. This is a human-readable format for
130    /// use in debugging output, and is not a stable serialization format. It is not
131    /// suitable for use in user interfaces as it exposes too much information for a
132    /// user.
133    ///
134    /// If the #GSocketConnectable implementation does not support string formatting,
135    /// the implementation’s type name will be returned as a fallback.
136    ///
137    /// # Returns
138    ///
139    /// the formatted string
140    #[doc(alias = "g_socket_connectable_to_string")]
141    fn to_string(&self) -> glib::GString {
142        unsafe {
143            from_glib_full(ffi::g_socket_connectable_to_string(
144                self.as_ref().to_glib_none().0,
145            ))
146        }
147    }
148}
149
150impl<O: IsA<SocketConnectable>> SocketConnectableExt for O {}