![]() | ![]() | ![]() | GNetwork Library Manual | ![]() |
---|
IP Addresses — Utilities for handling IP addresses.
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)
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.
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_0 | reserved by the specification. |
GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_NODE_LOCAL | only sent to the localhost. |
GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_LINK_LOCAL | only sent across one connection. |
GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_SITE_LOCAL | only sent throughout the location. |
GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_ORGANIZATION_LOCAL | only sent throughout the organization. |
GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_GLOBAL | sent globally to everyone. |
GNETWORK_IP_ADDRESS_MULTICAST_SCOPE_RESERVED_F | reserved by the specification. |
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_TRANSIENT | the multicast address is not permanent. |
union GNetworkIpAddress { guint8 addr8[16]; guint16 addr16[8]; guint32 addr32[4]; guint64 addr64[2]; };
A 128-bit unsigned integer in network byte order.
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
#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. |
#define GNETWORK_IP_ADDRESS_INIT
A static initialization macro, for use when declaring an IP address statically:
GNetworkIpAddress address = GNETWORK_IP_ADDRESS_INIT;
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
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.
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
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
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
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
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
#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. |
#define gnetwork_ip_address_is_address(addr)
Checks if addr contains a valid IP host address.
addr : | a pointer to the GNetworkIpAddress to check. |
#define gnetwork_ip_address_is_network(addr)
Checks if addr contains a valid IP network address.
addr : | a pointer to the GNetworkIpAddress to check. |
#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. |
#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. |
#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. |
#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. |
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. |
#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. |
#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. |
#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. |
#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. |
#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. |
#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. |
#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. |
#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. |
#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. |
<< Error Reporting | SSL Certificates >> |