Gio.SocketClient

g GObject.Object GObject.Object Gio.SocketClient Gio.SocketClient GObject.Object->Gio.SocketClient

Subclasses:

None

Methods

Inherited:

GObject.Object (37)

Structs:

GObject.ObjectClass (5)

class

new ()

add_application_proxy (protocol)

connect (connectable, cancellable)

connect_async (connectable, cancellable, callback, *user_data)

connect_finish (result)

connect_to_host (host_and_port, default_port, cancellable)

connect_to_host_async (host_and_port, default_port, cancellable, callback, *user_data)

connect_to_host_finish (result)

connect_to_service (domain, service, cancellable)

connect_to_service_async (domain, service, cancellable, callback, *user_data)

connect_to_service_finish (result)

connect_to_uri (uri, default_port, cancellable)

connect_to_uri_async (uri, default_port, cancellable, callback, *user_data)

connect_to_uri_finish (result)

get_enable_proxy ()

get_family ()

get_local_address ()

get_protocol ()

get_proxy_resolver ()

get_socket_type ()

get_timeout ()

get_tls ()

get_tls_validation_flags ()

set_enable_proxy (enable)

set_family (family)

set_local_address (address)

set_protocol (protocol)

set_proxy_resolver (proxy_resolver)

set_socket_type (type)

set_timeout (timeout)

set_tls (tls)

set_tls_validation_flags (flags)

Virtual Methods

Inherited:

GObject.Object (7)

do_event (event, connectable, connection)

Properties

Name

Type

Flags

Short Description

enable-proxy

bool

r/w/c

Enable proxy support

family

Gio.SocketFamily

r/w/c

The sockets address family to use for socket construction

local-address

Gio.SocketAddress

r/w/c

The local address constructed sockets will be bound to

protocol

Gio.SocketProtocol

r/w/c

The protocol to use for socket construction, or 0 for default

proxy-resolver

Gio.ProxyResolver

r/w/c

The proxy resolver to use

timeout

int

r/w/c

The I/O timeout for sockets, or 0 for none

tls

bool

r/w/c

Whether to create TLS connections

tls-validation-flags

Gio.TlsCertificateFlags

d/r/w/c

TLS validation flags to use deprecated

type

Gio.SocketType

r/w/c

The sockets type to use for socket construction

Signals

Inherited:

GObject.Object (1)

Name

Short Description

event

Emitted when client's activity on connectable changes state.

Fields

Inherited:

GObject.Object (1)

Name

Type

Access

Description

parent_instance

GObject.Object

r

Class Details

class Gio.SocketClient(**kwargs)
Bases:

GObject.Object

Abstract:

No

Structure:

Gio.SocketClientClass

Gio.SocketClient is a lightweight high-level utility class for connecting to a network host using a connection oriented socket type.

You create a Gio.SocketClient object, set any options you want, and then call a sync or async connect operation, which returns a Gio.SocketConnection subclass on success.

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

As Gio.SocketClient is a lightweight object, you don’t need to cache it. You can just create a new one any time you need one.

New in version 2.22.

classmethod new()[source]
Returns:

a Gio.SocketClient. Free the returned object with GObject.Object.unref().

Return type:

Gio.SocketClient

Creates a new Gio.SocketClient with the default options.

New in version 2.22.

add_application_proxy(protocol)[source]
Parameters:

protocol (str) – The proxy protocol

Enable proxy protocols to be handled by the application. When the indicated proxy protocol is returned by the Gio.ProxyResolver, Gio.SocketClient will consider this protocol as supported but will not try to find a Gio.Proxy instance to handle handshaking. The application must check for this case by calling Gio.SocketConnection.get_remote_address() on the returned Gio.SocketConnection, and seeing if it’s a Gio.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.

connect(connectable, cancellable)[source]
Parameters:
Raises:

GLib.Error

Returns:

a Gio.SocketConnection on success, None on error.

Return type:

Gio.SocketConnection

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

Upon a successful connection, a new Gio.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 Gio.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 Gio.TcpConnection.

The socket created will be the same family as the address that the connectable resolves to, unless family is set with Gio.SocketClient.set_family() or indirectly via Gio.SocketClient.set_local_address(). The socket type defaults to Gio.SocketType.STREAM but can be set with Gio.SocketClient.set_socket_type().

If a local address is specified with Gio.SocketClient.set_local_address() the socket will be bound to this address before connecting.

New in version 2.22.

connect_async(connectable, cancellable, callback, *user_data)[source]
Parameters:

This is the asynchronous version of Gio.SocketClient.connect().

You may wish to prefer the asynchronous version even in synchronous command line programs because, since 2.60, it implements RFC 8305 “Happy Eyeballs” recommendations to work around long connection timeouts in networks where IPv6 is broken by performing an IPv4 connection simultaneously without waiting for IPv6 to time out, which is not supported by the synchronous call. (This is not an API guarantee, and may change in the future.)

When the operation is finished callback will be called. You can then call Gio.SocketClient.connect_finish() to get the result of the operation.

New in version 2.22.

connect_finish(result)[source]
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult.

Raises:

GLib.Error

Returns:

a Gio.SocketConnection on success, None on error.

Return type:

Gio.SocketConnection

Finishes an async connect operation. See Gio.SocketClient.connect_async()

New in version 2.22.

connect_to_host(host_and_port, default_port, cancellable)[source]
Parameters:
Raises:

GLib.Error

Returns:

a Gio.SocketConnection on success, None on error.

Return type:

Gio.SocketConnection

This is a helper function for Gio.SocketClient.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 Gio.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.

New in version 2.22.

connect_to_host_async(host_and_port, default_port, cancellable, callback, *user_data)[source]
Parameters:

This is the asynchronous version of Gio.SocketClient.connect_to_host().

When the operation is finished callback will be called. You can then call Gio.SocketClient.connect_to_host_finish() to get the result of the operation.

New in version 2.22.

connect_to_host_finish(result)[source]
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult.

Raises:

GLib.Error

Returns:

a Gio.SocketConnection on success, None on error.

Return type:

Gio.SocketConnection

Finishes an async connect operation. See Gio.SocketClient.connect_to_host_async()

New in version 2.22.

connect_to_service(domain, service, cancellable)[source]
Parameters:
Raises:

GLib.Error

Returns:

a Gio.SocketConnection if successful, or None on error

Return type:

Gio.SocketConnection

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

connect_to_service_async(domain, service, cancellable, callback, *user_data)[source]
Parameters:

This is the asynchronous version of Gio.SocketClient.connect_to_service().

New in version 2.22.

connect_to_service_finish(result)[source]
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult.

Raises:

GLib.Error

Returns:

a Gio.SocketConnection on success, None on error.

Return type:

Gio.SocketConnection

Finishes an async connect operation. See Gio.SocketClient.connect_to_service_async()

New in version 2.22.

connect_to_uri(uri, default_port, cancellable)[source]
Parameters:
Raises:

GLib.Error

Returns:

a Gio.SocketConnection on success, None on error.

Return type:

Gio.SocketConnection

This is a helper function for Gio.SocketClient.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 Gio.SocketClient :tls is True. (Gio.SocketClient does not know to automatically assume TLS for certain URI schemes.)

Using this rather than Gio.SocketClient.connect() or Gio.SocketClient.connect_to_host() allows Gio.SocketClient to determine when to use application-specific proxy protocols.

Upon a successful connection, a new Gio.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.

New in version 2.26.

connect_to_uri_async(uri, default_port, cancellable, callback, *user_data)[source]
Parameters:

This is the asynchronous version of Gio.SocketClient.connect_to_uri().

When the operation is finished callback will be called. You can then call Gio.SocketClient.connect_to_uri_finish() to get the result of the operation.

New in version 2.26.

connect_to_uri_finish(result)[source]
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult.

Raises:

GLib.Error

Returns:

a Gio.SocketConnection on success, None on error.

Return type:

Gio.SocketConnection

Finishes an async connect operation. See Gio.SocketClient.connect_to_uri_async()

New in version 2.26.

get_enable_proxy()[source]
Returns:

whether proxying is enabled

Return type:

bool

Gets the proxy enable state; see Gio.SocketClient.set_enable_proxy()

New in version 2.26.

get_family()[source]
Returns:

a Gio.SocketFamily

Return type:

Gio.SocketFamily

Gets the socket family of the socket client.

See Gio.SocketClient.set_family() for details.

New in version 2.22.

get_local_address()[source]
Returns:

a Gio.SocketAddress or None. Do not free.

Return type:

Gio.SocketAddress or None

Gets the local address of the socket client.

See Gio.SocketClient.set_local_address() for details.

New in version 2.22.

get_protocol()[source]
Returns:

a Gio.SocketProtocol

Return type:

Gio.SocketProtocol

Gets the protocol name type of the socket client.

See Gio.SocketClient.set_protocol() for details.

New in version 2.22.

get_proxy_resolver()[source]
Returns:

The Gio.ProxyResolver being used by self.

Return type:

Gio.ProxyResolver

Gets the Gio.ProxyResolver being used by self. Normally, this will be the resolver returned by Gio.ProxyResolver.get_default(), but you can override it with Gio.SocketClient.set_proxy_resolver().

New in version 2.36.

get_socket_type()[source]
Returns:

a Gio.SocketFamily

Return type:

Gio.SocketType

Gets the socket type of the socket client.

See Gio.SocketClient.set_socket_type() for details.

New in version 2.22.

get_timeout()[source]
Returns:

the timeout in seconds

Return type:

int

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

See Gio.SocketClient.set_timeout() for details.

New in version 2.26.

get_tls()[source]
Returns:

whether self uses TLS

Return type:

bool

Gets whether self creates TLS connections. See Gio.SocketClient.set_tls() for details.

New in version 2.28.

get_tls_validation_flags()[source]
Returns:

the TLS validation flags

Return type:

Gio.TlsCertificateFlags

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

This function does not work as originally designed and is impossible to use correctly. See Gio.SocketClient :tls-validation-flags for more information.

New in version 2.28.

Deprecated since version 2.72: Do not attempt to ignore validation errors.

set_enable_proxy(enable)[source]
Parameters:

enable (bool) – whether to enable proxies

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

See also Gio.SocketClient.set_proxy_resolver().

New in version 2.26.

set_family(family)[source]
Parameters:

family (Gio.SocketFamily) – a Gio.SocketFamily

Sets the socket family of the socket client. If this is set to something other than Gio.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.

New in version 2.22.

set_local_address(address)[source]
Parameters:

address (Gio.SocketAddress or None) – a Gio.SocketAddress, or None

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.

New in version 2.22.

set_protocol(protocol)[source]
Parameters:

protocol (Gio.SocketProtocol) – a Gio.SocketProtocol

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

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

New in version 2.22.

set_proxy_resolver(proxy_resolver)[source]
Parameters:

proxy_resolver (Gio.ProxyResolver or None) – a Gio.ProxyResolver, or None for the default.

Overrides the Gio.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 Gio.SocketClient :enable-proxy, which is not changed by this function (but which is True by default)

New in version 2.36.

set_socket_type(type)[source]
Parameters:

type (Gio.SocketType) – a Gio.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 Gio.SocketType.DATAGRAM, as Gio.SocketClient is used for connection oriented services.

New in version 2.22.

set_timeout(timeout)[source]
Parameters:

timeout (int) – the timeout

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 Gio.SocketClient.connect(), etc, to fail with Gio.IOErrorEnum.TIMED_OUT.

New in version 2.26.

set_tls(tls)[source]
Parameters:

tls (bool) – whether to use TLS

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

Note that since Gio.SocketClient must return a Gio.SocketConnection, but Gio.TlsClientConnection is not a Gio.SocketConnection, this actually wraps the resulting Gio.TlsClientConnection in a Gio.TcpWrapperConnection when returning it. You can use Gio.TcpWrapperConnection.get_base_io_stream() on the return value to extract the Gio.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 Gio.TlsConnection ::accept-certificate signal), you can connect to self's Gio.SocketClient ::event signal and wait for it to be emitted with Gio.SocketClientEvent.TLS_HANDSHAKING, which will give you a chance to see the Gio.TlsClientConnection before the handshake starts.

New in version 2.28.

set_tls_validation_flags(flags)[source]
Parameters:

flags (Gio.TlsCertificateFlags) – the validation flags

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

This function does not work as originally designed and is impossible to use correctly. See Gio.SocketClient :tls-validation-flags for more information.

New in version 2.28.

Deprecated since version 2.72: Do not attempt to ignore validation errors.

do_event(event, connectable, connection) virtual
Parameters:

Signal Details

Gio.SocketClient.signals.event(socket_client, event, connectable, connection)
Signal Name:

event

Flags:

RUN_LAST

Parameters:

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:

Each event except Gio.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 Gio.SocketClient ::event signal at all for a given connectable, then it will always emit it with Gio.SocketClientEvent.COMPLETE when it is done.

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

New in version 2.32.

Property Details

Gio.SocketClient.props.enable_proxy
Name:

enable-proxy

Type:

bool

Default Value:

True

Flags:

READABLE, WRITABLE, CONSTRUCT

Enable proxy support

Gio.SocketClient.props.family
Name:

family

Type:

Gio.SocketFamily

Default Value:

Gio.SocketFamily.INVALID

Flags:

READABLE, WRITABLE, CONSTRUCT

The sockets address family to use for socket construction

Gio.SocketClient.props.local_address
Name:

local-address

Type:

Gio.SocketAddress

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT

The local address constructed sockets will be bound to

Gio.SocketClient.props.protocol
Name:

protocol

Type:

Gio.SocketProtocol

Default Value:

Gio.SocketProtocol.DEFAULT

Flags:

READABLE, WRITABLE, CONSTRUCT

The protocol to use for socket construction, or 0 for default

Gio.SocketClient.props.proxy_resolver
Name:

proxy-resolver

Type:

Gio.ProxyResolver

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT

The proxy resolver to use

New in version 2.36.

Gio.SocketClient.props.timeout
Name:

timeout

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, CONSTRUCT

The I/O timeout for sockets, or 0 for none

Gio.SocketClient.props.tls
Name:

tls

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE, CONSTRUCT

Whether to create TLS connections

Gio.SocketClient.props.tls_validation_flags
Name:

tls-validation-flags

Type:

Gio.TlsCertificateFlags

Default Value:

Gio.TlsCertificateFlags.UNKNOWN_CA | Gio.TlsCertificateFlags.BAD_IDENTITY | Gio.TlsCertificateFlags.NOT_ACTIVATED | Gio.TlsCertificateFlags.EXPIRED | Gio.TlsCertificateFlags.REVOKED | Gio.TlsCertificateFlags.INSECURE | Gio.TlsCertificateFlags.GENERIC_ERROR | Gio.TlsCertificateFlags.VALIDATE_ALL

Flags:

DEPRECATED, READABLE, WRITABLE, CONSTRUCT

The TLS validation flags used when creating TLS connections. The default value is Gio.TlsCertificateFlags.VALIDATE_ALL.

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 Gio.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 the Gio.SocketClient ::event signal, wait for it to be emitted with Gio.SocketClientEvent.TLS_HANDSHAKING, and use that to connect to Gio.TlsConnection ::accept-certificate.

Deprecated since version 2.72: Do not attempt to ignore validation errors.

Gio.SocketClient.props.type
Name:

type

Type:

Gio.SocketType

Default Value:

Gio.SocketType.STREAM

Flags:

READABLE, WRITABLE, CONSTRUCT

The sockets type to use for socket construction