gio/auto/
dtls_client_connection.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#![allow(deprecated)]
5
6use crate::{ffi, DatagramBased, DtlsConnection, SocketConnectable, TlsCertificateFlags};
7use glib::{
8    prelude::*,
9    signal::{connect_raw, SignalHandlerId},
10    translate::*,
11};
12use std::boxed::Box as Box_;
13
14glib::wrapper! {
15    /// `GDtlsClientConnection` is the client-side subclass of
16    /// [`DtlsConnection`][crate::DtlsConnection], representing a client-side DTLS connection.
17    ///
18    /// ## Properties
19    ///
20    ///
21    /// #### `accepted-cas`
22    ///  A list of the distinguished names of the Certificate Authorities
23    /// that the server will accept client certificates signed by. If the
24    /// server requests a client certificate during the handshake, then
25    /// this property will be set after the handshake completes.
26    ///
27    /// Each item in the list is a #GByteArray which contains the complete
28    /// subject DN of the certificate authority.
29    ///
30    /// Readable
31    ///
32    ///
33    /// #### `server-identity`
34    ///  A #GSocketConnectable describing the identity of the server that
35    /// is expected on the other end of the connection.
36    ///
37    /// If the [`TlsCertificateFlags::BAD_IDENTITY`][crate::TlsCertificateFlags::BAD_IDENTITY] flag is set in
38    /// #GDtlsClientConnection:validation-flags, this object will be used
39    /// to determine the expected identify of the remote end of the
40    /// connection; if #GDtlsClientConnection:server-identity is not set,
41    /// or does not match the identity presented by the server, then the
42    /// [`TlsCertificateFlags::BAD_IDENTITY`][crate::TlsCertificateFlags::BAD_IDENTITY] validation will fail.
43    ///
44    /// In addition to its use in verifying the server certificate,
45    /// this is also used to give a hint to the server about what
46    /// certificate we expect, which is useful for servers that serve
47    /// virtual hosts.
48    ///
49    /// Readable | Writeable | Construct
50    ///
51    ///
52    /// #### `validation-flags`
53    ///  What steps to perform when validating a certificate received from
54    /// a server. Server certificates that fail to validate in any of the
55    /// ways indicated here will be rejected unless the application
56    /// overrides the default via #GDtlsConnection::accept-certificate.
57    ///
58    /// GLib guarantees that if certificate verification fails, at least one
59    /// flag will be set, but it does not guarantee that all possible flags
60    /// will be set. Accordingly, you may not safely decide to ignore any
61    /// particular type of error. For example, it would be incorrect to mask
62    /// [`TlsCertificateFlags::EXPIRED`][crate::TlsCertificateFlags::EXPIRED] if you want to allow expired certificates,
63    /// because this could potentially be the only error flag set even if
64    /// other problems exist with the certificate. Therefore, there is no
65    /// safe way to use this property. This is not a horrible problem,
66    /// though, because you should not be attempting to ignore validation
67    /// errors anyway. If you really must ignore TLS certificate errors,
68    /// connect to #GDtlsConnection::accept-certificate.
69    ///
70    /// Readable | Writeable | Construct
71    /// <details><summary><h4>DtlsConnection</h4></summary>
72    ///
73    ///
74    /// #### `advertised-protocols`
75    ///  The list of application-layer protocols that the connection
76    /// advertises that it is willing to speak. See
77    /// g_dtls_connection_set_advertised_protocols().
78    ///
79    /// Readable | Writeable
80    ///
81    ///
82    /// #### `base-socket`
83    ///  The #GDatagramBased that the connection wraps. Note that this may be any
84    /// implementation of #GDatagramBased, not just a #GSocket.
85    ///
86    /// Readable | Writeable | Construct Only
87    ///
88    ///
89    /// #### `certificate`
90    ///  The connection's certificate; see
91    /// g_dtls_connection_set_certificate().
92    ///
93    /// Readable | Writeable
94    ///
95    ///
96    /// #### `ciphersuite-name`
97    ///  The name of the DTLS ciphersuite in use. See g_dtls_connection_get_ciphersuite_name().
98    ///
99    /// Readable
100    ///
101    ///
102    /// #### `database`
103    ///  The certificate database to use when verifying this TLS connection.
104    /// If no certificate database is set, then the default database will be
105    /// used. See g_tls_backend_get_default_database().
106    ///
107    /// When using a non-default database, #GDtlsConnection must fall back to using
108    /// the #GTlsDatabase to perform certificate verification using
109    /// g_tls_database_verify_chain(), which means certificate verification will
110    /// not be able to make use of TLS session context. This may be less secure.
111    /// For example, if you create your own #GTlsDatabase that just wraps the
112    /// default #GTlsDatabase, you might expect that you have not changed anything,
113    /// but this is not true because you may have altered the behavior of
114    /// #GDtlsConnection by causing it to use g_tls_database_verify_chain(). See the
115    /// documentation of g_tls_database_verify_chain() for more details on specific
116    /// security checks that may not be performed. Accordingly, setting a
117    /// non-default database is discouraged except for specialty applications with
118    /// unusual security requirements.
119    ///
120    /// Readable | Writeable
121    ///
122    ///
123    /// #### `interaction`
124    ///  A #GTlsInteraction object to be used when the connection or certificate
125    /// database need to interact with the user. This will be used to prompt the
126    /// user for passwords where necessary.
127    ///
128    /// Readable | Writeable
129    ///
130    ///
131    /// #### `negotiated-protocol`
132    ///  The application-layer protocol negotiated during the TLS
133    /// handshake. See g_dtls_connection_get_negotiated_protocol().
134    ///
135    /// Readable
136    ///
137    ///
138    /// #### `peer-certificate`
139    ///  The connection's peer's certificate, after the TLS handshake has
140    /// completed or failed. Note in particular that this is not yet set
141    /// during the emission of #GDtlsConnection::accept-certificate.
142    ///
143    /// (You can watch for a #GObject::notify signal on this property to
144    /// detect when a handshake has occurred.)
145    ///
146    /// Readable
147    ///
148    ///
149    /// #### `peer-certificate-errors`
150    ///  The errors noticed while verifying
151    /// #GDtlsConnection:peer-certificate. Normally this should be 0, but
152    /// it may not be if #GDtlsClientConnection:validation-flags is not
153    /// [`TlsCertificateFlags::VALIDATE_ALL`][crate::TlsCertificateFlags::VALIDATE_ALL], or if
154    /// #GDtlsConnection::accept-certificate overrode the default
155    /// behavior.
156    ///
157    /// GLib guarantees that if certificate verification fails, at least
158    /// one error will be set, but it does not guarantee that all possible
159    /// errors will be set. Accordingly, you may not safely decide to
160    /// ignore any particular type of error. For example, it would be
161    /// incorrect to mask [`TlsCertificateFlags::EXPIRED`][crate::TlsCertificateFlags::EXPIRED] if you want to allow
162    /// expired certificates, because this could potentially be the only
163    /// error flag set even if other problems exist with the certificate.
164    ///
165    /// Readable
166    ///
167    ///
168    /// #### `protocol-version`
169    ///  The DTLS protocol version in use. See g_dtls_connection_get_protocol_version().
170    ///
171    /// Readable
172    ///
173    ///
174    /// #### `rehandshake-mode`
175    ///  The rehandshaking mode. See
176    /// g_dtls_connection_set_rehandshake_mode().
177    ///
178    /// Readable | Writeable | Construct
179    ///
180    ///
181    /// #### `require-close-notify`
182    ///  Whether or not proper TLS close notification is required.
183    /// See g_dtls_connection_set_require_close_notify().
184    ///
185    /// Readable | Writeable | Construct
186    /// </details>
187    ///
188    /// # Implements
189    ///
190    /// [`DtlsClientConnectionExt`][trait@crate::prelude::DtlsClientConnectionExt], [`DatagramBasedExt`][trait@crate::prelude::DatagramBasedExt], [`DtlsConnectionExt`][trait@crate::prelude::DtlsConnectionExt], [`DatagramBasedExtManual`][trait@crate::prelude::DatagramBasedExtManual]
191    #[doc(alias = "GDtlsClientConnection")]
192    pub struct DtlsClientConnection(Interface<ffi::GDtlsClientConnection, ffi::GDtlsClientConnectionInterface>) @requires DatagramBased, DtlsConnection;
193
194    match fn {
195        type_ => || ffi::g_dtls_client_connection_get_type(),
196    }
197}
198
199impl DtlsClientConnection {
200    pub const NONE: Option<&'static DtlsClientConnection> = None;
201
202    /// Creates a new #GDtlsClientConnection wrapping @base_socket which is
203    /// assumed to communicate with the server identified by @server_identity.
204    /// ## `base_socket`
205    /// the #GDatagramBased to wrap
206    /// ## `server_identity`
207    /// the expected identity of the server
208    ///
209    /// # Returns
210    ///
211    /// the new
212    ///   #GDtlsClientConnection, or [`None`] on error
213    #[doc(alias = "g_dtls_client_connection_new")]
214    pub fn new(
215        base_socket: &impl IsA<DatagramBased>,
216        server_identity: Option<&impl IsA<SocketConnectable>>,
217    ) -> Result<DtlsClientConnection, glib::Error> {
218        unsafe {
219            let mut error = std::ptr::null_mut();
220            let ret = ffi::g_dtls_client_connection_new(
221                base_socket.as_ref().to_glib_none().0,
222                server_identity.map(|p| p.as_ref()).to_glib_none().0,
223                &mut error,
224            );
225            if error.is_null() {
226                Ok(from_glib_full(ret))
227            } else {
228                Err(from_glib_full(error))
229            }
230        }
231    }
232}
233
234mod sealed {
235    pub trait Sealed {}
236    impl<T: super::IsA<super::DtlsClientConnection>> Sealed for T {}
237}
238
239/// Trait containing all [`struct@DtlsClientConnection`] methods.
240///
241/// # Implementors
242///
243/// [`DtlsClientConnection`][struct@crate::DtlsClientConnection]
244pub trait DtlsClientConnectionExt: IsA<DtlsClientConnection> + sealed::Sealed + 'static {
245    /// Gets the list of distinguished names of the Certificate Authorities
246    /// that the server will accept certificates from. This will be set
247    /// during the TLS handshake if the server requests a certificate.
248    /// Otherwise, it will be [`None`].
249    ///
250    /// Each item in the list is a #GByteArray which contains the complete
251    /// subject DN of the certificate authority.
252    ///
253    /// # Returns
254    ///
255    /// the list of
256    /// CA DNs. You should unref each element with g_byte_array_unref() and then
257    /// the free the list with g_list_free().
258    #[doc(alias = "g_dtls_client_connection_get_accepted_cas")]
259    #[doc(alias = "get_accepted_cas")]
260    #[doc(alias = "accepted-cas")]
261    fn accepted_cas(&self) -> Vec<glib::ByteArray> {
262        unsafe {
263            FromGlibPtrContainer::from_glib_full(ffi::g_dtls_client_connection_get_accepted_cas(
264                self.as_ref().to_glib_none().0,
265            ))
266        }
267    }
268
269    /// Gets @self's expected server identity
270    ///
271    /// # Returns
272    ///
273    /// a #GSocketConnectable describing the
274    /// expected server identity, or [`None`] if the expected identity is not
275    /// known.
276    #[doc(alias = "g_dtls_client_connection_get_server_identity")]
277    #[doc(alias = "get_server_identity")]
278    #[doc(alias = "server-identity")]
279    fn server_identity(&self) -> SocketConnectable {
280        unsafe {
281            from_glib_none(ffi::g_dtls_client_connection_get_server_identity(
282                self.as_ref().to_glib_none().0,
283            ))
284        }
285    }
286
287    /// Gets @self's validation flags
288    ///
289    /// This function does not work as originally designed and is impossible
290    /// to use correctly. See #GDtlsClientConnection:validation-flags for more
291    /// information.
292    ///
293    /// # Deprecated since 2.74
294    ///
295    /// Do not attempt to ignore validation errors.
296    ///
297    /// # Returns
298    ///
299    /// the validation flags
300    #[cfg_attr(feature = "v2_74", deprecated = "Since 2.74")]
301    #[allow(deprecated)]
302    #[doc(alias = "g_dtls_client_connection_get_validation_flags")]
303    #[doc(alias = "get_validation_flags")]
304    #[doc(alias = "validation-flags")]
305    fn validation_flags(&self) -> TlsCertificateFlags {
306        unsafe {
307            from_glib(ffi::g_dtls_client_connection_get_validation_flags(
308                self.as_ref().to_glib_none().0,
309            ))
310        }
311    }
312
313    /// Sets @self's expected server identity, which is used both to tell
314    /// servers on virtual hosts which certificate to present, and also
315    /// to let @self know what name to look for in the certificate when
316    /// performing [`TlsCertificateFlags::BAD_IDENTITY`][crate::TlsCertificateFlags::BAD_IDENTITY] validation, if enabled.
317    /// ## `identity`
318    /// a #GSocketConnectable describing the expected server identity
319    #[doc(alias = "g_dtls_client_connection_set_server_identity")]
320    #[doc(alias = "server-identity")]
321    fn set_server_identity(&self, identity: &impl IsA<SocketConnectable>) {
322        unsafe {
323            ffi::g_dtls_client_connection_set_server_identity(
324                self.as_ref().to_glib_none().0,
325                identity.as_ref().to_glib_none().0,
326            );
327        }
328    }
329
330    /// Sets @self's validation flags, to override the default set of
331    /// checks performed when validating a server certificate. By default,
332    /// [`TlsCertificateFlags::VALIDATE_ALL`][crate::TlsCertificateFlags::VALIDATE_ALL] is used.
333    ///
334    /// This function does not work as originally designed and is impossible
335    /// to use correctly. See #GDtlsClientConnection:validation-flags for more
336    /// information.
337    ///
338    /// # Deprecated since 2.74
339    ///
340    /// Do not attempt to ignore validation errors.
341    /// ## `flags`
342    /// the #GTlsCertificateFlags to use
343    #[cfg_attr(feature = "v2_74", deprecated = "Since 2.74")]
344    #[allow(deprecated)]
345    #[doc(alias = "g_dtls_client_connection_set_validation_flags")]
346    #[doc(alias = "validation-flags")]
347    fn set_validation_flags(&self, flags: TlsCertificateFlags) {
348        unsafe {
349            ffi::g_dtls_client_connection_set_validation_flags(
350                self.as_ref().to_glib_none().0,
351                flags.into_glib(),
352            );
353        }
354    }
355
356    #[doc(alias = "accepted-cas")]
357    fn connect_accepted_cas_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
358        unsafe extern "C" fn notify_accepted_cas_trampoline<
359            P: IsA<DtlsClientConnection>,
360            F: Fn(&P) + 'static,
361        >(
362            this: *mut ffi::GDtlsClientConnection,
363            _param_spec: glib::ffi::gpointer,
364            f: glib::ffi::gpointer,
365        ) {
366            let f: &F = &*(f as *const F);
367            f(DtlsClientConnection::from_glib_borrow(this).unsafe_cast_ref())
368        }
369        unsafe {
370            let f: Box_<F> = Box_::new(f);
371            connect_raw(
372                self.as_ptr() as *mut _,
373                b"notify::accepted-cas\0".as_ptr() as *const _,
374                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
375                    notify_accepted_cas_trampoline::<Self, F> as *const (),
376                )),
377                Box_::into_raw(f),
378            )
379        }
380    }
381
382    #[doc(alias = "server-identity")]
383    fn connect_server_identity_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
384        unsafe extern "C" fn notify_server_identity_trampoline<
385            P: IsA<DtlsClientConnection>,
386            F: Fn(&P) + 'static,
387        >(
388            this: *mut ffi::GDtlsClientConnection,
389            _param_spec: glib::ffi::gpointer,
390            f: glib::ffi::gpointer,
391        ) {
392            let f: &F = &*(f as *const F);
393            f(DtlsClientConnection::from_glib_borrow(this).unsafe_cast_ref())
394        }
395        unsafe {
396            let f: Box_<F> = Box_::new(f);
397            connect_raw(
398                self.as_ptr() as *mut _,
399                b"notify::server-identity\0".as_ptr() as *const _,
400                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
401                    notify_server_identity_trampoline::<Self, F> as *const (),
402                )),
403                Box_::into_raw(f),
404            )
405        }
406    }
407
408    #[cfg_attr(feature = "v2_74", deprecated = "Since 2.74")]
409    #[doc(alias = "validation-flags")]
410    fn connect_validation_flags_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
411        unsafe extern "C" fn notify_validation_flags_trampoline<
412            P: IsA<DtlsClientConnection>,
413            F: Fn(&P) + 'static,
414        >(
415            this: *mut ffi::GDtlsClientConnection,
416            _param_spec: glib::ffi::gpointer,
417            f: glib::ffi::gpointer,
418        ) {
419            let f: &F = &*(f as *const F);
420            f(DtlsClientConnection::from_glib_borrow(this).unsafe_cast_ref())
421        }
422        unsafe {
423            let f: Box_<F> = Box_::new(f);
424            connect_raw(
425                self.as_ptr() as *mut _,
426                b"notify::validation-flags\0".as_ptr() as *const _,
427                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
428                    notify_validation_flags_trampoline::<Self, F> as *const (),
429                )),
430                Box_::into_raw(f),
431            )
432        }
433    }
434}
435
436impl<O: IsA<DtlsClientConnection>> DtlsClientConnectionExt for O {}