[−][src]Trait gio::SocketClientExt

pub trait SocketClientExt: 'static {
    fn add_application_proxy(&self, protocol: &str);

    fn connect<P: IsA<SocketConnectable>, Q: IsA<Cancellable>>(
        &self, 
        connectable: &P, 
        cancellable: Option<&Q>
    ) -> Result<SocketConnection, Error>;

    fn connect_async<P: IsA<SocketConnectable>, Q: IsA<Cancellable>, R: FnOnce(Result<SocketConnection, Error>) + Send + 'static>(
        &self, 
        connectable: &P, 
        cancellable: Option<&Q>, 
        callback: R
    );

    fn connect_async_future<P: IsA<SocketConnectable> + Clone + 'static>(
        &self, 
        connectable: &P
    ) -> Pin<Box_<dyn Future<Output = Result<SocketConnection, Error>> + 'static>>;

    fn connect_to_host<P: IsA<Cancellable>>(
        &self, 
        host_and_port: &str, 
        default_port: u16, 
        cancellable: Option<&P>
    ) -> Result<SocketConnection, Error>;

    fn connect_to_host_async<P: IsA<Cancellable>, Q: FnOnce(Result<SocketConnection, Error>) + Send + 'static>(
        &self, 
        host_and_port: &str, 
        default_port: u16, 
        cancellable: Option<&P>, 
        callback: Q
    );

    fn connect_to_host_async_future(
        &self, 
        host_and_port: &str, 
        default_port: u16
    ) -> Pin<Box_<dyn Future<Output = Result<SocketConnection, Error>> + 'static>>;

    fn connect_to_service<P: IsA<Cancellable>>(
        &self, 
        domain: &str, 
        service: &str, 
        cancellable: Option<&P>
    ) -> Result<SocketConnection, Error>;

    fn connect_to_service_async<P: IsA<Cancellable>, Q: FnOnce(Result<SocketConnection, Error>) + Send + 'static>(
        &self, 
        domain: &str, 
        service: &str, 
        cancellable: Option<&P>, 
        callback: Q
    );

    fn connect_to_service_async_future(
        &self, 
        domain: &str, 
        service: &str
    ) -> Pin<Box_<dyn Future<Output = Result<SocketConnection, Error>> + 'static>>;

    fn connect_to_uri<P: IsA<Cancellable>>(
        &self, 
        uri: &str, 
        default_port: u16, 
        cancellable: Option<&P>
    ) -> Result<SocketConnection, Error>;

    fn connect_to_uri_async<P: IsA<Cancellable>, Q: FnOnce(Result<SocketConnection, Error>) + Send + 'static>(
        &self, 
        uri: &str, 
        default_port: u16, 
        cancellable: Option<&P>, 
        callback: Q
    );

    fn connect_to_uri_async_future(
        &self, 
        uri: &str, 
        default_port: u16
    ) -> Pin<Box_<dyn Future<Output = Result<SocketConnection, Error>> + 'static>>;

    fn get_enable_proxy(&self) -> bool;

    fn get_family(&self) -> SocketFamily;

    fn get_local_address(&self) -> Option<SocketAddress>;

    fn get_protocol(&self) -> SocketProtocol;

    fn get_proxy_resolver(&self) -> Option<ProxyResolver>;

    fn get_socket_type(&self) -> SocketType;

    fn get_timeout(&self) -> u32;

    fn get_tls(&self) -> bool;

    fn get_tls_validation_flags(&self) -> TlsCertificateFlags;

    fn set_enable_proxy(&self, enable: bool);

    fn set_family(&self, family: SocketFamily);

    fn set_local_address<P: IsA<SocketAddress>>(&self, address: Option<&P>);

    fn set_protocol(&self, protocol: SocketProtocol);

    fn set_proxy_resolver<P: IsA<ProxyResolver>>(
        &self, 
        proxy_resolver: Option<&P>
    );

    fn set_socket_type(&self, type_: SocketType);

    fn set_timeout(&self, timeout: u32);

    fn set_tls(&self, tls: bool);

    fn set_tls_validation_flags(&self, flags: TlsCertificateFlags);

    fn get_property_type(&self) -> SocketType;

    fn set_property_type(&self, type_: SocketType);

    fn connect_event<F: Fn(&Self, SocketClientEvent, &SocketConnectable, Option<&IOStream>) + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_property_enable_proxy_notify<F: Fn(&Self) + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_property_family_notify<F: Fn(&Self) + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_property_local_address_notify<F: Fn(&Self) + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_property_protocol_notify<F: Fn(&Self) + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_property_proxy_resolver_notify<F: Fn(&Self) + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_property_timeout_notify<F: Fn(&Self) + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_property_tls_notify<F: Fn(&Self) + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_property_tls_validation_flags_notify<F: Fn(&Self) + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_property_type_notify<F: Fn(&Self) + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;
}

Trait containing all SocketClient methods.

Implementors

SocketClient

Required methods

fn add_application_proxy(&self, protocol: &str)

Enable proxy protocols to be handled by the application. When the indicated proxy protocol is returned by the ProxyResolver, SocketClient will consider this protocol as supported but will not try to find a Proxy instance to handle handshaking. The application must check for this case by calling SocketConnectionExt::get_remote_address on the returned SocketConnection, and seeing if it's a ProxyAddress of the appropriate type, to determine whether or not it needs to handle the proxy handshaking itself.

This should be used for proxy protocols that are dialects of another protocol such as HTTP proxy. It also allows cohabitation of proxy protocols that are reused between protocols. A good example is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also be use as generic socket proxy through the HTTP CONNECT method.

When the proxy is detected as being an application proxy, TLS handshake will be skipped. This is required to let the application do the proxy specific handshake.

protocol

The proxy protocol

fn connect<P: IsA<SocketConnectable>, Q: IsA<Cancellable>>(
    &self,
    connectable: &P,
    cancellable: Option<&Q>
) -> Result<SocketConnection, Error>

Tries to resolve the connectable and make a network connection to it.

Upon a successful connection, a new SocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it.

The type of the SocketConnection object returned depends on the type of the underlying socket that is used. For instance, for a TCP/IP connection it will be a TcpConnection.

The socket created will be the same family as the address that the connectable resolves to, unless family is set with SocketClientExt::set_family or indirectly via SocketClientExt::set_local_address. The socket type defaults to SocketType::Stream but can be set with SocketClientExt::set_socket_type.

If a local address is specified with SocketClientExt::set_local_address the socket will be bound to this address before connecting.

connectable

a SocketConnectable specifying the remote address.

cancellable

optional Cancellable object, None to ignore.

Returns

a SocketConnection on success, None on error.

fn connect_async<P: IsA<SocketConnectable>, Q: IsA<Cancellable>, R: FnOnce(Result<SocketConnection, Error>) + Send + 'static>(
    &self,
    connectable: &P,
    cancellable: Option<&Q>,
    callback: R
)

This is the asynchronous version of SocketClientExt::connect.

When the operation is finished callback will be called. You can then call SocketClientExt::connect_finish to get the result of the operation.

connectable

a SocketConnectable specifying the remote address.

cancellable

a Cancellable, or None

callback

a GAsyncReadyCallback

user_data

user data for the callback

fn connect_async_future<P: IsA<SocketConnectable> + Clone + 'static>(
    &self,
    connectable: &P
) -> Pin<Box_<dyn Future<Output = Result<SocketConnection, Error>> + 'static>>

fn connect_to_host<P: IsA<Cancellable>>(
    &self,
    host_and_port: &str,
    default_port: u16,
    cancellable: Option<&P>
) -> Result<SocketConnection, Error>

This is a helper function for SocketClientExt::connect.

Attempts to create a TCP connection to the named host.

host_and_port may be in any of a number of recognized 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. Ports may be given as decimal numbers or symbolic names (in which case an /etc/services lookup is performed).

If no port override is given 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.

In the case that an IP address is given, a single connection attempt is made. In the case that a name is given, multiple connection attempts may be made, in turn and according to the number of address records in DNS, until a connection succeeds.

Upon a successful connection, a new SocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it.

In the event of any failure (DNS error, service not found, no hosts connectable) None is returned and error (if non-None) is set accordingly.

host_and_port

the name and optionally port of the host to connect to

default_port

the default port to connect to

cancellable

a Cancellable, or None

Returns

a SocketConnection on success, None on error.

fn connect_to_host_async<P: IsA<Cancellable>, Q: FnOnce(Result<SocketConnection, Error>) + Send + 'static>(
    &self,
    host_and_port: &str,
    default_port: u16,
    cancellable: Option<&P>,
    callback: Q
)

This is the asynchronous version of SocketClientExt::connect_to_host.

When the operation is finished callback will be called. You can then call SocketClientExt::connect_to_host_finish to get the result of the operation.

host_and_port

the name and optionally the port of the host to connect to

default_port

the default port to connect to

cancellable

a Cancellable, or None

callback

a GAsyncReadyCallback

user_data

user data for the callback

fn connect_to_host_async_future(
    &self,
    host_and_port: &str,
    default_port: u16
) -> Pin<Box_<dyn Future<Output = Result<SocketConnection, Error>> + 'static>>

fn connect_to_service<P: IsA<Cancellable>>(
    &self,
    domain: &str,
    service: &str,
    cancellable: Option<&P>
) -> Result<SocketConnection, Error>

Attempts to create a TCP connection to a service.

This call looks up the SRV record for service at domain for the "tcp" protocol. It then attempts to connect, in turn, to each of the hosts providing the service until either a connection succeeds or there are no hosts remaining.

Upon a successful connection, a new SocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it.

In the event of any failure (DNS error, service not found, no hosts connectable) None is returned and error (if non-None) is set accordingly.

domain

a domain name

service

the name of the service to connect to

cancellable

a Cancellable, or None

Returns

a SocketConnection if successful, or None on error

fn connect_to_service_async<P: IsA<Cancellable>, Q: FnOnce(Result<SocketConnection, Error>) + Send + 'static>(
    &self,
    domain: &str,
    service: &str,
    cancellable: Option<&P>,
    callback: Q
)

This is the asynchronous version of SocketClientExt::connect_to_service.

domain

a domain name

service

the name of the service to connect to

cancellable

a Cancellable, or None

callback

a GAsyncReadyCallback

user_data

user data for the callback

fn connect_to_service_async_future(
    &self,
    domain: &str,
    service: &str
) -> Pin<Box_<dyn Future<Output = Result<SocketConnection, Error>> + 'static>>

fn connect_to_uri<P: IsA<Cancellable>>(
    &self,
    uri: &str,
    default_port: u16,
    cancellable: Option<&P>
) -> Result<SocketConnection, Error>

This is a helper function for SocketClientExt::connect.

Attempts to create a TCP connection with a network URI.

uri may be any valid URI containing an "authority" (hostname/port) component. If a port is not specified in the URI, default_port will be used. TLS will be negotiated if SocketClient:tls is true. (SocketClient does not know to automatically assume TLS for certain URI schemes.)

Using this rather than SocketClientExt::connect or SocketClientExt::connect_to_host allows SocketClient to determine when to use application-specific proxy protocols.

Upon a successful connection, a new SocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it.

In the event of any failure (DNS error, service not found, no hosts connectable) None is returned and error (if non-None) is set accordingly.

uri

A network URI

default_port

the default port to connect to

cancellable

a Cancellable, or None

Returns

a SocketConnection on success, None on error.

fn connect_to_uri_async<P: IsA<Cancellable>, Q: FnOnce(Result<SocketConnection, Error>) + Send + 'static>(
    &self,
    uri: &str,
    default_port: u16,
    cancellable: Option<&P>,
    callback: Q
)

This is the asynchronous version of SocketClientExt::connect_to_uri.

When the operation is finished callback will be called. You can then call SocketClientExt::connect_to_uri_finish to get the result of the operation.

uri

a network uri

default_port

the default port to connect to

cancellable

a Cancellable, or None

callback

a GAsyncReadyCallback

user_data

user data for the callback

fn connect_to_uri_async_future(
    &self,
    uri: &str,
    default_port: u16
) -> Pin<Box_<dyn Future<Output = Result<SocketConnection, Error>> + 'static>>

fn get_enable_proxy(&self) -> bool

Gets the proxy enable state; see SocketClientExt::set_enable_proxy

Returns

whether proxying is enabled

fn get_family(&self) -> SocketFamily

Gets the socket family of the socket client.

See SocketClientExt::set_family for details.

Returns

a SocketFamily

fn get_local_address(&self) -> Option<SocketAddress>

Gets the local address of the socket client.

See SocketClientExt::set_local_address for details.

Returns

a SocketAddress or None. Do not free.

fn get_protocol(&self) -> SocketProtocol

Gets the protocol name type of the socket client.

See SocketClientExt::set_protocol for details.

Returns

a SocketProtocol

fn get_proxy_resolver(&self) -> Option<ProxyResolver>

Gets the ProxyResolver being used by self. Normally, this will be the resolver returned by ProxyResolver::get_default, but you can override it with SocketClientExt::set_proxy_resolver.

Returns

The ProxyResolver being used by self.

fn get_socket_type(&self) -> SocketType

Gets the socket type of the socket client.

See SocketClientExt::set_socket_type for details.

Returns

a SocketFamily

fn get_timeout(&self) -> u32

Gets the I/O timeout time for sockets created by self.

See SocketClientExt::set_timeout for details.

Returns

the timeout in seconds

fn get_tls(&self) -> bool

Gets whether self creates TLS connections. See SocketClientExt::set_tls for details.

Returns

whether self uses TLS

fn get_tls_validation_flags(&self) -> TlsCertificateFlags

Gets the TLS validation flags used creating TLS connections via self.

Returns

the TLS validation flags

fn set_enable_proxy(&self, enable: bool)

Sets whether or not self attempts to make connections via a proxy server. When enabled (the default), SocketClient will use a ProxyResolver to determine if a proxy protocol such as SOCKS is needed, and automatically do the necessary proxy negotiation.

See also SocketClientExt::set_proxy_resolver.

enable

whether to enable proxies

fn set_family(&self, family: SocketFamily)

Sets the socket family of the socket client. If this is set to something other than SocketFamily::Invalid then the sockets created by this object will be of the specified family.

This might be useful for instance if you want to force the local connection to be an ipv4 socket, even though the address might be an ipv6 mapped to ipv4 address.

family

a SocketFamily

fn set_local_address<P: IsA<SocketAddress>>(&self, address: Option<&P>)

Sets the local address of the socket client. The sockets created by this object will bound to the specified address (if not None) before connecting.

This is useful if you want to ensure that the local side of the connection is on a specific port, or on a specific interface.

address

a SocketAddress, or None

fn set_protocol(&self, protocol: SocketProtocol)

Sets the protocol of the socket client. The sockets created by this object will use of the specified protocol.

If protocol is SocketProtocol::Default that means to use the default protocol for the socket family and type.

protocol

a SocketProtocol

fn set_proxy_resolver<P: IsA<ProxyResolver>>(&self, proxy_resolver: Option<&P>)

Overrides the ProxyResolver used by self. You can call this if you want to use specific proxies, rather than using the system default proxy settings.

Note that whether or not the proxy resolver is actually used depends on the setting of SocketClient:enable-proxy, which is not changed by this function (but which is true by default)

proxy_resolver

a ProxyResolver, or None for the default.

fn set_socket_type(&self, type_: SocketType)

Sets the socket type of the socket client. The sockets created by this object will be of the specified type.

It doesn't make sense to specify a type of SocketType::Datagram, as GSocketClient is used for connection oriented services.

type_

a SocketType

fn set_timeout(&self, timeout: u32)

Sets the I/O timeout for sockets created by self. timeout is a time in seconds, or 0 for no timeout (the default).

The timeout value affects the initial connection attempt as well, so setting this may cause calls to SocketClientExt::connect, etc, to fail with IOErrorEnum::TimedOut.

timeout

the timeout

fn set_tls(&self, tls: bool)

Sets whether self creates TLS (aka SSL) connections. If tls is true, self will wrap its connections in a TlsClientConnection and perform a TLS handshake when connecting.

Note that since SocketClient must return a SocketConnection, but TlsClientConnection is not a SocketConnection, this actually wraps the resulting TlsClientConnection in a TcpWrapperConnection when returning it. You can use TcpWrapperConnection::get_base_io_stream on the return value to extract the TlsClientConnection.

If you need to modify the behavior of the TLS handshake (eg, by setting a client-side certificate to use, or connecting to the TlsConnection::accept-certificate signal), you can connect to self's SocketClient::event signal and wait for it to be emitted with SocketClientEvent::TlsHandshaking, which will give you a chance to see the TlsClientConnection before the handshake starts.

tls

whether to use TLS

fn set_tls_validation_flags(&self, flags: TlsCertificateFlags)

Sets the TLS validation flags used when creating TLS connections via self. The default value is TlsCertificateFlags::ValidateAll.

flags

the validation flags

fn get_property_type(&self) -> SocketType

fn set_property_type(&self, type_: SocketType)

fn connect_event<F: Fn(&Self, SocketClientEvent, &SocketConnectable, Option<&IOStream>) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

Emitted when client's activity on connectable changes state. Among other things, this can be used to provide progress information about a network connection in the UI. The meanings of the different event values are as follows:

  • SocketClientEvent::Resolving: client is about to look up connectable in DNS. connection will be None.

  • SocketClientEvent::Resolved: client has successfully resolved connectable in DNS. connection will be None.

  • SocketClientEvent::Connecting: client is about to make a connection to a remote host; either a proxy server or the destination server itself. connection is the SocketConnection, which is not yet connected. Since GLib 2.40, you can access the remote address via SocketConnectionExt::get_remote_address.

  • SocketClientEvent::Connected: client has successfully connected to a remote host. connection is the connected SocketConnection.

  • SocketClientEvent::ProxyNegotiating: client is about to negotiate with a proxy to get it to connect to connectable. connection is the SocketConnection to the proxy server.

  • SocketClientEvent::ProxyNegotiated: client has negotiated a connection to connectable through a proxy server. connection is the stream returned from Proxy::connect, which may or may not be a SocketConnection.

  • SocketClientEvent::TlsHandshaking: client is about to begin a TLS handshake. connection is a TlsClientConnection.

  • SocketClientEvent::TlsHandshaked: client has successfully completed the TLS handshake. connection is a TlsClientConnection.

  • SocketClientEvent::Complete: client has either successfully connected to connectable (in which case connection is the SocketConnection that it will be returning to the caller) or has failed (in which case connection is None and the client is about to return an error).

Each event except SocketClientEvent::Complete may be emitted multiple times (or not at all) for a given connectable (in particular, if client ends up attempting to connect to more than one address). However, if client emits the SocketClient::event signal at all for a given connectable, that it will always emit it with SocketClientEvent::Complete when it is done.

Note that there may be additional SocketClientEvent values in the future; unrecognized event values should be ignored.

event

the event that is occurring

connectable

the SocketConnectable that event is occurring on

connection

the current representation of the connection

fn connect_property_enable_proxy_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

fn connect_property_family_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

fn connect_property_local_address_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

fn connect_property_protocol_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

fn connect_property_proxy_resolver_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

fn connect_property_timeout_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

fn connect_property_tls_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

fn connect_property_tls_validation_flags_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

fn connect_property_type_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

Loading content...

Implementors

impl<O: IsA<SocketClient>> SocketClientExt for O[src]

Loading content...