gio/auto/

dtls_client_connection.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT
#![allow(deprecated)]

use crate::{ffi, DatagramBased, DtlsConnection, SocketConnectable, TlsCertificateFlags};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// `GDtlsClientConnection` is the client-side subclass of
    /// [`DtlsConnection`][crate::DtlsConnection], representing a client-side DTLS connection.
    ///
    /// ## Properties
    ///
    ///
    /// #### `accepted-cas`
    ///  A list of the distinguished names of the Certificate Authorities
    /// that the server will accept client certificates signed by. If the
    /// server requests a client certificate during the handshake, then
    /// this property will be set after the handshake completes.
    ///
    /// Each item in the list is a #GByteArray which contains the complete
    /// subject DN of the certificate authority.
    ///
    /// Readable
    ///
    ///
    /// #### `server-identity`
    ///  A #GSocketConnectable describing the identity of the server that
    /// is expected on the other end of the connection.
    ///
    /// If the [`TlsCertificateFlags::BAD_IDENTITY`][crate::TlsCertificateFlags::BAD_IDENTITY] flag is set in
    /// #GDtlsClientConnection:validation-flags, this object will be used
    /// to determine the expected identify of the remote end of the
    /// connection; if #GDtlsClientConnection:server-identity is not set,
    /// or does not match the identity presented by the server, then the
    /// [`TlsCertificateFlags::BAD_IDENTITY`][crate::TlsCertificateFlags::BAD_IDENTITY] validation will fail.
    ///
    /// In addition to its use in verifying the server certificate,
    /// this is also used to give a hint to the server about what
    /// certificate we expect, which is useful for servers that serve
    /// virtual hosts.
    ///
    /// Readable | Writeable | Construct
    ///
    ///
    /// #### `validation-flags`
    ///  What steps to perform when validating a certificate received from
    /// a server. Server certificates that fail to validate in any of the
    /// ways indicated here will be rejected unless the application
    /// overrides the default via #GDtlsConnection::accept-certificate.
    ///
    /// GLib guarantees that if certificate verification fails, at least one
    /// flag will be set, but it does not guarantee that all possible flags
    /// will be set. Accordingly, you may not safely decide to ignore any
    /// particular type of error. For example, it would be incorrect to mask
    /// [`TlsCertificateFlags::EXPIRED`][crate::TlsCertificateFlags::EXPIRED] if you want to allow expired certificates,
    /// because this could potentially be the only error flag set even if
    /// other problems exist with the certificate. Therefore, there is no
    /// safe way to use this property. This is not a horrible problem,
    /// though, because you should not be attempting to ignore validation
    /// errors anyway. If you really must ignore TLS certificate errors,
    /// connect to #GDtlsConnection::accept-certificate.
    ///
    /// Readable | Writeable | Construct
    /// <details><summary><h4>DtlsConnection</h4></summary>
    ///
    ///
    /// #### `advertised-protocols`
    ///  The list of application-layer protocols that the connection
    /// advertises that it is willing to speak. See
    /// g_dtls_connection_set_advertised_protocols().
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `base-socket`
    ///  The #GDatagramBased that the connection wraps. Note that this may be any
    /// implementation of #GDatagramBased, not just a #GSocket.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `certificate`
    ///  The connection's certificate; see
    /// g_dtls_connection_set_certificate().
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `ciphersuite-name`
    ///  The name of the DTLS ciphersuite in use. See g_dtls_connection_get_ciphersuite_name().
    ///
    /// Readable
    ///
    ///
    /// #### `database`
    ///  The certificate database to use when verifying this TLS connection.
    /// If no certificate database is set, then the default database will be
    /// used. See g_tls_backend_get_default_database().
    ///
    /// When using a non-default database, #GDtlsConnection must fall back to using
    /// the #GTlsDatabase to perform certificate verification using
    /// g_tls_database_verify_chain(), which means certificate verification will
    /// not be able to make use of TLS session context. This may be less secure.
    /// For example, if you create your own #GTlsDatabase that just wraps the
    /// default #GTlsDatabase, you might expect that you have not changed anything,
    /// but this is not true because you may have altered the behavior of
    /// #GDtlsConnection by causing it to use g_tls_database_verify_chain(). See the
    /// documentation of g_tls_database_verify_chain() for more details on specific
    /// security checks that may not be performed. Accordingly, setting a
    /// non-default database is discouraged except for specialty applications with
    /// unusual security requirements.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `interaction`
    ///  A #GTlsInteraction object to be used when the connection or certificate
    /// database need to interact with the user. This will be used to prompt the
    /// user for passwords where necessary.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `negotiated-protocol`
    ///  The application-layer protocol negotiated during the TLS
    /// handshake. See g_dtls_connection_get_negotiated_protocol().
    ///
    /// Readable
    ///
    ///
    /// #### `peer-certificate`
    ///  The connection's peer's certificate, after the TLS handshake has
    /// completed or failed. Note in particular that this is not yet set
    /// during the emission of #GDtlsConnection::accept-certificate.
    ///
    /// (You can watch for a #GObject::notify signal on this property to
    /// detect when a handshake has occurred.)
    ///
    /// Readable
    ///
    ///
    /// #### `peer-certificate-errors`
    ///  The errors noticed while verifying
    /// #GDtlsConnection:peer-certificate. Normally this should be 0, but
    /// it may not be if #GDtlsClientConnection:validation-flags is not
    /// [`TlsCertificateFlags::VALIDATE_ALL`][crate::TlsCertificateFlags::VALIDATE_ALL], or if
    /// #GDtlsConnection::accept-certificate overrode the default
    /// behavior.
    ///
    /// GLib guarantees that if certificate verification fails, at least
    /// one error will be set, but it does not guarantee that all possible
    /// errors will be set. Accordingly, you may not safely decide to
    /// ignore any particular type of error. For example, it would be
    /// incorrect to mask [`TlsCertificateFlags::EXPIRED`][crate::TlsCertificateFlags::EXPIRED] if you want to allow
    /// expired certificates, because this could potentially be the only
    /// error flag set even if other problems exist with the certificate.
    ///
    /// Readable
    ///
    ///
    /// #### `protocol-version`
    ///  The DTLS protocol version in use. See g_dtls_connection_get_protocol_version().
    ///
    /// Readable
    ///
    ///
    /// #### `rehandshake-mode`
    ///  The rehandshaking mode. See
    /// g_dtls_connection_set_rehandshake_mode().
    ///
    /// Readable | Writeable | Construct
    ///
    ///
    /// #### `require-close-notify`
    ///  Whether or not proper TLS close notification is required.
    /// See g_dtls_connection_set_require_close_notify().
    ///
    /// Readable | Writeable | Construct
    /// </details>
    ///
    /// # Implements
    ///
    /// [`DtlsClientConnectionExt`][trait@crate::prelude::DtlsClientConnectionExt], [`DatagramBasedExt`][trait@crate::prelude::DatagramBasedExt], [`DtlsConnectionExt`][trait@crate::prelude::DtlsConnectionExt], [`DatagramBasedExtManual`][trait@crate::prelude::DatagramBasedExtManual]
    #[doc(alias = "GDtlsClientConnection")]
    pub struct DtlsClientConnection(Interface<ffi::GDtlsClientConnection, ffi::GDtlsClientConnectionInterface>) @requires DatagramBased, DtlsConnection;

    match fn {
        type_ => || ffi::g_dtls_client_connection_get_type(),
    }
}

impl DtlsClientConnection {
    pub const NONE: Option<&'static DtlsClientConnection> = None;

    /// Creates a new #GDtlsClientConnection wrapping @base_socket which is
    /// assumed to communicate with the server identified by @server_identity.
    /// ## `base_socket`
    /// the #GDatagramBased to wrap
    /// ## `server_identity`
    /// the expected identity of the server
    ///
    /// # Returns
    ///
    /// the new
    ///   #GDtlsClientConnection, or [`None`] on error
    #[doc(alias = "g_dtls_client_connection_new")]
    pub fn new(
        base_socket: &impl IsA<DatagramBased>,
        server_identity: Option<&impl IsA<SocketConnectable>>,
    ) -> Result<DtlsClientConnection, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_dtls_client_connection_new(
                base_socket.as_ref().to_glib_none().0,
                server_identity.map(|p| p.as_ref()).to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }
}

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::DtlsClientConnection>> Sealed for T {}
}

/// Trait containing all [`struct@DtlsClientConnection`] methods.
///
/// # Implementors
///
/// [`DtlsClientConnection`][struct@crate::DtlsClientConnection]
pub trait DtlsClientConnectionExt: IsA<DtlsClientConnection> + sealed::Sealed + 'static {
    /// Gets the list of distinguished names of the Certificate Authorities
    /// that the server will accept certificates from. This will be set
    /// during the TLS handshake if the server requests a certificate.
    /// Otherwise, it will be [`None`].
    ///
    /// Each item in the list is a #GByteArray which contains the complete
    /// subject DN of the certificate authority.
    ///
    /// # Returns
    ///
    /// the list of
    /// CA DNs. You should unref each element with g_byte_array_unref() and then
    /// the free the list with g_list_free().
    #[doc(alias = "g_dtls_client_connection_get_accepted_cas")]
    #[doc(alias = "get_accepted_cas")]
    #[doc(alias = "accepted-cas")]
    fn accepted_cas(&self) -> Vec<glib::ByteArray> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::g_dtls_client_connection_get_accepted_cas(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets @self's expected server identity
    ///
    /// # Returns
    ///
    /// a #GSocketConnectable describing the
    /// expected server identity, or [`None`] if the expected identity is not
    /// known.
    #[doc(alias = "g_dtls_client_connection_get_server_identity")]
    #[doc(alias = "get_server_identity")]
    #[doc(alias = "server-identity")]
    fn server_identity(&self) -> SocketConnectable {
        unsafe {
            from_glib_none(ffi::g_dtls_client_connection_get_server_identity(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets @self's validation flags
    ///
    /// This function does not work as originally designed and is impossible
    /// to use correctly. See #GDtlsClientConnection:validation-flags for more
    /// information.
    ///
    /// # Deprecated since 2.74
    ///
    /// Do not attempt to ignore validation errors.
    ///
    /// # Returns
    ///
    /// the validation flags
    #[cfg_attr(feature = "v2_74", deprecated = "Since 2.74")]
    #[allow(deprecated)]
    #[doc(alias = "g_dtls_client_connection_get_validation_flags")]
    #[doc(alias = "get_validation_flags")]
    #[doc(alias = "validation-flags")]
    fn validation_flags(&self) -> TlsCertificateFlags {
        unsafe {
            from_glib(ffi::g_dtls_client_connection_get_validation_flags(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Sets @self's expected server identity, which is used both to tell
    /// servers on virtual hosts which certificate to present, and also
    /// to let @self know what name to look for in the certificate when
    /// performing [`TlsCertificateFlags::BAD_IDENTITY`][crate::TlsCertificateFlags::BAD_IDENTITY] validation, if enabled.
    /// ## `identity`
    /// a #GSocketConnectable describing the expected server identity
    #[doc(alias = "g_dtls_client_connection_set_server_identity")]
    #[doc(alias = "server-identity")]
    fn set_server_identity(&self, identity: &impl IsA<SocketConnectable>) {
        unsafe {
            ffi::g_dtls_client_connection_set_server_identity(
                self.as_ref().to_glib_none().0,
                identity.as_ref().to_glib_none().0,
            );
        }
    }

    /// Sets @self's validation flags, to override the default set of
    /// checks performed when validating a server certificate. By default,
    /// [`TlsCertificateFlags::VALIDATE_ALL`][crate::TlsCertificateFlags::VALIDATE_ALL] is used.
    ///
    /// This function does not work as originally designed and is impossible
    /// to use correctly. See #GDtlsClientConnection:validation-flags for more
    /// information.
    ///
    /// # Deprecated since 2.74
    ///
    /// Do not attempt to ignore validation errors.
    /// ## `flags`
    /// the #GTlsCertificateFlags to use
    #[cfg_attr(feature = "v2_74", deprecated = "Since 2.74")]
    #[allow(deprecated)]
    #[doc(alias = "g_dtls_client_connection_set_validation_flags")]
    #[doc(alias = "validation-flags")]
    fn set_validation_flags(&self, flags: TlsCertificateFlags) {
        unsafe {
            ffi::g_dtls_client_connection_set_validation_flags(
                self.as_ref().to_glib_none().0,
                flags.into_glib(),
            );
        }
    }

    #[doc(alias = "accepted-cas")]
    fn connect_accepted_cas_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_accepted_cas_trampoline<
            P: IsA<DtlsClientConnection>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GDtlsClientConnection,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(DtlsClientConnection::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::accepted-cas\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_accepted_cas_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "server-identity")]
    fn connect_server_identity_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_server_identity_trampoline<
            P: IsA<DtlsClientConnection>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GDtlsClientConnection,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(DtlsClientConnection::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::server-identity\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_server_identity_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[cfg_attr(feature = "v2_74", deprecated = "Since 2.74")]
    #[doc(alias = "validation-flags")]
    fn connect_validation_flags_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_validation_flags_trampoline<
            P: IsA<DtlsClientConnection>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GDtlsClientConnection,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(DtlsClientConnection::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::validation-flags\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_validation_flags_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<DtlsClientConnection>> DtlsClientConnectionExt for O {}