GSocketConnectable

GSocketConnectable — Interface for potential socket endpoints

Functions

Properties

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

Types and Values

Object Hierarchy

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

Prerequisites

GSocketConnectable requires GObject.

Known Implementations

GSocketConnectable is implemented by GInetSocketAddress, GNetworkAddress, GNetworkService, GProxyAddress, 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;
    }
}

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

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

Parameters

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.

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

Members

GTypeInterface g_iface;

The parent interface.

 

enumerate ()

Creates a GSocketAddressEnumerator

 

proxy_enumerate ()

Creates a GProxyAddressEnumerator

 

GSocketAddressEnumerator

typedef struct _GSocketAddressEnumerator GSocketAddressEnumerator;

Enumerator type for objects that contain or generate GSocketAddresses.


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 *

The connectable being enumerated.

Flags: Read / Write / Construct Only


The “uri” property

  “uri”                      gchar *

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

Flags: Read / Write / Construct Only

Default value: NULL