IP Addresses

IP Addresses — Utilities for handling IP addresses.

Synopsis




enum        GNetworkIpAddressMulticastScope;
enum        GNetworkIpAddressMulticastFlags;
union       GNetworkIpAddress;
GNetworkIpAddress* gnetwork_ip_address_new  (const gchar *str);
#define     gnetwork_ip_address_init        (addr)
#define     GNETWORK_IP_ADDRESS_INIT
gchar*      gnetwork_ip_address_to_string   (const GNetworkIpAddress *address);
gboolean    gnetwork_ip_address_set_from_string
                                            (GNetworkIpAddress *address,
                                             const gchar *str);
gboolean    gnetwork_str_is_ip_address      (const gchar *str);
GNetworkIpAddress* gnetwork_ip_address_dup  (const GNetworkIpAddress *address);
guint       gnetwork_ip_address_hash        (gconstpointer address);
gboolean    gnetwork_ip_address_equal       (gconstpointer address1,
                                             gconstpointer address2);
gint        gnetwork_ip_address_collate     (const GNetworkIpAddress *address1,
                                             const GNetworkIpAddress *address2);
#define     gnetwork_ip_address_is_valid    (addr)
#define     gnetwork_ip_address_is_address  (addr)
#define     gnetwork_ip_address_is_network  (addr)
#define     gnetwork_ip_address_is_multicast(addr)
#define     gnetwork_ip_address_get_multicast_scope(addr)
#define     gnetwork_ip_address_get_multicast_flags(addr)
#define     gnetwork_ip_address_is_ipv4     (addr)
void        gnetwork_ip_address_set_ipv4    (GNetworkIpAddress *address,
                                             guint32 ip);
#define     gnetwork_ip_address_get_ipv4    (addr)
#define     gnetwork_ip_address_set8        (addr,pos,val)
#define     gnetwork_ip_address_get8        (addr,pos)
#define     gnetwork_ip_address_set16       (addr,pos,val)
#define     gnetwork_ip_address_get16       (addr,pos)
#define     gnetwork_ip_address_set32       (addr,pos,val)
#define     gnetwork_ip_address_get32       (addr,pos)
#define     gnetwork_ip_address_set64       (addr,pos,val)
#define     gnetwork_ip_address_get64       (addr,pos)

Description

In the GNetwork library, "IP address" means "IPv6 address". However, IPv6 addressing is not well known (at least, I didn't know it before I wrote this code), so a short explanation is in order.

An IPv6 address is a 128-bit (16-byte) integer in network (big-endian) byte-order. What this means is that the 16 bytes of an IP address are arranged such that the "larger" binary digits come first. Older IPv4 addresses are 32-bit (4-byte) integers stored in the same arrangement.

Because IPv4 addresses are smaller than IPv6 addresses, and in the same order, a special IPv4-mapped address type exists. The byte order looks something like this:

[ 0 | 0 ] [ 0 | 0 ] [ 0 | 0 ] [ 0 | 0 ] [ 0 | 0 ] [255|255] [127| 0 ] [ 0 | 1 ]

There is also an IPv4-compatible address, which looks like this (all the bytes are zeroes except the IPv4 address):

[ 0 | 0 ] [ 0 | 0 ] [ 0 | 0 ] [ 0 | 0 ] [ 0 | 0 ] [ 0 | 0 ] [127| 0 ] [ 0 | 1 ]

GNetwork and the IPv4 utilities below read and understands both, but will always write the IPv4-mapped form.

Details

enum GNetworkIpAddressMulticastScope

typedef enum /* <prefix=GNETWORK_IP_ADDRESS_MULTICAST_SCOPE> */
{
  GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_RESERVED_0 = 0,
  GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_NODE_LOCAL = 0x1,
  GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_LINK_LOCAL = 0x2,
  GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_SITE_LOCAL = 0x5,
  GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_ORGANIZATION_LOCAL = 0x8,
  GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_GLOBAL = 0xE,
  GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_RESERVED_F = 0xF
}
GNetworkIpAddressMulticastScope;

An enumeration of scopes that an IP multicast address can have. A multicast scope is the number of bytes to use for the range this multicast should be sent, 0x1 (1) to 0xE (14).

GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_RESERVED_0reserved by the specification.
GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_NODE_LOCALonly sent to the localhost.
GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_LINK_LOCALonly sent across one connection.
GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_SITE_LOCALonly sent throughout the location.
GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_ORGANIZATION_LOCALonly sent throughout the organization.
GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_GLOBALsent globally to everyone.
GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_RESERVED_Freserved by the specification.

enum GNetworkIpAddressMulticastFlags

typedef enum /* <flags,prefix=GNETWORK_IP_ADDRESS_MULTICAST> */
{
  GNETWORK_IP_ADDRESS_MULTICAST_IS_TRANSIENT = 0x1
}
GNetworkIpAddressMulticastFlags;

An enumeration of bitwise flags a multicast address can have set.

GNETWORK_IP_ADDRESS_MULTICAST_IS_TRANSIENTthe multicast address is not permanent.

union GNetworkIpAddress

union GNetworkIpAddress
{
  guint8 addr8[16];
  guint16 addr16[8];
  guint32 addr32[4];
  guint64 addr64[2];
};

A 128-bit unsigned integer in network byte order.


gnetwork_ip_address_new ()

GNetworkIpAddress* gnetwork_ip_address_new  (const gchar *str);

Creates a new IP address based on the data in str. If str is NULL, a zeroed address structure will be returned. The returned data should be freed with g_free() when no longer needed.

str : the string representation of an IP address.
Returns : a new GNetworkIpAddress structure for str.

Since 1.0


gnetwork_ip_address_init()

#define     gnetwork_ip_address_init(addr)

Initializes the address in addr to all zeroes (the invalid address).

addr :a pointer to the address to initialize.

GNETWORK_IP_ADDRESS_INIT

#define     GNETWORK_IP_ADDRESS_INIT

A static initialization macro, for use when declaring an IP address statically:

GNetworkIpAddress address = GNETWORK_IP_ADDRESS_INIT;


gnetwork_ip_address_to_string ()

gchar*      gnetwork_ip_address_to_string   (const GNetworkIpAddress *address);

Creates a string representation of the IP address in address. The returned value should be freed with g_free() when no longer needed.

address : the address to examine.
Returns : the string representation of address.

Since 1.0


gnetwork_ip_address_set_from_string ()

gboolean    gnetwork_ip_address_set_from_string
                                            (GNetworkIpAddress *address,
                                             const gchar *str);

Overwrites the existing IP address in address using the string data in str. If str is not a valid IP address string, address will be set to the invalid address (all 0s), and the function will return FALSE. str may be in IPv4 ("127.0.0.1"), IPv6 ("::1"), or IPv4-compatable IPv6 format ("::127.0.0.1").

address : the address to modify.
str : the new IP address in string format.
Returns : TRUE or FALSE, depending on whether str was a valid IP address string.

Since 1.0.


gnetwork_str_is_ip_address ()

gboolean    gnetwork_str_is_ip_address      (const gchar *str);

Checks if str contains a valid IP address string (in either IPv6 or IPv4 format). NULL and empty strings are considered invalid addresses.

str : the character string to check, or NULL.
Returns : TRUE or FALSE.

Since 1.0


gnetwork_ip_address_dup ()

GNetworkIpAddress* gnetwork_ip_address_dup  (const GNetworkIpAddress *address);

Creates a copy of the IP address in address. The returned value should be freed with g_free() when no longer needed.

address : a pointer to the address to duplicate.
Returns : a copy of address.

Since 1.0


gnetwork_ip_address_hash ()

guint       gnetwork_ip_address_hash        (gconstpointer address);

Computes a hash value for the IP address in address.

address : a pointer to the address to hash.
Returns : the hash of address.

Since 1.0


gnetwork_ip_address_equal ()

gboolean    gnetwork_ip_address_equal       (gconstpointer address1,
                                             gconstpointer address2);

Tests the equality of address1 and address2. This is a GEqualFunc, so it can be used straight-away in a GHashTable.

address1 : a pointer to the first address to test.
address2 : a pointer to the second address to test.
Returns : TRUE of address1 equals address2, FALSE if it does not.

Since 1.0


gnetwork_ip_address_collate ()

gint        gnetwork_ip_address_collate     (const GNetworkIpAddress *address1,
                                             const GNetworkIpAddress *address2);

Compares address1 and address2 for sorting.

address1 : a pointer to the first address to test.
address2 : a pointer to the second address to test.
Returns : -1 if address1 should be sorted first, 1 if address2 should be sorted first, and 0 if both addresses are equal.

Since 1.0


gnetwork_ip_address_is_valid()

#define     gnetwork_ip_address_is_valid(addr)

Checks to see if addr contains a valid IP host or network address.

addr :a pointer to the GNetworkIpAddress to check.

gnetwork_ip_address_is_address()

#define     gnetwork_ip_address_is_address(addr)

Checks if addr contains a valid IP host address.

addr :a pointer to the GNetworkIpAddress to check.

gnetwork_ip_address_is_network()

#define     gnetwork_ip_address_is_network(addr)

Checks if addr contains a valid IP network address.

addr :a pointer to the GNetworkIpAddress to check.

gnetwork_ip_address_is_multicast()

#define     gnetwork_ip_address_is_multicast(addr)

Checks if addr contains a valid IP multicasting address (both IPv6 and IPv4 are checked).

addr :a pointer to the GNetworkIpAddress to check.

gnetwork_ip_address_get_multicast_scope()

#define     gnetwork_ip_address_get_multicast_scope(addr)

Retrieves the GNetworkIpAddressMulticastScope of addr. If addr is NULL or not a valid IPv6 multicasting address, 0 will be returned.

addr :a pointer to the GNetworkIpAddress to examine.

gnetwork_ip_address_get_multicast_flags()

#define     gnetwork_ip_address_get_multicast_flags(addr)

Retrieves the GNetworkIpAddressMulticastFlags of addr. If addr is NULL or not a valid IPv6 multicasting address, 0 will be returned.

addr :a pointer to the GNetworkIpAddress to examine.

gnetwork_ip_address_is_ipv4()

#define     gnetwork_ip_address_is_ipv4(addr)

Checks if addr contains a valid IPv4 address (both IPv4-mapped and IPv4-compatable addresses are checked).

addr :a pointer to the GNetworkIpAddress to examine.

gnetwork_ip_address_set_ipv4 ()

void        gnetwork_ip_address_set_ipv4    (GNetworkIpAddress *address,
                                             guint32 ip);

Modifies addr to hold the host byte-order IPv4 address in ip.

address :
ip :the new IPv4 address.

gnetwork_ip_address_get_ipv4()

#define     gnetwork_ip_address_get_ipv4(addr)

Retrieves the host-byte-order 32-bit IPv4 address from addr. If addr is NULL or not valid, 0 will be returned.

addr :a pointer to the GNetworkIpAddress to examine.

gnetwork_ip_address_set8()

#define     gnetwork_ip_address_set8(addr,pos,val)

Sets the guint8 of addr at pos to val.

addr :a pointer to a GNetworkIpAddress.
pos :the position (0 to 16) to modify.
val :the new value.

gnetwork_ip_address_get8()

#define     gnetwork_ip_address_get8(addr,pos)

Retrieves the host byte-order guint8 from addr at pos.

addr :a pointer to a GNetworkIpAddress.
pos :the position (0 to 15) to retreive.

gnetwork_ip_address_set16()

#define     gnetwork_ip_address_set16(addr,pos,val)

Sets the guint16 of addr at pos to val. val should be in host byte-order.

addr :a pointer to a GNetworkIpAddress.
pos :the position (0 to 7) to modify.
val :the new value.

gnetwork_ip_address_get16()

#define     gnetwork_ip_address_get16(addr,pos)

Retrieves the host byte-order guint16 from addr at pos.

addr :a pointer to a GNetworkIpAddress.
pos :the position (0 to 7) to retreive.

gnetwork_ip_address_set32()

#define     gnetwork_ip_address_set32(addr,pos,val)

Sets the guint32 of addr at pos to val. val should be in host byte-order.

addr :a pointer to a GNetworkIpAddress.
pos :the position (0 to 3) to modify.
val :the new value.

gnetwork_ip_address_get32()

#define     gnetwork_ip_address_get32(addr,pos)

Retrieves the host byte-order guint32 from addr at pos.

addr :a pointer to a GNetworkIpAddress.
pos :the position (0 to 3) to retreive.

gnetwork_ip_address_set64()

#define     gnetwork_ip_address_set64(addr,pos,val)

Sets the guint64 of addr at pos to val. val should be in host byte-order.

addr :a pointer to a GNetworkIpAddress.
pos :the position (0 or 1) to modify.
val :the new value.

gnetwork_ip_address_get64()

#define     gnetwork_ip_address_get64(addr,pos)

Retrieves the host byte-order guint64 from addr at pos.

addr :a pointer to a GNetworkIpAddress.
pos :the position (0 or 1) to retreive.

See Also

RFC 3513: Internet Protocol Version 6 (IPv6) Addressing Architecture