## NiceAddress NiceAddress — IP address convenience library |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        NiceAddress;
    #define             NICE_ADDRESS_STRING_LEN
    void                nice_address_init                   (NiceAddress *addr);
    NiceAddress *       nice_address_new                    (void);
    void                nice_address_free                   (NiceAddress *addr);
    NiceAddress *       nice_address_dup                    (const NiceAddress *addr);
    void                nice_address_set_ipv4               (NiceAddress *addr,
                                                             guint32 addr_ipv4);
    void                nice_address_set_ipv6               (NiceAddress *addr,
                                                             const guchar *addr_ipv6);
    void                nice_address_set_port               (NiceAddress *addr,
                                                             guint port);
    guint               nice_address_get_port               (const NiceAddress *addr);
    gboolean            nice_address_set_from_string        (NiceAddress *addr,
                                                             const gchar *str);
    void                nice_address_set_from_sockaddr      (NiceAddress *addr,
                                                             const struct sockaddr *sin);
    void                nice_address_copy_to_sockaddr       (const NiceAddress *addr,
                                                             struct sockaddr *sin);
    gboolean            nice_address_equal                  (const NiceAddress *a,
                                                             const NiceAddress *b);
    void                nice_address_to_string              (const NiceAddress *addr,
                                                             gchar *dst);
    gboolean            nice_address_is_private             (const NiceAddress *addr);
    gboolean            nice_address_is_valid               (const NiceAddress *addr);
    int                 nice_address_ip_version             (const NiceAddress *addr);

## Description

The NiceAddress structure will allow you to easily set/get and modify an IPv4 or IPv6 address in order to communicate with the NiceAgent.

## Details

### NiceAddress

    typedef struct {
      union
      {
        struct sockaddr     addr;
        struct sockaddr_in  ip4;
        struct sockaddr_in6 ip6;
      } s;
    } NiceAddress;

The NiceAddress structure that represents an IPv4 or IPv6 address.

### NICE_ADDRESS_STRING_LEN

    #define NICE_ADDRESS_STRING_LEN INET6_ADDRSTRLEN

The maximum string length representation of an address. When using `nice_address_to_string()` make sure the string has a size of at least `NICE_ADDRESS_STRING_LEN`

### nice_address_init ()

    void                nice_address_init                   (NiceAddress *addr);

Initialize a NiceAddress into an undefined address

`addr` : | The NiceAddress to init

### nice_address_new ()

    NiceAddress *       nice_address_new                    (void);

Create a new NiceAddress with undefined address You must free it with `nice_address_free()`

Returns : | The new NiceAddress

### nice_address_free ()

    void                nice_address_free                   (NiceAddress *addr);

Frees a NiceAddress created with `nice_address_new()` or `nice_address_dup()`

`addr` : | The NiceAddress to free

### nice_address_dup ()

    NiceAddress *       nice_address_dup                    (const NiceAddress *addr);

Creates a new NiceAddress with the same address as `addr`

`addr` : | The NiceAddress to dup
Returns : | The new NiceAddress

### nice_address_set_ipv4 ()

    void                nice_address_set_ipv4               (NiceAddress *addr,
                                                             guint32 addr_ipv4);

Set `addr` to an IPv4 address using the data from `addr_ipv4`

### Note

This function will reset the port to 0, so make sure you call it before `nice_address_set_port()`

`addr` : | The NiceAddress to modify
`addr_ipv4` : | The IPv4 address

### nice_address_set_ipv6 ()

    void                nice_address_set_ipv6               (NiceAddress *addr,
                                                             const guchar *addr_ipv6);

Set `addr` to an IPv6 address using the data from `addr_ipv6`

### Note

This function will reset the port to 0, so make sure you call it before `nice_address_set_port()`

`addr` : | The NiceAddress to modify
`addr_ipv6` : | The IPv6 address

### nice_address_set_port ()

    void                nice_address_set_port               (NiceAddress *addr,
                                                             guint port);

Set the port of `addr` to `port`

`addr` : | The NiceAddress to modify
`port` : | The port to set

### nice_address_get_port ()

    guint               nice_address_get_port               (const NiceAddress *addr);

Retreive the port of `addr`

`addr` : | The NiceAddress to query
Returns : | The port of `addr`

### nice_address_set_from_string ()

    gboolean            nice_address_set_from_string        (NiceAddress *addr,
                                                             const gchar *str);

Sets an IPv4 or IPv6 address from the string `str`

`addr` : | The NiceAddress to modify
`str` : | The string to set
Returns : | `TRUE` if success, `FALSE` on error

### nice_address_set_from_sockaddr ()

    void                nice_address_set_from_sockaddr      (NiceAddress *addr,
                                                             const struct sockaddr *sin);

Sets an IPv4 or IPv6 address from the sockaddr structure `sin`

`addr` : | The NiceAddress to modify
`sin` : | The sockaddr to set

### nice_address_copy_to_sockaddr ()

    void                nice_address_copy_to_sockaddr       (const NiceAddress *addr,
                                                             struct sockaddr *sin);

Fills the sockaddr structure `sin` with the address contained in `addr`

`addr` : | The NiceAddress to query
`sin` : | The sockaddr to fill

### nice_address_equal ()

    gboolean            nice_address_equal                  (const NiceAddress *a,
                                                             const NiceAddress *b);

Compares two NiceAddress structures to see if they contain the same address

`a` : | First NiceAddress to compare
`b` : | Second NiceAddress to compare
Returns : | `TRUE` if `a` and `b` are the same address, `FALSE` if they are different

### nice_address_to_string ()

    void                nice_address_to_string              (const NiceAddress *addr,
                                                             gchar *dst);

Transforms the address `addr` into a human readable string

`addr` : | The NiceAddress to query
`dst` : | The string to fill

### nice_address_is_private ()

    gboolean            nice_address_is_private             (const NiceAddress *addr);

Verifies if the address in `addr` is a private address or not

`addr` : | The NiceAddress to query
Returns : | `TRUE` if `addr` is a private address, `FALSE` otherwise

### nice_address_is_valid ()

    gboolean            nice_address_is_valid               (const NiceAddress *addr);

Validate whether the NiceAddress `addr` is a valid IPv4 or IPv6 address

`addr` : | The NiceAddress to query
Returns : | `TRUE` if `addr` is valid, `FALSE` otherwise

### nice_address_ip_version ()

    int                 nice_address_ip_version             (const NiceAddress *addr);

Returns the IP version of the address

`addr` : | The NiceAddress to query
Returns : | 4 for IPv4, 6 for IPv6 and 0 for undefined address