SoupAddress

## SoupAddress SoupAddress — DNS support |

## Synopsis

    struct              SoupAddress;
    enum                SoupAddressFamily;
    #define             SOUP_ADDRESS_ANY_PORT
    SoupAddress*        soup_address_new                    (const char *name,
                                                             guint port);
    SoupAddress*        soup_address_new_from_sockaddr      (struct sockaddr *sa,
                                                             int len);
    SoupAddress*        soup_address_new_any                (SoupAddressFamily family,
                                                             guint port);

    void                (*SoupAddressCallback)              (SoupAddress *addr,
                                                             guint status,
                                                             gpointer data);
    void                soup_address_resolve_async          (SoupAddress *addr,
                                                             GMainContext *async_context,
                                                             GCancellable *cancellable,
                                                             SoupAddressCallback callback,
                                                             gpointer user_data);
    guint               soup_address_resolve_sync           (SoupAddress *addr,
                                                             GCancellable *cancellable);

    const char*         soup_address_get_name               (SoupAddress *addr);
    struct sockaddr*    soup_address_get_sockaddr           (SoupAddress *addr,
                                                             int *len);
    const char*         soup_address_get_physical           (SoupAddress *addr);
    guint               soup_address_get_port               (SoupAddress *addr);

    #define             SOUP_ADDRESS_FAMILY
    #define             SOUP_ADDRESS_NAME
    #define             SOUP_ADDRESS_PHYSICAL
    #define             SOUP_ADDRESS_PORT
    #define             SOUP_ADDRESS_SOCKADDR

## Object Hierarchy

      GObject
       +----SoupAddress

## Properties

      "family"                   SoupAddressFamily     : Read / Write / Construct Only
      "name"                     gchararray            : Read / Write / Construct Only
      "physical"                 gchararray            : Read
      "port"                     gint                  : Read / Write / Construct Only
      "sockaddr"                 gpointer              : Read / Write / Construct Only

## Description

SoupAddress represents the address of a TCP connection endpoint: both the IP address and the port. (It is somewhat like an object-oriented version of struct sockaddr.)

If libsoup was built with IPv6 support, SoupAddress will allow both IPv4 and IPv6 addresses.

## Details

### struct SoupAddress

    struct SoupAddress;

### enum SoupAddressFamily

    typedef enum {
    	SOUP_ADDRESS_FAMILY_INVALID = -1,

    	SOUP_ADDRESS_FAMILY_IPV4 = AF_INET,
    	SOUP_ADDRESS_FAMILY_IPV6 = AF_INET6
    } SoupAddressFamily;

The supported address families. Note that the `SOUP_ADDRESS_FAMILY_IPV6` constant is available even if libsoup was built without IPv6 support, but attempting to create an IPv6 address will fail in that case.

`SOUP_ADDRESS_FAMILY_INVALID` | an invalid `SoupAddress`
`SOUP_ADDRESS_FAMILY_IPV4` | an IPv4 address
`SOUP_ADDRESS_FAMILY_IPV6` | an IPv6 address

### SOUP_ADDRESS_ANY_PORT

    #define SOUP_ADDRESS_ANY_PORT 0

This can be passed to any SoupAddress method that expects a port, to indicate that you don't care what port is used.

### soup_address_new ()

    SoupAddress*        soup_address_new                    (const char *name,
                                                             guint port);

Creates a SoupAddress from `name` and `port`. The SoupAddress's IP address may not be available right away; the caller can call `soup_address_resolve_async()` or `soup_address_resolve_sync()` to force a DNS resolution.

`name` : | a hostname or physical address
`port` : | a port number
Returns : | a SoupAddress

### soup_address_new_from_sockaddr ()

    SoupAddress*        soup_address_new_from_sockaddr      (struct sockaddr *sa,
                                                             int len);

Returns a SoupAddress equivalent to `sa` (or `NULL` if `sa`'s address family isn't supported)

`sa` : | a pointer to a sockaddr
`len` : | size of `sa`
Returns : | the new SoupAddress

### soup_address_new_any ()

    SoupAddress*        soup_address_new_any                (SoupAddressFamily family,
                                                             guint port);

Returns a SoupAddress corresponding to the "any" address for `family` (or `NULL` if `family` isn't supported), suitable for passing to `soup_socket_server_new()`.

`family` : | the address family
`port` : | the port number (usually `SOUP_ADDRESS_ANY_PORT`)
Returns : | the new SoupAddress

### SoupAddressCallback ()

    void                (*SoupAddressCallback)              (SoupAddress *addr,
                                                             guint status,
                                                             gpointer data);

The callback function passed to `soup_address_resolve_async()`.

`addr` : | the SoupAddress that was resolved
`status` : | `SOUP_STATUS_OK`, `SOUP_STATUS_CANT_RESOLVE`, or `SOUP_STATUS_CANCELLED`
`data` : | the user data that was passed to `soup_address_resolve_async()`

### soup_address_resolve_async ()

    void                soup_address_resolve_async          (SoupAddress *addr,
                                                             GMainContext *async_context,
                                                             GCancellable *cancellable,
                                                             SoupAddressCallback callback,
                                                             gpointer user_data);

Asynchronously resolves the missing half of `addr` (its IP address if it was created with `soup_address_new()`, or its hostname if it was created with `soup_address_new_from_sockaddr()` or `soup_address_new_any()`.)

If `cancellable` is non-`NULL`, it can be used to cancel the resolution. `callback` will still be invoked in this case, with a status of `SOUP_STATUS_CANCELLED`.

`addr` : | a SoupAddress
`async_context` : | the GMainContext to call `callback` from
`cancellable` : | a GCancellable object, or `NULL`
`callback` : | callback to call with the result
`user_data` : | data for `callback`

### soup_address_resolve_sync ()

    guint               soup_address_resolve_sync           (SoupAddress *addr,
                                                             GCancellable *cancellable);

Synchronously resolves the missing half of `addr`, as with `soup_address_resolve_async()`.

If `cancellable` is non-`NULL`, it can be used to cancel the resolution. `soup_address_resolve_sync()` will then return a status of `SOUP_STATUS_CANCELLED`.

`addr` : | a SoupAddress
`cancellable` : | a GCancellable object, or `NULL`
Returns : | `SOUP_STATUS_OK`, `SOUP_STATUS_CANT_RESOLVE`, or `SOUP_STATUS_CANCELLED`.

### soup_address_get_name ()

    const char*         soup_address_get_name               (SoupAddress *addr);

Returns the hostname associated with `addr`.

`addr` : | a SoupAddress
Returns : | the hostname, or `NULL` if it is not known.

### soup_address_get_sockaddr ()

    struct sockaddr*    soup_address_get_sockaddr           (SoupAddress *addr,
                                                             int *len);

Returns the sockaddr associated with `addr`, with its length in *`len`. If the sockaddr is not yet known, returns `NULL`.

`addr` : | a SoupAddress
`len` : | return location for sockaddr length
Returns : | the sockaddr, or `NULL`

### soup_address_get_physical ()

    const char*         soup_address_get_physical           (SoupAddress *addr);

Returns the physical address associated with `addr` as a string. (Eg, "127.0.0.1"). If the address is not yet known, returns `NULL`.

`addr` : | a SoupAddress
Returns : | the physical address, or `NULL`

### soup_address_get_port ()

    guint               soup_address_get_port               (SoupAddress *addr);

Returns the port associated with `addr`.

`addr` : | a SoupAddress
Returns : | the port

### SOUP_ADDRESS_FAMILY

    #define SOUP_ADDRESS_FAMILY   "family"

### SOUP_ADDRESS_NAME

    #define SOUP_ADDRESS_NAME     "name"

### SOUP_ADDRESS_PHYSICAL

    #define SOUP_ADDRESS_PHYSICAL "physical"

### SOUP_ADDRESS_PORT

    #define SOUP_ADDRESS_PORT     "port"

### SOUP_ADDRESS_SOCKADDR

    #define SOUP_ADDRESS_SOCKADDR "sockaddr"

## Property Details

### The `"family"` property

      "family"                   SoupAddressFamily     : Read / Write / Construct Only

Address family for this address.

Default value: SOUP_ADDRESS_FAMILY_INVALID

### The `"name"` property

      "name"                     gchararray            : Read / Write / Construct Only

Hostname for this address.

Default value: NULL

### The `"physical"` property

      "physical"                 gchararray            : Read

IP address for this address.

Default value: NULL

### The `"port"` property

      "port"                     gint                  : Read / Write / Construct Only

Port for this address.

Allowed values: [G_MAXULONG,65535]

Default value: -1

### The `"sockaddr"` property

      "sockaddr"                 gpointer              : Read / Write / Construct Only

struct sockaddr for this address.