Class: Gio::SocketClient

Inherits:
Object
  • Object
show all
Defined in:
(unknown)

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Gio::SocketClient

Creates a new GSocket::Client with the default options.

Instance Method Details

#add_application_proxy(protocol) ⇒ nil

Enable proxy protocols to be handled by the application. When the
indicated proxy protocol is returned by the GProxy::Resolver,
GSocket::Client will consider this protocol as supported but will
not try to find a #GProxy instance to handle handshaking. The
application must check for this case by calling
g_socket_connection_get_remote_address() on the returned
GSocket::Connection, and seeing if it's a #GProxyAddress 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.

Parameters:

  • protocol (String) —

    The proxy protocol

Returns:

  • (nil)

#connect(connectable, cancellable) ⇒ Gio::SocketConnection

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

Upon a successful connection, a new GSocket::Connection 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 GSocket::Connection object returned depends on the type of
the underlying socket that is used. For instance, for a TCP/IP connection
it will be a GTcp::Connection.

The socket created will be the same family as the address that the
connectable resolves to, unless family is set with g_socket_client_set_family()
or indirectly via g_socket_client_set_local_address(). The socket type
defaults to %G_SOCKET_TYPE_STREAM but can be set with
g_socket_client_set_socket_type().

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

Parameters:

Returns:

#connect_async(connectable, cancellable, callback, user_data) ⇒ nil

This is the asynchronous version of g_socket_client_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 g_socket_client_connect_finish() to get
the result of the operation.

Parameters:

  • connectable (Gio::SocketConnectable) —

    a GSocket::Connectable specifying the remote address.

  • cancellable (Gio::Cancellable) —

    a #GCancellable, or nil

  • callback (Gio::AsyncReadyCallback) —

    a GAsync::ReadyCallback

  • user_data (GObject) —

    user data for the callback

Returns:

  • (nil)

#connect_finish(result) ⇒ Gio::SocketConnection

Finishes an async connect operation. See g_socket_client_connect_async()

Parameters:

Returns:

#connect_to_host(host_and_port, default_port, cancellable) ⇒ Gio::SocketConnection

This is a helper function for g_socket_client_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 GSocket::Connection 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) nil is returned and error (if non-nil) is set
accordingly.

Parameters:

  • host_and_port (String) —

    the name and optionally port of the host to connect to

  • default_port (Integer) —

    the default port to connect to

  • cancellable (Gio::Cancellable) —

    a #GCancellable, or nil

Returns:

#connect_to_host_async(host_and_port, default_port, cancellable, callback, user_data) ⇒ nil

This is the asynchronous version of g_socket_client_connect_to_host().

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

Parameters:

  • host_and_port (String) —

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

  • default_port (Integer) —

    the default port to connect to

  • cancellable (Gio::Cancellable) —

    a #GCancellable, or nil

  • callback (Gio::AsyncReadyCallback) —

    a GAsync::ReadyCallback

  • user_data (GObject) —

    user data for the callback

Returns:

  • (nil)

#connect_to_host_finish(result) ⇒ Gio::SocketConnection

Finishes an async connect operation. See g_socket_client_connect_to_host_async()

Parameters:

Returns:

#connect_to_service(domain, service, cancellable) ⇒ 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 GSocket::Connection 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) nil is returned and error (if non-nil) is set
accordingly.

Parameters:

  • domain (String) —

    a domain name

  • service (String) —

    the name of the service to connect to

  • cancellable (Gio::Cancellable) —

    a #GCancellable, or nil

Returns:

#connect_to_service_async(domain, service, cancellable, callback, user_data) ⇒ nil

This is the asynchronous version of
g_socket_client_connect_to_service().

Parameters:

  • domain (String) —

    a domain name

  • service (String) —

    the name of the service to connect to

  • cancellable (Gio::Cancellable) —

    a #GCancellable, or nil

  • callback (Gio::AsyncReadyCallback) —

    a GAsync::ReadyCallback

  • user_data (GObject) —

    user data for the callback

Returns:

  • (nil)

#connect_to_service_finish(result) ⇒ Gio::SocketConnection

Finishes an async connect operation. See g_socket_client_connect_to_service_async()

Parameters:

Returns:

#connect_to_uri(uri, default_port, cancellable) ⇒ Gio::SocketConnection

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

Using this rather than g_socket_client_connect() or
g_socket_client_connect_to_host() allows GSocket::Client to
determine when to use application-specific proxy protocols.

Upon a successful connection, a new GSocket::Connection 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) nil is returned and error (if non-nil) is set
accordingly.

Parameters:

  • uri (String) —

    A network URI

  • default_port (Integer) —

    the default port to connect to

  • cancellable (Gio::Cancellable) —

    a #GCancellable, or nil

Returns:

#connect_to_uri_async(uri, default_port, cancellable, callback, user_data) ⇒ nil

This is the asynchronous version of g_socket_client_connect_to_uri().

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

Parameters:

  • uri (String) —

    a network uri

  • default_port (Integer) —

    the default port to connect to

  • cancellable (Gio::Cancellable) —

    a #GCancellable, or nil

  • callback (Gio::AsyncReadyCallback) —

    a GAsync::ReadyCallback

  • user_data (GObject) —

    user data for the callback

Returns:

  • (nil)

#connect_to_uri_finish(result) ⇒ Gio::SocketConnection

Finishes an async connect operation. See g_socket_client_connect_to_uri_async()

Parameters:

Returns:

#enable_proxy ⇒ Boolean

Gets the proxy enable state; see g_socket_client_set_enable_proxy()

Returns:

  • (Boolean) —

    whether proxying is enabled

#enable_proxy=(enable_proxy) ⇒ Boolean

Enable proxy support.

Parameters:

  • enable_proxy (Boolean)

Returns:

  • (Boolean) —

    enable-proxy

  • (Boolean) —

    enable-proxy

#enable_proxy? ⇒ Boolean

Enable proxy support.

Returns:

  • (Boolean) —

    enable-proxy

#family ⇒ Gio::SocketFamily

The address family to use for socket construction.

Returns:

#family=(family) ⇒ Gio::SocketFamily

The address family to use for socket construction.

Parameters:

Returns:

#local_address ⇒ Gio::SocketAddress

The local address constructed sockets will be bound to.

Returns:

#local_address=(local_address) ⇒ Gio::SocketAddress

The local address constructed sockets will be bound to.

Parameters:

Returns:

#protocol ⇒ Gio::SocketProtocol

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

Returns:

#protocol=(protocol) ⇒ Gio::SocketProtocol

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

Parameters:

Returns:

#proxy_resolver ⇒ Gio::ProxyResolver

The proxy resolver to use

Returns:

#proxy_resolver=(proxy_resolver) ⇒ Gio::ProxyResolver

The proxy resolver to use

Parameters:

Returns:

#socket_type ⇒ Gio::SocketType

Gets the socket type of the socket client.

See g_socket_client_set_socket_type() for details.

Returns:

#socket_type=(type) ⇒ nil

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 %G_SOCKET_TYPE_DATAGRAM,
as GSocketClient is used for connection oriented services.

Parameters:

Returns:

  • (nil)

#timeout ⇒ Integer

The I/O timeout for sockets, in seconds, or 0 for none.

Returns:

  • (Integer) —

    timeout

#timeout=(timeout) ⇒ Integer

The I/O timeout for sockets, in seconds, or 0 for none.

Parameters:

  • timeout (Integer)

Returns:

  • (Integer) —

    timeout

  • (Integer) —

    timeout

#tls ⇒ Boolean

Gets whether client creates TLS connections. See
g_socket_client_set_tls() for details.

Returns:

  • (Boolean) —

    whether client uses TLS

#tls=(tls) ⇒ Boolean

Whether to create TLS connections.

Parameters:

  • tls (Boolean)

Returns:

  • (Boolean) —

    tls

  • (Boolean) —

    tls

#tls? ⇒ Boolean

Whether to create TLS connections.

Returns:

  • (Boolean) —

    tls

#tls_validation_flags ⇒ Gio::TlsCertificateFlags

The TLS validation flags used when creating TLS connections. The
default value is %G_TLS_CERTIFICATE_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
%G_TLS_CERTIFICATE_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 GSocket::Client::event signal, wait for it to be
emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, and use that to
connect to GTls::Connection::accept-certificate.

Returns:

#tls_validation_flags=(tls_validation_flags) ⇒ Gio::TlsCertificateFlags

The TLS validation flags used when creating TLS connections. The
default value is %G_TLS_CERTIFICATE_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
%G_TLS_CERTIFICATE_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 GSocket::Client::event signal, wait for it to be
emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, and use that to
connect to GTls::Connection::accept-certificate.

Parameters:

Returns:

#type ⇒ Gio::SocketType

The type to use for socket construction.

Returns:

#type=(type) ⇒ Gio::SocketType

The type to use for socket construction.

Parameters:

Returns: