gio/auto/

network_address.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

use crate::{ffi, SocketConnectable};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// `GNetworkAddress` provides an easy way to resolve a hostname and
    /// then attempt to connect to that host, handling the possibility of
    /// multiple IP addresses and multiple address families.
    ///
    /// The enumeration results of resolved addresses *may* be cached as long
    /// as this object is kept alive which may have unexpected results if
    /// alive for too long.
    ///
    /// See [`SocketConnectable`][crate::SocketConnectable] for an example of using the connectable
    /// interface.
    ///
    /// ## Properties
    ///
    ///
    /// #### `hostname`
    ///  Hostname to resolve.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `port`
    ///  Network port.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `scheme`
    ///  URI scheme.
    ///
    /// Readable | Writeable | Construct Only
    ///
    /// # Implements
    ///
    /// [`NetworkAddressExt`][trait@crate::prelude::NetworkAddressExt], [`trait@glib::ObjectExt`], [`SocketConnectableExt`][trait@crate::prelude::SocketConnectableExt]
    #[doc(alias = "GNetworkAddress")]
    pub struct NetworkAddress(Object<ffi::GNetworkAddress, ffi::GNetworkAddressClass>) @implements SocketConnectable;

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

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

    /// Creates a new #GSocketConnectable for connecting to the given
    /// @hostname and @port.
    ///
    /// Note that depending on the configuration of the machine, a
    /// @hostname of `localhost` may refer to the IPv4 loopback address
    /// only, or to both IPv4 and IPv6; use
    /// g_network_address_new_loopback() to create a #GNetworkAddress that
    /// is guaranteed to resolve to both addresses.
    /// ## `hostname`
    /// the hostname
    /// ## `port`
    /// the port
    ///
    /// # Returns
    ///
    /// the new #GNetworkAddress
    #[doc(alias = "g_network_address_new")]
    pub fn new(hostname: &str, port: u16) -> NetworkAddress {
        unsafe { from_glib_full(ffi::g_network_address_new(hostname.to_glib_none().0, port)) }
    }

    /// Creates a new #GSocketConnectable for connecting to the local host
    /// over a loopback connection to the given @port. This is intended for
    /// use in connecting to local services which may be running on IPv4 or
    /// IPv6.
    ///
    /// The connectable will return IPv4 and IPv6 loopback addresses,
    /// regardless of how the host resolves `localhost`. By contrast,
    /// g_network_address_new() will often only return an IPv4 address when
    /// resolving `localhost`, and an IPv6 address for `localhost6`.
    ///
    /// g_network_address_get_hostname() will always return `localhost` for
    /// a #GNetworkAddress created with this constructor.
    /// ## `port`
    /// the port
    ///
    /// # Returns
    ///
    /// the new #GNetworkAddress
    #[doc(alias = "g_network_address_new_loopback")]
    pub fn new_loopback(port: u16) -> NetworkAddress {
        unsafe { from_glib_full(ffi::g_network_address_new_loopback(port)) }
    }

    /// Creates a new #GSocketConnectable for connecting to the given
    /// @hostname and @port. May fail and return [`None`] in case
    /// parsing @host_and_port fails.
    ///
    /// @host_and_port may be in any of a number of recognised formats; an IPv6
    /// address, an IPv4 address, or a domain name (in which case a DNS
    /// lookup is performed). Quoting with [] is supported for all address
    /// types. A port override may be specified in the usual way with a
    /// colon.
    ///
    /// If no port is specified in @host_and_port then @default_port will be
    /// used as the port number to connect to.
    ///
    /// In general, @host_and_port is expected to be provided by the user
    /// (allowing them to give the hostname, and a port override if necessary)
    /// and @default_port is expected to be provided by the application.
    ///
    /// (The port component of @host_and_port can also be specified as a
    /// service name rather than as a numeric port, but this functionality
    /// is deprecated, because it depends on the contents of /etc/services,
    /// which is generally quite sparse on platforms other than Linux.)
    /// ## `host_and_port`
    /// the hostname and optionally a port
    /// ## `default_port`
    /// the default port if not in @host_and_port
    ///
    /// # Returns
    ///
    /// the new
    ///   #GNetworkAddress, or [`None`] on error
    #[doc(alias = "g_network_address_parse")]
    pub fn parse(host_and_port: &str, default_port: u16) -> Result<NetworkAddress, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_network_address_parse(
                host_and_port.to_glib_none().0,
                default_port,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Creates a new #GSocketConnectable for connecting to the given
    /// @uri. May fail and return [`None`] in case parsing @uri fails.
    ///
    /// Using this rather than g_network_address_new() or
    /// g_network_address_parse() allows #GSocketClient to determine
    /// when to use application-specific proxy protocols.
    /// ## `uri`
    /// the hostname and optionally a port
    /// ## `default_port`
    /// The default port if none is found in the URI
    ///
    /// # Returns
    ///
    /// the new
    ///   #GNetworkAddress, or [`None`] on error
    #[doc(alias = "g_network_address_parse_uri")]
    pub fn parse_uri(uri: &str, default_port: u16) -> Result<NetworkAddress, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret =
                ffi::g_network_address_parse_uri(uri.to_glib_none().0, default_port, &mut error);
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }
}

unsafe impl Send for NetworkAddress {}
unsafe impl Sync for NetworkAddress {}

/// Trait containing all [`struct@NetworkAddress`] methods.
///
/// # Implementors
///
/// [`NetworkAddress`][struct@crate::NetworkAddress]
pub trait NetworkAddressExt: IsA<NetworkAddress> + 'static {
    /// Gets @self's hostname. This might be either UTF-8 or ASCII-encoded,
    /// depending on what @self was created with.
    ///
    /// # Returns
    ///
    /// @self's hostname
    #[doc(alias = "g_network_address_get_hostname")]
    #[doc(alias = "get_hostname")]
    fn hostname(&self) -> glib::GString {
        unsafe {
            from_glib_none(ffi::g_network_address_get_hostname(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets @self's port number
    ///
    /// # Returns
    ///
    /// @self's port (which may be 0)
    #[doc(alias = "g_network_address_get_port")]
    #[doc(alias = "get_port")]
    fn port(&self) -> u16 {
        unsafe { ffi::g_network_address_get_port(self.as_ref().to_glib_none().0) }
    }

    /// Gets @self's scheme
    ///
    /// # Returns
    ///
    /// @self's scheme ([`None`] if not built from URI)
    #[doc(alias = "g_network_address_get_scheme")]
    #[doc(alias = "get_scheme")]
    fn scheme(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::g_network_address_get_scheme(
                self.as_ref().to_glib_none().0,
            ))
        }
    }
}

impl<O: IsA<NetworkAddress>> NetworkAddressExt for O {}