GSocketClient

GSocketClient — Helper for connecting to a network service

Synopsis

#include <gio/gio.h>

                    GSocketClient;
void                g_socket_client_add_application_proxy
                                                        (GSocketClient *client,
                                                         const gchar *protocol);
GSocketClient *     g_socket_client_new                 (void);
GSocketConnection *      g_socket_client_connect        (GSocketClient *client,
                                                         GSocketConnectable *connectable,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                g_socket_client_connect_async       (GSocketClient *client,
                                                         GSocketConnectable *connectable,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
GSocketConnection *      g_socket_client_connect_finish (GSocketClient *client,
                                                         GAsyncResult *result,
                                                         GError **error);
GSocketConnection *      g_socket_client_connect_to_host
                                                        (GSocketClient *client,
                                                         const gchar *host_and_port,
                                                         guint16 default_port,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                g_socket_client_connect_to_host_async
                                                        (GSocketClient *client,
                                                         const gchar *host_and_port,
                                                         guint16 default_port,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
GSocketConnection *      g_socket_client_connect_to_host_finish
                                                        (GSocketClient *client,
                                                         GAsyncResult *result,
                                                         GError **error);
GSocketConnection *      g_socket_client_connect_to_service
                                                        (GSocketClient *client,
                                                         const gchar *domain,
                                                         const gchar *service,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                g_socket_client_connect_to_service_async
                                                        (GSocketClient *client,
                                                         const gchar *domain,
                                                         const gchar *service,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
GSocketConnection *      g_socket_client_connect_to_service_finish
                                                        (GSocketClient *client,
                                                         GAsyncResult *result,
                                                         GError **error);
GSocketConnection *      g_socket_client_connect_to_uri (GSocketClient *client,
                                                         const gchar *uri,
                                                         guint16 default_port,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                g_socket_client_connect_to_uri_async
                                                        (GSocketClient *client,
                                                         const gchar *uri,
                                                         guint16 default_port,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
GSocketConnection *      g_socket_client_connect_to_uri_finish
                                                        (GSocketClient *client,
                                                         GAsyncResult *result,
                                                         GError **error);
void                g_socket_client_set_family          (GSocketClient *client,
                                                         GSocketFamily family);
void                g_socket_client_set_local_address   (GSocketClient *client,
                                                         GSocketAddress *address);
void                g_socket_client_set_protocol        (GSocketClient *client,
                                                         GSocketProtocol protocol);
void                g_socket_client_set_socket_type     (GSocketClient *client,
                                                         GSocketType type);
void                g_socket_client_set_timeout         (GSocketClient *client,
                                                         guint timeout);
void                g_socket_client_set_enable_proxy    (GSocketClient *client,
                                                         gboolean enable);
void                g_socket_client_set_tls             (GSocketClient *client,
                                                         gboolean tls);
void                g_socket_client_set_tls_validation_flags
                                                        (GSocketClient *client,
                                                         GTlsCertificateFlags flags);
GSocketFamily       g_socket_client_get_family          (GSocketClient *client);
GSocketAddress *    g_socket_client_get_local_address   (GSocketClient *client);
GSocketProtocol     g_socket_client_get_protocol        (GSocketClient *client);
GSocketType         g_socket_client_get_socket_type     (GSocketClient *client);
guint               g_socket_client_get_timeout         (GSocketClient *client);
gboolean            g_socket_client_get_enable_proxy    (GSocketClient *client);
gboolean            g_socket_client_get_tls             (GSocketClient *client);
GTlsCertificateFlags  g_socket_client_get_tls_validation_flags
                                                        (GSocketClient *client);

Object Hierarchy

  GObject
   +----GSocketClient

Properties

  "enable-proxy"             gboolean              : Read / Write / Construct
  "family"                   GSocketFamily         : Read / Write / Construct
  "local-address"            GSocketAddress*       : Read / Write / Construct
  "protocol"                 GSocketProtocol       : Read / Write / Construct
  "timeout"                  guint                 : Read / Write / Construct
  "tls"                      gboolean              : Read / Write / Construct
  "tls-validation-flags"     GTlsCertificateFlags  : Read / Write / Construct
  "type"                     GSocketType           : Read / Write / Construct

Description

GSocketClient is a 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, 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.

Details

GSocketClient

typedef struct _GSocketClient GSocketClient;

A helper class for network servers to listen for and accept connections.

Since 2.22


g_socket_client_add_application_proxy ()

void                g_socket_client_add_application_proxy
                                                        (GSocketClient *client,
                                                         const gchar *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 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.

client :

a GSocketClient

protocol :

The proxy protocol

g_socket_client_new ()

GSocketClient *     g_socket_client_new                 (void);

Creates a new GSocketClient with the default options.

Returns :

a GSocketClient. Free the returned object with g_object_unref().

Since 2.22


g_socket_client_connect ()

GSocketConnection *      g_socket_client_connect        (GSocketClient *client,
                                                         GSocketConnectable *connectable,
                                                         GCancellable *cancellable,
                                                         GError **error);

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

client :

a GSocketClient.

connectable :

a GSocketConnectable specifying the remote address.

cancellable :

optional GCancellable object, NULL to ignore. [allow-none]

error :

GError for error reporting, or NULL to ignore.

Returns :

a GSocketConnection on success, NULL on error. [transfer full]

Since 2.22


g_socket_client_connect_async ()

void                g_socket_client_connect_async       (GSocketClient *client,
                                                         GSocketConnectable *connectable,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

This is the asynchronous version of g_socket_client_connect().

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.

client :

a GTcpClient

connectable :

a GSocketConnectable specifying the remote address.

cancellable :

a GCancellable, or NULL. [allow-none]

callback :

a GAsyncReadyCallback. [scope async]

user_data :

user data for the callback. [closure]

Since 2.22


g_socket_client_connect_finish ()

GSocketConnection *      g_socket_client_connect_finish (GSocketClient *client,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes an async connect operation. See g_socket_client_connect_async()

client :

a GSocketClient.

result :

a GAsyncResult.

error :

a GError location to store the error occuring, or NULL to ignore.

Returns :

a GSocketConnection on success, NULL on error. [transfer full]

Since 2.22


g_socket_client_connect_to_host ()

GSocketConnection *      g_socket_client_connect_to_host
                                                        (GSocketClient *client,
                                                         const gchar *host_and_port,
                                                         guint16 default_port,
                                                         GCancellable *cancellable,
                                                         GError **error);

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

client :

a GSocketClient

host_and_port :

the name and optionally port of the host to connect to

default_port :

the default port to connect to

cancellable :

a GCancellable, or NULL. [allow-none]

error :

a pointer to a GError, or NULL

Returns :

a GSocketConnection on success, NULL on error. [transfer full]

Since 2.22


g_socket_client_connect_to_host_async ()

void                g_socket_client_connect_to_host_async
                                                        (GSocketClient *client,
                                                         const gchar *host_and_port,
                                                         guint16 default_port,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

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.

client :

a GTcpClient

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 GCancellable, or NULL. [allow-none]

callback :

a GAsyncReadyCallback. [scope async]

user_data :

user data for the callback. [closure]

Since 2.22


g_socket_client_connect_to_host_finish ()

GSocketConnection *      g_socket_client_connect_to_host_finish
                                                        (GSocketClient *client,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes an async connect operation. See g_socket_client_connect_to_host_async()

client :

a GSocketClient.

result :

a GAsyncResult.

error :

a GError location to store the error occuring, or NULL to ignore.

Returns :

a GSocketConnection on success, NULL on error. [transfer full]

Since 2.22


g_socket_client_connect_to_service ()

GSocketConnection *      g_socket_client_connect_to_service
                                                        (GSocketClient *client,
                                                         const gchar *domain,
                                                         const gchar *service,
                                                         GCancellable *cancellable,
                                                         GError **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 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.

client :

a GSocketConnection

domain :

a domain name

service :

the name of the service to connect to

cancellable :

a GCancellable, or NULL. [allow-none]

error :

a pointer to a GError, or NULL

Returns :

a GSocketConnection if successful, or NULL on error. [transfer full]

g_socket_client_connect_to_service_async ()

void                g_socket_client_connect_to_service_async
                                                        (GSocketClient *client,
                                                         const gchar *domain,
                                                         const gchar *service,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

This is the asynchronous version of g_socket_client_connect_to_service().

client :

a GSocketClient

domain :

a domain name

service :

the name of the service to connect to

cancellable :

a GCancellable, or NULL. [allow-none]

callback :

a GAsyncReadyCallback. [scope async]

user_data :

user data for the callback. [closure]

Since 2.22


g_socket_client_connect_to_service_finish ()

GSocketConnection *      g_socket_client_connect_to_service_finish
                                                        (GSocketClient *client,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes an async connect operation. See g_socket_client_connect_to_service_async()

client :

a GSocketClient.

result :

a GAsyncResult.

error :

a GError location to store the error occuring, or NULL to ignore.

Returns :

a GSocketConnection on success, NULL on error. [transfer full]

Since 2.22


g_socket_client_connect_to_uri ()

GSocketConnection *      g_socket_client_connect_to_uri (GSocketClient *client,
                                                         const gchar *uri,
                                                         guint16 default_port,
                                                         GCancellable *cancellable,
                                                         GError **error);

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

client :

a GSocketClient

uri :

A network URI

default_port :

the default port to connect to

cancellable :

a GCancellable, or NULL. [allow-none]

error :

a pointer to a GError, or NULL

Returns :

a GSocketConnection on success, NULL on error. [transfer full]

Since 2.26


g_socket_client_connect_to_uri_async ()

void                g_socket_client_connect_to_uri_async
                                                        (GSocketClient *client,
                                                         const gchar *uri,
                                                         guint16 default_port,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

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.

client :

a GSocketClient

uri :

a network uri

default_port :

the default port to connect to

cancellable :

a GCancellable, or NULL. [allow-none]

callback :

a GAsyncReadyCallback. [scope async]

user_data :

user data for the callback. [closure]

Since 2.26


g_socket_client_connect_to_uri_finish ()

GSocketConnection *      g_socket_client_connect_to_uri_finish
                                                        (GSocketClient *client,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes an async connect operation. See g_socket_client_connect_to_uri_async()

client :

a GSocketClient.

result :

a GAsyncResult.

error :

a GError location to store the error occuring, or NULL to ignore.

Returns :

a GSocketConnection on success, NULL on error. [transfer full]

Since 2.26


g_socket_client_set_family ()

void                g_socket_client_set_family          (GSocketClient *client,
                                                         GSocketFamily family);

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.

client :

a GSocketClient.

family :

a GSocketFamily

Since 2.22


g_socket_client_set_local_address ()

void                g_socket_client_set_local_address   (GSocketClient *client,
                                                         GSocketAddress *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 the the local side of the connection is on a specific port, or on a specific interface.

client :

a GSocketClient.

address :

a GSocketAddress, or NULL

Since 2.22


g_socket_client_set_protocol ()

void                g_socket_client_set_protocol        (GSocketClient *client,
                                                         GSocketProtocol protocol);

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

If protocol is 0 that means to use the default protocol for the socket family and type.

client :

a GSocketClient.

protocol :

a GSocketProtocol

Since 2.22


g_socket_client_set_socket_type ()

void                g_socket_client_set_socket_type     (GSocketClient *client,
                                                         GSocketType 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 G_SOCKET_TYPE_DATAGRAM, as GSocketClient is used for connection oriented services.

client :

a GSocketClient.

type :

a GSocketType

Since 2.22


g_socket_client_set_timeout ()

void                g_socket_client_set_timeout         (GSocketClient *client,
                                                         guint 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 G_IO_ERROR_TIMED_OUT.

client :

a GSocketClient.

timeout :

the timeout

Since 2.26


g_socket_client_set_enable_proxy ()

void                g_socket_client_set_enable_proxy    (GSocketClient *client,
                                                         gboolean enable);

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.

client :

a GSocketClient.

enable :

whether to enable proxies

Since 2.26


g_socket_client_set_tls ()

void                g_socket_client_set_tls             (GSocketClient *client,
                                                         gboolean tls);

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.

client :

a GSocketClient.

tls :

whether to use TLS

Since 2.28


g_socket_client_set_tls_validation_flags ()

void                g_socket_client_set_tls_validation_flags
                                                        (GSocketClient *client,
                                                         GTlsCertificateFlags flags);

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

client :

a GSocketClient.

flags :

the validation flags

Since 2.28


g_socket_client_get_family ()

GSocketFamily       g_socket_client_get_family          (GSocketClient *client);

Gets the socket family of the socket client.

See g_socket_client_set_family() for details.

client :

a GSocketClient.

Returns :

a GSocketFamily

Since 2.22


g_socket_client_get_local_address ()

GSocketAddress *    g_socket_client_get_local_address   (GSocketClient *client);

Gets the local address of the socket client.

See g_socket_client_set_local_address() for details.

client :

a GSocketClient.

Returns :

a GSocketAddres or NULL. don't free. [transfer none]

Since 2.22


g_socket_client_get_protocol ()

GSocketProtocol     g_socket_client_get_protocol        (GSocketClient *client);

Gets the protocol name type of the socket client.

See g_socket_client_set_protocol() for details.

client :

a GSocketClient

Returns :

a GSocketProtocol

Since 2.22


g_socket_client_get_socket_type ()

GSocketType         g_socket_client_get_socket_type     (GSocketClient *client);

Gets the socket type of the socket client.

See g_socket_client_set_socket_type() for details.

client :

a GSocketClient.

Returns :

a GSocketFamily

Since 2.22


g_socket_client_get_timeout ()

guint               g_socket_client_get_timeout         (GSocketClient *client);

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

See g_socket_client_set_timeout() for details.

client :

a GSocketClient

Returns :

the timeout in seconds

Since 2.26


g_socket_client_get_enable_proxy ()

gboolean            g_socket_client_get_enable_proxy    (GSocketClient *client);

Gets the proxy enable state; see g_socket_client_set_enable_proxy()

client :

a GSocketClient.

Returns :

whether proxying is enabled

Since 2.26


g_socket_client_get_tls ()

gboolean            g_socket_client_get_tls             (GSocketClient *client);

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

client :

a GSocketClient.

Returns :

whether client uses TLS

Since 2.28


g_socket_client_get_tls_validation_flags ()

GTlsCertificateFlags  g_socket_client_get_tls_validation_flags
                                                        (GSocketClient *client);

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

client :

a GSocketClient.

Returns :

the TLS validation flags

Since 2.28

Property Details

The "enable-proxy" property

  "enable-proxy"             gboolean              : Read / Write / Construct

Enable proxy support.

Default value: TRUE


The "family" property

  "family"                   GSocketFamily         : Read / Write / Construct

The sockets address family to use for socket construction.

Default value: G_SOCKET_FAMILY_INVALID


The "local-address" property

  "local-address"            GSocketAddress*       : Read / Write / Construct

The local address constructed sockets will be bound to.


The "protocol" property

  "protocol"                 GSocketProtocol       : Read / Write / Construct

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

Default value: G_SOCKET_PROTOCOL_DEFAULT


The "timeout" property

  "timeout"                  guint                 : Read / Write / Construct

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

Default value: 0


The "tls" property

  "tls"                      gboolean              : Read / Write / Construct

Whether to create TLS connections.

Default value: FALSE


The "tls-validation-flags" property

  "tls-validation-flags"     GTlsCertificateFlags  : Read / Write / Construct

TLS validation flags to use.

Default value: G_TLS_CERTIFICATE_UNKNOWN_CA|G_TLS_CERTIFICATE_BAD_IDENTITY|G_TLS_CERTIFICATE_NOT_ACTIVATED|G_TLS_CERTIFICATE_EXPIRED|G_TLS_CERTIFICATE_REVOKED|G_TLS_CERTIFICATE_INSECURE|G_TLS_CERTIFICATE_GENERIC_ERROR


The "type" property

  "type"                     GSocketType           : Read / Write / Construct

The sockets type to use for socket construction.

Default value: G_SOCKET_TYPE_STREAM

See Also

GSocketConnection, GSocketListener