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 ()
GSocketAddress * | g_socket_address_enumerator_next ()
void | g_socket_address_enumerator_next_async ()
GSocketAddress * | g_socket_address_enumerator_next_finish ()

## Properties

GSocketConnectable * | connectable | Read / Write / Construct Only
guint | default-port | Read / Write / Construct Only
GProxyResolver * | proxy-resolver | Read / Write / Construct
gchar * | uri | Read / Write / Construct Only

## Types and Values

| GSocketConnectable
struct | GSocketConnectableIface
| GSocketAddressEnumerator
| GProxyAddressEnumerator

## Object Hierarchy

        GInterface
        ╰── GSocketConnectable
        GObject
        ╰── GSocketAddressEnumerator
            ╰── GProxyAddressEnumerator

## Prerequisites

GSocketConnectable requires GObject.

## Known Implementations

GSocketConnectable is implemented by GInetSocketAddress, 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 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()`.

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

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

#### Parameters

enumerator | a GSocketAddressEnumerator |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
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.

#### Parameters

enumerator | a GSocketAddressEnumerator |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
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.

#### Parameters

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]

## Types and Values

### GSocketConnectable

    typedef struct _GSocketConnectable GSocketConnectable;

Interface for objects that contain or generate GSocketAddress<!-- -->es.

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

### GSocketAddressEnumerator

    typedef struct _GSocketAddressEnumerator GSocketAddressEnumerator;

Enumerator type for objects that contain or generate GSocketAddress<!-- -->es.

### GProxyAddressEnumerator

    typedef struct _GProxyAddressEnumerator GProxyAddressEnumerator;

A subclass of GSocketAddressEnumerator that takes another address enumerator and wraps its results in GProxyAddress<!-- -->es as directed by the default GProxyResolver.

## Property Details

### The `“connectable”` property

      “connectable”              GSocketConnectable *

The connectable being enumerated.

Flags: Read / Write / Construct Only

### The `“default-port”` property

      “default-port”             guint

The default port to use if “uri” does not specify one.

Flags: Read / Write / Construct Only

Allowed values: <= 65535

Default value: 0

Since: 2.38

### The `“proxy-resolver”` property

      “proxy-resolver”           GProxyResolver *

The proxy resolver to use.

Flags: Read / Write / Construct

Since: 2.36

### The `“uri”` property

      “uri”                      gchar *

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

Flags: Read / Write / Construct Only

Default value: NULL