GSocketClient
3
GIO Library

# GSocketClient

Helper for connecting to a network service

## Synopsis

    #include <gio/gio.h>

                        GSocketClient;
    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);
    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);
    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);

## Object Hierarchy

      GObject
       +----GSocketClient

## Properties

      "family"                   GSocketFamily         : Read / Write / Construct
      "local-address"            GSocketAddress*       : Read / Write / Construct
      "protocol"                 GSocketProtocol       : 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_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.

`error` :

  GError for error reporting, or `NULL` to ignore.

Returns :

  a GSocketConnection on success, `NULL` on error.

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`

`callback` :

  a GAsyncReadyCallback

`user_data` :

  user data for the callback

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.

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 SocketClient

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

`error` :

  a pointer to a GError, or `NULL`

Returns :

  a GSocketConnection on success, `NULL` on error.

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`

`callback` :

  a GAsyncReadyCallback

`user_data` :

  user data for the callback

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.

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`

`error` :

  a pointer to a GError, or `NULL`

Returns :

  a GSocketConnection if successful, or `NULL` on error

### 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`

`callback` :

  a GAsyncReadyCallback

`user_data` :

  user data for the callback

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.

Since 2.22

### 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_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

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

## Property Details

### 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 `"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