GSocketAddressEnumerator: GIO Reference Manual

## GSocketAddressEnumerator GSocketAddressEnumerator — Enumerator for socket addresses |

## Functions

GSocketAddress * | g_socket_address_enumerator_next ()
void | g_socket_address_enumerator_next_async ()
GSocketAddress * | g_socket_address_enumerator_next_finish ()

## Types and Values

| GSocketAddressEnumerator
struct | GSocketAddressEnumeratorClass

## Object Hierarchy

        GObject
        ╰── GSocketAddressEnumerator
            ╰── GProxyAddressEnumerator

## Includes

    #include <gio/gio.h>

## Description

GSocketAddressEnumerator is an enumerator type for GSocketAddress instances. It is returned by enumeration functions such as `g_socket_connectable_enumerate()`, which returns a GSocketAddressEnumerator to list each GSocketAddress which could be used to connect to that GSocketConnectable.

Enumeration is typically a blocking operation, so the asynchronous methods `g_socket_address_enumerator_next_async()` and `g_socket_address_enumerator_next_finish()` should be used where possible.

Each GSocketAddressEnumerator can only be enumerated once. Once `g_socket_address_enumerator_next()` has returned `NULL`, further enumeration with that GSocketAddressEnumerator is not possible, and it can be unreffed.

## Functions

### 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][nullable]

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

It is an error to call this multiple times before the previous callback has finished.

#### 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][nullable]

## Types and Values

### GSocketAddressEnumerator

    typedef struct _GSocketAddressEnumerator GSocketAddressEnumerator;

Enumerator type for objects that contain or generate GSocketAddress instances.

### struct GSocketAddressEnumeratorClass

    struct GSocketAddressEnumeratorClass {
      /* Virtual Table */

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

      void             (* next_async)  (GSocketAddressEnumerator  *enumerator,
    				    GCancellable              *cancellable,
    				    GAsyncReadyCallback        callback,
    				    gpointer                   user_data);
      GSocketAddress * (* next_finish) (GSocketAddressEnumerator  *enumerator,
    				    GAsyncResult              *result,
    				    GError                   **error);
    };

Class structure for GSocketAddressEnumerator.

#### Members

`next` () | Virtual method for `g_socket_address_enumerator_next()`. |
`next_async` () | Virtual method for `g_socket_address_enumerator_next_async()`. |
`next_finish` () | Virtual method for `g_socket_address_enumerator_next_finish()`. |