SoupAddress

## SoupAddress SoupAddress — DNS support |

## Synopsis

    #include <libsoup/soup.h>

                        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 user_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);
    gboolean            soup_address_is_resolved            (SoupAddress *addr);

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

    gboolean            soup_address_equal_by_name          (gconstpointer addr1,
                                                             gconstpointer addr2);
    guint               soup_address_hash_by_name           (gconstpointer addr);
    gboolean            soup_address_equal_by_ip            (gconstpointer addr1,
                                                             gconstpointer addr2);
    guint               soup_address_hash_by_ip             (gconstpointer addr);

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

## Object Hierarchy

      GObject
       +----SoupAddress

## Implemented Interfaces

SoupAddress implements GSocketConnectable.

## Properties

      "family"                   SoupAddressFamily     : Read / Write / Construct Only
      "name"                     gchar*                : Read / Write / Construct Only
      "physical"                 gchar*                : Read
      "port"                     gint                  : Read / Write / Construct Only
      "protocol"                 gchar*                : 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.)

Although SoupAddress is still used in some libsoup API's, it should not be used in new code; use GLib's GNetworkAddress or GSocketAddress instead.

## Details

### SoupAddress

    typedef struct _SoupAddress SoupAddress;

### enum SoupAddressFamily

    typedef enum {
    	SOUP_ADDRESS_FAMILY_INVALID = -1,

    	SOUP_ADDRESS_FAMILY_IPV4 = G_SOCKET_FAMILY_IPV4,
    	SOUP_ADDRESS_FAMILY_IPV6 = G_SOCKET_FAMILY_IPV6
    } SoupAddressFamily;

The supported address families.

`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. [allow-none]

### 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 using as a listening SoupSocket.

`family` : | the address family
`port` : | the port number (usually `SOUP_ADDRESS_ANY_PORT`)
Returns : | the new SoupAddress. [allow-none]

### SoupAddressCallback ()

    void                (*SoupAddressCallback)              (SoupAddress *addr,
                                                             guint status,
                                                             gpointer user_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`
`user_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`.

It is safe to call this more than once on a given address, from the same thread, with the same `async_context` (and doing so will not result in redundant DNS queries being made). But it is not safe to call from multiple threads, or with different `async_contexts`, or mixed with calls to `soup_address_resolve_sync()`.

`addr` : | a SoupAddress
`async_context` : | the GMainContext to call `callback` from. [allow-none]
`cancellable` : | a GCancellable object, or `NULL`
`callback` : | callback to call with the result. [scope async]
`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`.

It is safe to call this more than once, even from different threads, but it is not safe to mix calls to `soup_address_resolve_sync()` with calls to `soup_address_resolve_async()` on the same address.

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

### soup_address_is_resolved ()

    gboolean            soup_address_is_resolved            (SoupAddress *addr);

Tests if `addr` has already been resolved. Unlike the other SoupAddress "get" methods, this is safe to call when `addr` might be being resolved in another thread.

`addr` : | a SoupAddress
Returns : | `TRUE` if `addr` has been resolved.

### soup_address_get_name ()

    const char *        soup_address_get_name               (SoupAddress *addr);

Returns the hostname associated with `addr`.

This method is not thread-safe; if you call it while `addr` is being resolved in another thread, it may return garbage. You can use `soup_address_is_resolved()` to safely test whether or not an address is resolved before fetching its name or address.

`addr` : | a SoupAddress
Returns : | the hostname, or `NULL` if it is not known. [allow-none]

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

This method is not thread-safe; if you call it while `addr` is being resolved in another thread, it may return garbage. You can use `soup_address_is_resolved()` to safely test whether or not an address is resolved before fetching its name or address.

`addr` : | a SoupAddress
`len` : | return location for sockaddr length
Returns : | the sockaddr, or `NULL`. [allow-none][transfer none]

### soup_address_get_gsockaddr ()

    GSocketAddress *    soup_address_get_gsockaddr          (SoupAddress *addr);

Creates a new GSocketAddress corresponding to `addr` (which is assumed to only have one socket address associated with it).

`addr` : | a SoupAddress
Returns : | a new GSocketAddress. [transfer full]

Since 2.32

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

This method is not thread-safe; if you call it while `addr` is being resolved in another thread, it may return garbage. You can use `soup_address_is_resolved()` to safely test whether or not an address is resolved before fetching its name or address.

`addr` : | a SoupAddress
Returns : | the physical address, or `NULL`. [allow-none]

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

    gboolean            soup_address_equal_by_name          (gconstpointer addr1,
                                                             gconstpointer addr2);

Tests if `addr1` and `addr2` have the same "name". This method can be used with `soup_address_hash_by_name()` to create a GHashTable that hashes on address "names".

Comparing by name normally means comparing the addresses by their hostnames. But if the address was originally created using an IP address literal, then it will be compared by that instead.

In particular, if "www.example.com" has the IP address 10.0.0.1, and `addr1` was created with the name "www.example.com" and `addr2` was created with the name "10.0.0.1", then they will compare as unequal for purposes of `soup_address_equal_by_name()`.

This would be used to distinguish hosts in situations where different virtual hosts on the same IP address should be considered different. Eg, for purposes of HTTP authentication or cookies, two hosts with the same IP address but different names are considered to be different hosts.

See also `soup_address_equal_by_ip()`, which compares by IP address rather than by name.

`addr1` : | a SoupAddress with a resolved name. [type Soup.Address]
`addr2` : | another SoupAddress with a resolved name. [type Soup.Address]
Returns : | whether or not `addr1` and `addr2` have the same name

Since 2.26

### soup_address_hash_by_name ()

    guint               soup_address_hash_by_name           (gconstpointer addr);

A hash function (for GHashTable) that corresponds to `soup_address_equal_by_name()`, qv

`addr` : | a SoupAddress. [type Soup.Address]
Returns : | the named-based hash value for `addr`.

Since 2.26

### soup_address_equal_by_ip ()

    gboolean            soup_address_equal_by_ip            (gconstpointer addr1,
                                                             gconstpointer addr2);

Tests if `addr1` and `addr2` have the same IP address. This method can be used with `soup_address_hash_by_ip()` to create a GHashTable that hashes on IP address.

This would be used to distinguish hosts in situations where different virtual hosts on the same IP address should be considered the same. Eg, if "www.example.com" and "www.example.net" have the same IP address, then a single connection can be used to talk to either of them.

See also `soup_address_equal_by_name()`, which compares by name rather than by IP address.

`addr1` : | a SoupAddress with a resolved IP address. [type Soup.Address]
`addr2` : | another SoupAddress with a resolved IP address. [type Soup.Address]
Returns : | whether or not `addr1` and `addr2` have the same IP address.

Since 2.26

### soup_address_hash_by_ip ()

    guint               soup_address_hash_by_ip             (gconstpointer addr);

A hash function (for GHashTable) that corresponds to `soup_address_equal_by_ip()`, qv

`addr` : | a SoupAddress. [type Soup.Address]
Returns : | the IP-based hash value for `addr`.

Since 2.26

### SOUP_ADDRESS_FAMILY

    #define SOUP_ADDRESS_FAMILY   "family"

Alias for the "family" property. (The SoupAddressFamily for this address.)

### SOUP_ADDRESS_NAME

    #define SOUP_ADDRESS_NAME     "name"

Alias for the "name" property. (The hostname for this address.)

### SOUP_ADDRESS_PHYSICAL

    #define SOUP_ADDRESS_PHYSICAL "physical"

An alias for the "physical" property. (The stringified IP address for this address.)

### SOUP_ADDRESS_PORT

    #define SOUP_ADDRESS_PORT     "port"

An alias for the "port" property. (The port for this address.)

### SOUP_ADDRESS_SOCKADDR

    #define SOUP_ADDRESS_SOCKADDR "sockaddr"

An alias for the "sockaddr" property. (A pointer to the struct sockaddr for this address.)

### SOUP_ADDRESS_PROTOCOL

    #define SOUP_ADDRESS_PROTOCOL "protocol"

Alias for the "protocol" property. (The URI scheme used with this address.)

## 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"                     gchar*                : Read / Write / Construct Only

Hostname for this address.

Default value: NULL

### The `"physical"` property

      "physical"                 gchar*                : 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 `"protocol"` property

      "protocol"                 gchar*                : Read / Write / Construct Only

URI scheme for this address.

Default value: NULL

### The `"sockaddr"` property

      "sockaddr"                 gpointer              : Read / Write / Construct Only

struct sockaddr for this address.