Class SocketClient

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gio.SocketClient
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public class SocketClient extends GObject

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 SocketConnection subclass on success.

The type of the 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 TcpConnection.

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.

Since:
2.22

  • Constructor Details

    • SocketClient

      public SocketClient(MemorySegment address)
      Create a SocketClient instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • SocketClient

      public SocketClient()
      Create a new SocketClient.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the SocketClient class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected SocketClient asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class GObject
      Returns:
      the instance as if it were its parent type

    • addApplicationProxy

      public void addApplicationProxy(String protocol)

      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.

      Parameters:
      protocol - The proxy protocol

    • connect

      public SocketConnection connect(SocketConnectable connectable, @Nullable Cancellable cancellable) throws GErrorException

      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 SocketType.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:
      connectable - a GSocketConnectable specifying the remote address.
      cancellable - optional GCancellable object, null to ignore.
      Returns:
      a GSocketConnection on success, null on error.
      Throws:
      GErrorException - see GError
      Since:
      2.22

    • connectAsync

      public void connectAsync(SocketConnectable connectable, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)

      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 - a GSocketConnectable specifying the remote address.
      cancellable - a GCancellable, or null
      callback - a GAsyncReadyCallback
      Since:
      2.22

    • connectFinish

      public SocketConnection connectFinish(AsyncResult result) throws GErrorException
      Finishes an async connect operation. See g_socket_client_connect_async()
      Parameters:
      result - a GAsyncResult.
      Returns:
      a GSocketConnection on success, null on error.
      Throws:
      GErrorException - see GError
      Since:
      2.22

    • connectToHost

      public SocketConnection connectToHost(String hostAndPort, short defaultPort, @Nullable Cancellable cancellable) throws GErrorException

      This is a helper function for g_socket_client_connect().

      Attempts to create a TCP connection to the named host.

      hostAndPort 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 hostAndPort then defaultPort will be used as the port number to connect to.

      In general, hostAndPort is expected to be provided by the user (allowing them to give the hostname, and a port override if necessary) and defaultPort 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) null is returned and error (if non-null) is set accordingly.

      Parameters:
      hostAndPort - the name and optionally port of the host to connect to
      defaultPort - the default port to connect to
      cancellable - a GCancellable, or null
      Returns:
      a GSocketConnection on success, null on error.
      Throws:
      GErrorException - see GError
      Since:
      2.22

    • connectToHostAsync

      public void connectToHostAsync(String hostAndPort, short defaultPort, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)

      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:
      hostAndPort - the name and optionally the port of the host to connect to
      defaultPort - the default port to connect to
      cancellable - a GCancellable, or null
      callback - a GAsyncReadyCallback
      Since:
      2.22

    • connectToHostFinish

      public SocketConnection connectToHostFinish(AsyncResult result) throws GErrorException
      Finishes an async connect operation. See g_socket_client_connect_to_host_async()
      Parameters:
      result - a GAsyncResult.
      Returns:
      a GSocketConnection on success, null on error.
      Throws:
      GErrorException - see GError
      Since:
      2.22

    • connectToService

      public SocketConnection connectToService(String domain, String service, @Nullable Cancellable cancellable) throws GErrorException

      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) null is returned and error (if non-null) is set accordingly.

      Parameters:
      domain - a domain name
      service - the name of the service to connect to
      cancellable - a GCancellable, or null
      Returns:
      a GSocketConnection if successful, or null on error
      Throws:
      GErrorException - see GError

    • connectToServiceAsync

      public void connectToServiceAsync(String domain, String service, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)
      This is the asynchronous version of g_socket_client_connect_to_service().
      Parameters:
      domain - a domain name
      service - the name of the service to connect to
      cancellable - a GCancellable, or null
      callback - a GAsyncReadyCallback
      Since:
      2.22

    • connectToServiceFinish

      public SocketConnection connectToServiceFinish(AsyncResult result) throws GErrorException
      Finishes an async connect operation. See g_socket_client_connect_to_service_async()
      Parameters:
      result - a GAsyncResult.
      Returns:
      a GSocketConnection on success, null on error.
      Throws:
      GErrorException - see GError
      Since:
      2.22

    • connectToUri

      public SocketConnection connectToUri(String uri, short defaultPort, @Nullable Cancellable cancellable) throws GErrorException

      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, defaultPort 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) null is returned and error (if non-null) is set accordingly.

      Parameters:
      uri - A network URI
      defaultPort - the default port to connect to
      cancellable - a GCancellable, or null
      Returns:
      a GSocketConnection on success, null on error.
      Throws:
      GErrorException - see GError
      Since:
      2.26

    • connectToUriAsync

      public void connectToUriAsync(String uri, short defaultPort, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)

      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 - a network uri
      defaultPort - the default port to connect to
      cancellable - a GCancellable, or null
      callback - a GAsyncReadyCallback
      Since:
      2.26

    • connectToUriFinish

      public SocketConnection connectToUriFinish(AsyncResult result) throws GErrorException
      Finishes an async connect operation. See g_socket_client_connect_to_uri_async()
      Parameters:
      result - a GAsyncResult.
      Returns:
      a GSocketConnection on success, null on error.
      Throws:
      GErrorException - see GError
      Since:
      2.26

    • getEnableProxy

      public boolean getEnableProxy()
      Gets the proxy enable state; see g_socket_client_set_enable_proxy()
      Returns:
      whether proxying is enabled
      Since:
      2.26

    • getFamily

      public SocketFamily getFamily()

      Gets the socket family of the socket client.

      See g_socket_client_set_family() for details.

      Returns:
      a GSocketFamily
      Since:
      2.22

    • getLocalAddress

      public @Nullable SocketAddress getLocalAddress()

      Gets the local address of the socket client.

      See g_socket_client_set_local_address() for details.

      Returns:
      a GSocketAddress or null. Do not free.
      Since:
      2.22

    • getProtocol

      public SocketProtocol getProtocol()

      Gets the protocol name type of the socket client.

      See g_socket_client_set_protocol() for details.

      Returns:
      a GSocketProtocol
      Since:
      2.22

    • getProxyResolver

      public ProxyResolver getProxyResolver()
      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().
      Returns:
      The GProxyResolver being used by client.
      Since:
      2.36

    • getSocketType

      public SocketType getSocketType()

      Gets the socket type of the socket client.

      See g_socket_client_set_socket_type() for details.

      Returns:
      a GSocketFamily
      Since:
      2.22

    • getTimeout

      public int getTimeout()

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

      See g_socket_client_set_timeout() for details.

      Returns:
      the timeout in seconds
      Since:
      2.26

    • getTls

      public boolean getTls()
      Gets whether this SocketClient creates TLS connections. See g_socket_client_set_tls() for details.
      Returns:
      whether this SocketClient uses TLS
      Since:
      2.28

    • getTlsValidationFlags

      @Deprecated public Set<TlsCertificateFlags> getTlsValidationFlags()
      Deprecated.
      Do not attempt to ignore validation errors.

      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.

      Returns:
      the TLS validation flags
      Since:
      2.28

    • setEnableProxy

      public void setEnableProxy(boolean enable)

      Sets whether or not this SocketClient 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().

      Parameters:
      enable - whether to enable proxies
      Since:
      2.26

    • setFamily

      public void setFamily(SocketFamily family)

      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.

      Parameters:
      family - a GSocketFamily
      Since:
      2.22

    • setLocalAddress

      public void setLocalAddress(@Nullable SocketAddress address)

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

      Parameters:
      address - a GSocketAddress, or null
      Since:
      2.22

    • setProtocol

      public void setProtocol(SocketProtocol protocol)

      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.

      Parameters:
      protocol - a GSocketProtocol
      Since:
      2.22

    • setProxyResolver

      public void setProxyResolver(@Nullable ProxyResolver proxyResolver)

      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)

      Parameters:
      proxyResolver - a GProxyResolver, or null for the default.
      Since:
      2.36

    • setSocketType

      public void setSocketType(SocketType type)

      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.

      Parameters:
      type - a GSocketType
      Since:
      2.22

    • setTimeout

      public void setTimeout(int timeout)

      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 IOErrorEnum.TIMED_OUT.

      Parameters:
      timeout - the timeout
      Since:
      2.26

    • setTls

      public void setTls(boolean tls)

      Sets whether this SocketClient creates TLS (aka SSL) connections. If tls is true, this SocketClient 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 SocketClientEvent.TLS_HANDSHAKING, which will give you a chance to see the GTlsClientConnection before the handshake starts.

      Parameters:
      tls - whether to use TLS
      Since:
      2.28

    • setTlsValidationFlags

      @Deprecated public void setTlsValidationFlags(Set<TlsCertificateFlags> flags)
      Deprecated.
      Do not attempt to ignore validation errors.

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

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

      Parameters:
      flags - the validation flags
      Since:
      2.28

    • setTlsValidationFlags

      @Deprecated public void setTlsValidationFlags(TlsCertificateFlags... flags)
      Deprecated.
      Do not attempt to ignore validation errors.

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

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

      Parameters:
      flags - the validation flags
      Since:
      2.28

    • event

      protected void event(SocketClientEvent event, SocketConnectable connectable, IOStream connection)

    • onEvent

      public SignalConnection<SocketClient.EventCallback> onEvent(SocketClient.EventCallback handler)

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

      • SocketClientEvent.RESOLVED: client has successfully resolved connectable in DNS. connection will be null.

      • 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 GSocketConnection, which is not yet connected. Since GLib 2.40, you can access the remote address via g_socket_connection_get_remote_address().

      • SocketClientEvent.CONNECTED: client has successfully connected to a remote host. connection is the connected GSocketConnection.

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

      • SocketClientEvent.PROXY_NEGOTIATED: client has negotiated a connection to connectable through a proxy server. connection is the stream returned from g_proxy_connect(), which may or may not be a GSocketConnection.

      • SocketClientEvent.TLS_HANDSHAKING: client is about to begin a TLS handshake. connection is a GTlsClientConnection.

      • SocketClientEvent.TLS_HANDSHAKED: client has successfully completed the TLS handshake. connection is a GTlsClientConnection.

      • SocketClientEvent.COMPLETE: client has either successfully connected to connectable (in which case connection is the GSocketConnection that it will be returning to the caller) or has failed (in which case connection is null 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 GSocketClient::event signal at all for a given connectable, then it will always emit it with SocketClientEvent.COMPLETE when it is done.

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

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      2.32
      See Also:

    • emitEvent

      public void emitEvent(SocketClientEvent event, @Nullable SocketConnectable connectable, @Nullable IOStream connection)
      Emits the "event" signal. See onEvent(SocketClient.EventCallback).

    • builder

      public static SocketClient.Builder<? extends SocketClient.Builder> builder()
      A SocketClient.Builder object constructs a SocketClient with the specified properties. Use the various set...() methods to set properties, and finish construction with SocketClient.Builder.build().
      Returns:
      the builder object