class Gio::SocketClient

Overview

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

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

The type of the #GSocketConnection 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 #GTcpConnection.

As #GSocketClient is a lightweight object, you don't need to cache it. You can just create a new one any time you need one.

Defined in:

lib/gi-crystal/src/auto/gio-2.0/socket_client.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class GObject::Object

bind_property(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags) : GObject::Binding bind_property, bind_property_full(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags, transform_to : GObject::Closure, transform_from : GObject::Closure) : GObject::Binding bind_property_full, data(key : String) : Pointer(Void)? data, finalize finalize, freeze_notify : Nil freeze_notify, getv(names : Enumerable(String), values : Enumerable(_)) : Nil getv, notify(property_name : String) : Nil notify, notify_by_pspec(pspec : GObject::ParamSpec) : Nil notify_by_pspec, notify_signal notify_signal, property(property_name : String, value : _) : Nil property, qdata(quark : UInt32) : Pointer(Void)? qdata, ref_count : UInt32 ref_count, run_dispose : Nil run_dispose, set_data(key : String, data : Pointer(Void)?) : Nil set_data, set_property(property_name : String, value : _) : Nil set_property, steal_data(key : String) : Pointer(Void)? steal_data, steal_qdata(quark : UInt32) : Pointer(Void)? steal_qdata, thaw_notify : Nil thaw_notify, to_unsafe : Pointer(Void) to_unsafe, watch_closure(closure : GObject::Closure) : Nil watch_closure

Constructor methods inherited from class GObject::Object

cast(obj : GObject::Object) : self cast, cast?(obj : GObject::Object) : self? cast?, new(pointer : Pointer(Void), transfer : GICrystal::Transfer)
new
new
, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter)) : self newv

Class methods inherited from class GObject::Object

compat_control(what : UInt64, data : Pointer(Void)?) : UInt64 compat_control, g_type : UInt64 g_type, interface_find_property(g_iface : GObject::TypeInterface, property_name : String) : GObject::ParamSpec interface_find_property, interface_list_properties(g_iface : GObject::TypeInterface) : Enumerable(GObject::ParamSpec) interface_list_properties

Constructor Detail

def self.new : self #

Creates a new #GSocketClient with the default options.


def self.new(*, enable_proxy : Bool? = nil, family : Gio::SocketFamily? = nil, local_address : Gio::SocketAddress? = nil, protocol : Gio::SocketProtocol? = nil, proxy_resolver : Gio::ProxyResolver? = nil, timeout : UInt32? = nil, tls : Bool? = nil, tls_validation_flags : Gio::TlsCertificateFlags? = nil, type : Gio::SocketType? = nil) #

Class Method Detail

def self.g_type : UInt64 #

Returns the type id (GType) registered in GLib type system.


Instance Method Detail

def add_application_proxy(protocol : String) : Nil #

Enable proxy protocols to be handled by the application. When the indicated proxy protocol is returned by the #GProxyResolver, #GSocketClient 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 #GSocketConnection, 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.


def connect(connectable : Gio::SocketConnectable, cancellable : Gio::Cancellable?) : Gio::SocketConnection #

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

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

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.


def connect_async(connectable : Gio::SocketConnectable, cancellable : Gio::Cancellable?, callback : Gio::AsyncReadyCallback?, user_data : Pointer(Void)?) : 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.


def connect_finish(result : Gio::AsyncResult) : Gio::SocketConnection #

Finishes an async connect operation. See g_socket_client_connect_async()


def connect_to_host(host_and_port : String, default_port : UInt16, cancellable : Gio::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 #GSocketConnection 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.


def connect_to_host_async(host_and_port : String, default_port : UInt16, cancellable : Gio::Cancellable?, callback : Gio::AsyncReadyCallback?, user_data : Pointer(Void)?) : 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.


def connect_to_host_finish(result : Gio::AsyncResult) : Gio::SocketConnection #

Finishes an async connect operation. See g_socket_client_connect_to_host_async()


def connect_to_service(domain : String, service : String, cancellable : Gio::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 #GSocketConnection 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.


def connect_to_service_async(domain : String, service : String, cancellable : Gio::Cancellable?, callback : Gio::AsyncReadyCallback?, user_data : Pointer(Void)?) : Nil #

This is the asynchronous version of g_socket_client_connect_to_service().


def connect_to_service_finish(result : Gio::AsyncResult) : Gio::SocketConnection #

Finishes an async connect operation. See g_socket_client_connect_to_service_async()


def connect_to_uri(uri : String, default_port : UInt16, cancellable : Gio::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 #GSocketClient:tls is true. (#GSocketClient 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 #GSocketClient to determine when to use application-specific proxy protocols.

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


def connect_to_uri_async(uri : String, default_port : UInt16, cancellable : Gio::Cancellable?, callback : Gio::AsyncReadyCallback?, user_data : Pointer(Void)?) : 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.


def connect_to_uri_finish(result : Gio::AsyncResult) : Gio::SocketConnection #

Finishes an async connect operation. See g_socket_client_connect_to_uri_async()


def enable_proxy : Bool #

Gets the proxy enable state; see g_socket_client_set_enable_proxy()


def enable_proxy=(enable : Bool) : Nil #

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

See also g_socket_client_set_proxy_resolver().


def enable_proxy? : Bool #

def event_signal #

def family : Gio::SocketFamily #

Gets the socket family of the socket client.

See g_socket_client_set_family() for details.


def family=(family : Gio::SocketFamily) : Nil #

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


def local_address : Gio::SocketAddress? #

Gets the local address of the socket client.

See g_socket_client_set_local_address() for details.


def local_address=(address : Gio::SocketAddress?) : Nil #

Sets the local address of the socket client. The sockets created by this object will bound to the specified address (if not nil) 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.


def protocol : Gio::SocketProtocol #

Gets the protocol name type of the socket client.

See g_socket_client_set_protocol() for details.


def protocol=(protocol : Gio::SocketProtocol) : Nil #

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

If @protocol is %G_SOCKET_PROTOCOL_DEFAULT that means to use the default protocol for the socket family and type.


def proxy_resolver : Gio::ProxyResolver #

Gets the #GProxyResolver being used by @client. Normally, this will be the resolver returned by g_proxy_resolver_get_default(), but you can override it with g_socket_client_set_proxy_resolver().


def proxy_resolver=(proxy_resolver : Gio::ProxyResolver?) : Nil #

Overrides the #GProxyResolver used by @client. 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 #GSocketClient:enable-proxy, which is not changed by this function (but which is true by default)


def socket_type : Gio::SocketType #

Gets the socket type of the socket client.

See g_socket_client_set_socket_type() for details.


def socket_type=(type : Gio::SocketType) : 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.


def timeout : UInt32 #

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

See g_socket_client_set_timeout() for details.


def timeout=(timeout : UInt32) : Nil #

Sets the I/O timeout for sockets created by @client. @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 g_socket_client_connect(), etc, to fail with %G_IO_ERROR_TIMED_OUT.


def tls : Bool #

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


def tls=(tls : Bool) : Nil #

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

Note that since #GSocketClient must return a #GSocketConnection, but #GTlsClientConnection is not a #GSocketConnection, this actually wraps the resulting #GTlsClientConnection in a #GTcpWrapperConnection when returning it. You can use g_tcp_wrapper_connection_get_base_io_stream() on the return value to extract the #GTlsClientConnection.

If you need to modify the behavior of the TLS handshake (eg, by setting a client-side certificate to use, or connecting to the #GTlsConnection::accept-certificate signal), you can connect to @client's #GSocketClient::event signal and wait for it to be emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you a chance to see the #GTlsClientConnection before the handshake starts.


def tls? : Bool #

def tls_validation_flags : Gio::TlsCertificateFlags #

Gets the TLS validation flags used creating TLS connections via @client.

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


def tls_validation_flags=(flags : Gio::TlsCertificateFlags) : Nil #

Sets the TLS validation flags used when creating TLS connections via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.

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


def type : Gio::SocketType #

def type=(value : Gio::SocketType) : Gio::SocketType #