## GSocketConnectable

GSocketConnectable — Interface for potential socket endpoints

## Synopsis

                        GSocketConnectable;
                        GSocketConnectableIface;
    GSocketAddressEnumerator * g_socket_connectable_enumerate
                                                            (GSocketConnectable *connectable);

                        GSocketAddressEnumerator;
    GSocketAddress *    g_socket_address_enumerator_next    (GSocketAddressEnumerator *enumerator,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                g_socket_address_enumerator_next_async
                                                            (GSocketAddressEnumerator *enumerator,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GSocketAddress *    g_socket_address_enumerator_next_finish
                                                            (GSocketAddressEnumerator *enumerator,
                                                             GAsyncResult *result,
                                                             GError **error);

## Object Hierarchy

      GInterface
       +----GSocketConnectable

      GObject
       +----GSocketAddressEnumerator

## Prerequisites

GSocketConnectable requires GObject.

## Known Implementations

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

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

    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 ("www.gnome.org", 80);
      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 the 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;
        }
    }

## Details

### GSocketConnectable

    typedef struct _GSocketConnectable GSocketConnectable;

Interface for objects that contain or generate GSocketAddresses.

### GSocketConnectableIface

    typedef struct {
      GTypeInterface g_iface;

      /* Virtual Table */

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

Provides an interface for returning a GSocketAddressEnumerator

GTypeInterface `g_iface`; | The parent interface.
`enumerate` () | Creates a GSocketAddressEnumerator

### g_socket_connectable_enumerate ()

    GSocketAddressEnumerator * g_socket_connectable_enumerate
                                                            (GSocketConnectable *connectable);

Creates a GSocketAddressEnumerator for `connectable`.

`connectable` : | a GSocketConnectable
Returns : | a new GSocketAddressEnumerator.

Since 2.22

### GSocketAddressEnumerator

    typedef struct _GSocketAddressEnumerator GSocketAddressEnumerator;

Enumerator type for objects that contain or generate GSocketAddresses.

### g_socket_address_enumerator_next ()

    GSocketAddress *    g_socket_address_enumerator_next    (GSocketAddressEnumerator *enumerator,
                                                             GCancellable *cancellable,
                                                             GError **error);

Retrieves the next GSocketAddress from `enumerator`. Note that this may block for some amount of time. (Eg, a GNetworkAddress may need to do a DNS lookup before it can return an address.) Use `g_socket_address_enumerator_next_async()` if you need to avoid blocking.

If `enumerator` is expected to yield addresses, but for some reason is unable to (eg, because of a DNS error), then the first call to `g_socket_address_enumerator_next()` will return an appropriate error in *`error`. However, if the first call to `g_socket_address_enumerator_next()` succeeds, then any further internal errors (other than `cancellable` being triggered) will be ignored.

`enumerator` : | a GSocketAddressEnumerator
`cancellable` : | optional GCancellable object, `NULL` to ignore.
`error` : | a GError.
Returns : | a GSocketAddress (owned by the caller), or `NULL` on error (in which case *`error` will be set) or if there are no more addresses.

### g_socket_address_enumerator_next_async ()

    void                g_socket_address_enumerator_next_async
                                                            (GSocketAddressEnumerator *enumerator,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously retrieves the next GSocketAddress from `enumerator` and then calls `callback`, which must call `g_socket_address_enumerator_next_finish()` to get the result.

`enumerator` : | a GSocketAddressEnumerator
`cancellable` : | optional GCancellable object, `NULL` to ignore.
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | the data to pass to callback function

### g_socket_address_enumerator_next_finish ()

    GSocketAddress *    g_socket_address_enumerator_next_finish
                                                            (GSocketAddressEnumerator *enumerator,
                                                             GAsyncResult *result,
                                                             GError **error);

Retrieves the result of a completed call to `g_socket_address_enumerator_next_async()`. See `g_socket_address_enumerator_next()` for more information about error handling.

`enumerator` : | a GSocketAddressEnumerator
`result` : | a GAsyncResult
`error` : | a GError
Returns : | a GSocketAddress (owned by the caller), or `NULL` on error (in which case *`error` will be set) or if there are no more addresses.