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 GInetSocketAddress, GNetworkAddress, GNetworkService, GSocketAddress and GUnixSocketAddress.

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.

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.
Generated by GTK-Doc V1.14