GSocketConnectable: GIO Reference Manual

## GSocketConnectable GSocketConnectable — Interface for potential socket endpoints |

## Functions

GSocketAddressEnumerator * | g_socket_connectable_enumerate ()
GSocketAddressEnumerator * | g_socket_connectable_proxy_enumerate ()
gchar * | g_socket_connectable_to_string ()

## Types and Values

| GSocketConnectable
struct | GSocketConnectableIface

## Object Hierarchy

        GInterface
        ╰── GSocketConnectable

## Prerequisites

GSocketConnectable requires GObject.

## Known Implementations

GSocketConnectable is implemented by GInetSocketAddress, GNativeSocketAddress, GNetworkAddress, GNetworkService, GProxyAddress, GSocketAddress and GUnixSocketAddress.

## Includes

    #include <gio/gio.h>

## Description

Objects that describe one or more potential socket endpoints implement GSocketConnectable. Callers can then use `g_socket_connectable_enumerate()` to get a GSocketAddressEnumerator to try out each socket address in turn until one succeeds, as shown in the sample code below.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    MyConnectionType *
    connect_to_host (const char    *hostname,
                     guint16        port,
                     GCancellable  *cancellable,
                     GError       **error)
    {
      MyConnection *conn = NULL;
      GSocketConnectable *addr;
      GSocketAddressEnumerator *enumerator;
      GSocketAddress *sockaddr;
      GError *conn_error = NULL;

      addr = g_network_address_new (hostname, port);
      enumerator = g_socket_connectable_enumerate (addr);
      g_object_unref (addr);

      // Try each sockaddr until we succeed. Record the first connection error,
      // but not any further ones (since they'll probably be basically the same
      // as the first).
      while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
        {
          conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
          g_object_unref (sockaddr);
        }
      g_object_unref (enumerator);

      if (conn)
        {
          if (conn_error)
            {
              // We couldn't connect to the first address, but we succeeded
              // in connecting to a later address.
              g_error_free (conn_error);
            }
          return conn;
        }
      else if (error)
        {
          /// Either initial lookup failed, or else the caller cancelled us.
          if (conn_error)
            g_error_free (conn_error);
          return NULL;
        }
      else
        {
          g_error_propagate (error, conn_error);
          return NULL;
        }
    }

## Functions

### g_socket_connectable_enumerate ()

    GSocketAddressEnumerator *
    g_socket_connectable_enumerate (GSocketConnectable *connectable);

Creates a GSocketAddressEnumerator for `connectable` .

#### Parameters

connectable | a GSocketConnectable |

#### Returns

a new GSocketAddressEnumerator.

[transfer full]

Since: 2.22

### g_socket_connectable_proxy_enumerate ()

    GSocketAddressEnumerator *
    g_socket_connectable_proxy_enumerate (GSocketConnectable *connectable);

Creates a GSocketAddressEnumerator for `connectable` that will return a GProxyAddress for each of its addresses that you must connect to via a proxy.

If `connectable` does not implement `g_socket_connectable_proxy_enumerate()`, this will fall back to calling `g_socket_connectable_enumerate()`.

#### Parameters

connectable | a GSocketConnectable |

#### Returns

a new GSocketAddressEnumerator.

[transfer full]

Since: 2.26

### g_socket_connectable_to_string ()

    gchar *
    g_socket_connectable_to_string (GSocketConnectable *connectable);

Format a GSocketConnectable as a string. This is a human-readable format for use in debugging output, and is not a stable serialization format. It is not suitable for use in user interfaces as it exposes too much information for a user.

If the GSocketConnectable implementation does not support string formatting, the implementation’s type name will be returned as a fallback.

#### Parameters

connectable | a GSocketConnectable |

#### Returns

the formatted string.

[transfer full]

Since: 2.48

## Types and Values

### GSocketConnectable

    typedef struct _GSocketConnectable GSocketConnectable;

Interface for objects that contain or generate a GSocketAddress.

### struct GSocketConnectableIface

    struct GSocketConnectableIface {
      GTypeInterface g_iface;

      /* Virtual Table */

      GSocketAddressEnumerator * (* enumerate)       (GSocketConnectable *connectable);

      GSocketAddressEnumerator * (* proxy_enumerate) (GSocketConnectable *connectable);

      gchar                    * (* to_string)       (GSocketConnectable *connectable);
    };

Provides an interface for returning a GSocketAddressEnumerator and GProxyAddressEnumerator

#### Members

`enumerate` () | Creates a GSocketAddressEnumerator |
`proxy_enumerate` () | Creates a GProxyAddressEnumerator |
`to_string` () | Format the connectable’s address as a string for debugging. Implementing this is optional. (Since: 2.48) |