GSocketConnectable

## GSocketConnectable GSocketConnectable — Interface for potential socket endpoints |

## Synopsis

                        GSocketConnectable;
    struct              GSocketConnectableIface;
    GSocketAddressEnumerator * g_socket_connectable_enumerate
                                                            (GSocketConnectable *connectable);
    GSocketAddressEnumerator * g_socket_connectable_proxy_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);

                        GProxyAddressEnumerator;

## Object Hierarchy

      GInterface
       +----GSocketConnectable

      GObject
       +----GSocketAddressEnumerator
             +----GProxyAddressEnumerator

      GObject
       +----GSocketAddressEnumerator
             +----GProxyAddressEnumerator

## Prerequisites

GSocketConnectable requires GObject.

## Known Implementations

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

## Properties

      "connectable"              GSocketConnectable*   : Read / Write / Construct Only
      "uri"                      gchar*                : Read / Write / Construct Only

## 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
    50
    51
    52
    53
    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.

### struct GSocketConnectableIface

    struct GSocketConnectableIface {
      GTypeInterface g_iface;

      /* Virtual Table */

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

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

Provides an interface for returning a GSocketAddressEnumerator and GProxyAddressEnumerator

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

### g_socket_connectable_enumerate ()

    GSocketAddressEnumerator * g_socket_connectable_enumerate
                                                            (GSocketConnectable *connectable);

Creates a GSocketAddressEnumerator for `connectable`.

`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 GProxyAddresses for 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()`.

`connectable` : | a GSocketConnectable
Returns : | a new GSocketAddressEnumerator. [transfer full]

Since 2.26

### 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. [allow-none]
`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. [transfer full]

### 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. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | the data to pass to callback function. [closure]

### 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. [transfer full]

### GProxyAddressEnumerator

    typedef struct _GProxyAddressEnumerator GProxyAddressEnumerator;

A subclass of GSocketAddressEnumerator that takes another address enumerator and wraps its results in GProxyAddresses as directed by the default GProxyResolver.

## Property Details

### The `"connectable"` property

      "connectable"              GSocketConnectable*   : Read / Write / Construct Only

The connectable being enumerated.

### The `"uri"` property

      "uri"                      gchar*                : Read / Write / Construct Only

The destination URI, use none:// for generic socket.

Default value: NULL