InetAddr

InetAddr — Internet Address

Synopsis




            GInetAddr;
GInetAddr*  gnet_inetaddr_new               (const gchar *hostname,
                                             gint port);
typedef     GInetAddrNewAsyncID;
void        (*GInetAddrNewAsyncFunc)        (GInetAddr *inetaddr,
                                             gpointer data);
GInetAddrNewAsyncID gnet_inetaddr_new_async (const gchar *hostname,
                                             gint port,
                                             GInetAddrNewAsyncFunc func,
                                             gpointer data);
void        gnet_inetaddr_new_async_cancel  (GInetAddrNewAsyncID id);
GList*      gnet_inetaddr_new_list          (const gchar *hostname,
                                             gint port);
void        gnet_inetaddr_delete_list       (GList *list);
typedef     GInetAddrNewListAsyncID;
void        (*GInetAddrNewListAsyncFunc)    (GList *list,
                                             gpointer data);
GInetAddrNewListAsyncID gnet_inetaddr_new_list_async
                                            (const gchar *hostname,
                                             gint port,
                                             GInetAddrNewListAsyncFunc func,
                                             gpointer data);
void        gnet_inetaddr_new_list_async_cancel
                                            (GInetAddrNewListAsyncID id);
GInetAddr*  gnet_inetaddr_new_nonblock      (const gchar *hostname,
                                             gint port);
GInetAddr*  gnet_inetaddr_new_bytes         (const gchar *bytes,
                                             const guint length);
GInetAddr*  gnet_inetaddr_clone             (const GInetAddr *inetaddr);
void        gnet_inetaddr_delete            (GInetAddr *inetaddr);
void        gnet_inetaddr_ref               (GInetAddr *inetaddr);
void        gnet_inetaddr_unref             (GInetAddr *inetaddr);
gchar*      gnet_inetaddr_get_name          (GInetAddr *inetaddr);
gchar*      gnet_inetaddr_get_name_nonblock (GInetAddr *inetaddr);
typedef     GInetAddrGetNameAsyncID;
void        (*GInetAddrGetNameAsyncFunc)    (gchar *hostname,
                                             gpointer data);
GInetAddrGetNameAsyncID gnet_inetaddr_get_name_async
                                            (GInetAddr *inetaddr,
                                             GInetAddrGetNameAsyncFunc func,
                                             gpointer data);
void        gnet_inetaddr_get_name_async_cancel
                                            (GInetAddrGetNameAsyncID id);
#define     GNET_INETADDR_MAX_LEN
gint        gnet_inetaddr_get_length        (const GInetAddr *inetaddr);
void        gnet_inetaddr_get_bytes         (const GInetAddr *inetaddr,
                                             gchar *buffer);
void        gnet_inetaddr_set_bytes         (GInetAddr *inetaddr,
                                             const gchar *bytes,
                                             gint length);
gchar*      gnet_inetaddr_get_canonical_name
                                            (const GInetAddr *inetaddr);
gint        gnet_inetaddr_get_port          (const GInetAddr *inetaddr);
void        gnet_inetaddr_set_port          (const GInetAddr *inetaddr,
                                             gint port);
gboolean    gnet_inetaddr_is_canonical      (const gchar *hostname);
gboolean    gnet_inetaddr_is_internet       (const GInetAddr *inetaddr);
gboolean    gnet_inetaddr_is_private        (const GInetAddr *inetaddr);
gboolean    gnet_inetaddr_is_reserved       (const GInetAddr *inetaddr);
gboolean    gnet_inetaddr_is_loopback       (const GInetAddr *inetaddr);
gboolean    gnet_inetaddr_is_multicast      (const GInetAddr *inetaddr);
gboolean    gnet_inetaddr_is_broadcast      (const GInetAddr *inetaddr);
gboolean    gnet_inetaddr_is_ipv4           (const GInetAddr *inetaddr);
gboolean    gnet_inetaddr_is_ipv6           (const GInetAddr *inetaddr);
guint       gnet_inetaddr_hash              (gconstpointer p);
gboolean    gnet_inetaddr_equal             (gconstpointer p1,
                                             gconstpointer p2);
gboolean    gnet_inetaddr_noport_equal      (gconstpointer p1,
                                             gconstpointer p2);
gchar*      gnet_inetaddr_get_host_name     (void);
GInetAddr*  gnet_inetaddr_get_host_addr     (void);
GInetAddr*  gnet_inetaddr_autodetect_internet_interface
                                            (void);
GInetAddr*  gnet_inetaddr_get_interface_to  (const GInetAddr *inetaddr);
GInetAddr*  gnet_inetaddr_get_internet_interface
                                            (void);
gboolean    gnet_inetaddr_is_internet_domainname
                                            (const gchar *name);
GList*      gnet_inetaddr_list_interfaces   (void);

Description

A GInetAddr represents an internet address. This module provides functions for making DNS and reverse DNS lookups (blocking and asynchronously) and for working with GInetAddr's.

Create a GInetAddr by calling gnet_inetaddr_new(). This function will perform a DNS lookup and creates a GInetAddr representing the address. This function blocks. The function gnet_inetaddr_new_async() performs the lookup asynchronously and calls a callback with the GInetAddr when the lookup completes. An asynchronous lookup can be canceled by calling gnet_inetaddr_new_async_cancel().

Technically a DNS lookup can map a name to several addresses. Use gnet_inetaddr_new_list() or gnet_inetaddr_new_list_async() to get this list. Use gnet_inetaddr_delete_list() to delete the list.

This module can also make reverse DNS lookups (i.e., map an address to a hostname). Call gnet_inetaddr_get_name() to get the hostname from an address. This function blocks. Its asynchronous counterpart is gnet_inetadr_get_name_async(). To get the canonical name, or dotted decimal address, call gnet_inetaddr_get_canonical_name().

To get the host's address, call gnet_inetaddr_gethostaddr(). This creates a GInetAddr by performing a DNS lookup on the host's name. To get the list of all the host's interfaces, call gnet_inetaddr_list_interfaces(). The function gnet_inetaddr_autodetect_internet_interface() uses this function and heuristics to find an interface connected to the internet. This can be used to automatically configure peer-to-peer applications.

Details

GInetAddr

typedef struct _GInetAddr GInetAddr;

GInetAddr is an internet address.


gnet_inetaddr_new ()

GInetAddr*  gnet_inetaddr_new               (const gchar *hostname,
                                             gint port);

Creates a GInetAddr from a host name and port. This function makes a DNS lookup on the host name so it may block. The host name may resolve to multiple addresses. If this occurs, the first address in the list is returned. Use gnet_inetaddr_new_list() to get the complete list.

hostname : host name
port : port number (0 if the port doesn't matter)
Returns : a new GInetAddr; NULL on error.

GInetAddrNewAsyncID

typedef gpointer GInetAddrNewAsyncID;

ID of an asynchronous GInetAddr creation/lookup started with gnet_inetaddr_new_async(). The creation can be canceled by calling gnet_inetaddr_new_async_cancel() with the ID.


GInetAddrNewAsyncFunc ()

void        (*GInetAddrNewAsyncFunc)        (GInetAddr *inetaddr,
                                             gpointer data);

Callback for gnet_inetaddr_new_async(). Callee owns the address. The address will be NULL if the lookup failed.

inetaddr : InetAddr that was looked up (callee owned)
data : User data

gnet_inetaddr_new_async ()

GInetAddrNewAsyncID gnet_inetaddr_new_async (const gchar *hostname,
                                             gint port,
                                             GInetAddrNewAsyncFunc func,
                                             gpointer data);

Asynchronously creates a GInetAddr from a host name and port. The callback is called once the GInetAddr is created or an error occurs during lookup. The callback will not be called during the call to this function.

See gnet_inetaddr_new_list_async() for implementation notes.

hostname : host name
port : port number (0 if the port doesn't matter)
func : callback function
data : data to pass to func on the callback
Returns : the ID of the lookup; NULL on failure. The ID can be used with gnet_inetaddr_new_async_cancel() to cancel the lookup.

gnet_inetaddr_new_async_cancel ()

void        gnet_inetaddr_new_async_cancel  (GInetAddrNewAsyncID id);

Cancels an asynchronous GInetAddr creation that was started with gnet_inetaddr_new_async().

id : ID of the lookup

gnet_inetaddr_new_list ()

GList*      gnet_inetaddr_new_list          (const gchar *hostname,
                                             gint port);

Creates a GList of GInetAddr's from a host name and port. This function makes a DNS lookup on the host name so it may block.

hostname : host name
port : port number (0 if the port doesn't matter)
Returns : a GList of GInetAddr's; NULL on error.

gnet_inetaddr_delete_list ()

void        gnet_inetaddr_delete_list       (GList *list);

Deletes a GList of GInetAddr's.

list : GList of GInetAddr's

GInetAddrNewListAsyncID

typedef gpointer GInetAddrNewListAsyncID;

ID of an asynchronous GInetAddr list creation/lookup started with gnet_inetaddr_new_list_async(). The creation can be canceled by calling gnet_inetaddr_new_list_async_cancel() with the ID.


GInetAddrNewListAsyncFunc ()

void        (*GInetAddrNewListAsyncFunc)    (GList *list,
                                             gpointer data);

Callback for gnet_inetaddr_new_list_async(). Callee owns the list of GInetAddrs. The list is NULL if the lookup failed.

list : List of GInetAddr's (callee owned)
data : User data

gnet_inetaddr_new_list_async ()

GInetAddrNewListAsyncID gnet_inetaddr_new_list_async
                                            (const gchar *hostname,
                                             gint port,
                                             GInetAddrNewListAsyncFunc func,
                                             gpointer data);

Asynchronously creates a GList of GInetAddr's from a host name and port. The callback is called once the list is created or an error occurs during lookup. The callback will not be called during the call to gnet_inetaddr_new_list_async(). The list passed in the callback is callee owned.

The Unix version creates a pthread thread which does the lookup. If pthreads aren't available, it forks and does the lookup. Forking can be slow or even fail when using operating systems that copy the entire process when forking.

If you need to lookup hundreds of addresses, we recommend calling g_main_iteration(FALSE) between calls. This will help prevent an explosion of threads or processes.

If you need a more robust library for Unix, look at GNU ADNS. GNU ADNS is under the GNU GPL. This library does not use threads or processes.

The Windows version is molded after the Unix pthread version.

hostname : host name
port : port number (0 if the port doesn't matter)
func : callback function
data : data to pass to func on the callback
Returns : the ID of the lookup; NULL on failure. The ID can be used with gnet_inetaddr_new_list_async_cancel() to cancel the lookup.

gnet_inetaddr_new_list_async_cancel ()

void        gnet_inetaddr_new_list_async_cancel
                                            (GInetAddrNewListAsyncID id);

Cancels an asynchronous GInetAddr list creation that was started with gnet_inetaddr_new_list_async().

id : ID of the lookup

gnet_inetaddr_new_nonblock ()

GInetAddr*  gnet_inetaddr_new_nonblock      (const gchar *hostname,
                                             gint port);

Creates a GInetAddr from a host name and port without blocking. This function does not make a DNS lookup and will fail if creating the address would require a DNS lookup.

hostname : host name
port : port number (0 if the port doesn't matter)
Returns : a new GInetAddr, or NULL if there was a failure or the function would block.

gnet_inetaddr_new_bytes ()

GInetAddr*  gnet_inetaddr_new_bytes         (const gchar *bytes,
                                             const guint length);

Creates a GInetAddr from raw bytes. The bytes should be in network byte order (big endian). There should be 4 bytes if it's an IPv4 address and 16 bytees if it's an IPv6 address. The port is set to 0.

bytes : address in raw bytes
length : length of bytes (4 if IPv4, 16 if IPv6)
Returns : a new GInetAddr, or NULL if there was a failure.

gnet_inetaddr_clone ()

GInetAddr*  gnet_inetaddr_clone             (const GInetAddr *inetaddr);

Copies a GInetAddr.

inetaddr : a GInetAddr
Returns : a copy of inetaddr.

gnet_inetaddr_delete ()

void        gnet_inetaddr_delete            (GInetAddr *inetaddr);

Deletes a GInetAddr.

inetaddr : a GInetAddr

gnet_inetaddr_ref ()

void        gnet_inetaddr_ref               (GInetAddr *inetaddr);

Adds a reference to a GInetAddr.

inetaddr : a GInetAddr

gnet_inetaddr_unref ()

void        gnet_inetaddr_unref             (GInetAddr *inetaddr);

Removes a reference from a GInetAddr. A GInetAddr is deleted when the reference count reaches 0.

inetaddr : a GInetAddr

gnet_inetaddr_get_name ()

gchar*      gnet_inetaddr_get_name          (GInetAddr *inetaddr);

Gets the host name for a GInetAddr. This functions makes a reverse DNS lookup on the address so it may block. The canonical name is returned if the address has no host name.

inetaddr : a GInetAddr
Returns : the host name for the inetaddr; NULL on error.

gnet_inetaddr_get_name_nonblock ()

gchar*      gnet_inetaddr_get_name_nonblock (GInetAddr *inetaddr);

Gets the host name for a GInetAddr. This function does not make a reverse DNS lookup and will fail if getting the name would require a reverse DNS lookup.

inetaddr : a GInetAddr
Returns : the host name for the inetaddr, or NULL if there was an error or it would require blocking.

GInetAddrGetNameAsyncID

typedef gpointer GInetAddrGetNameAsyncID;

ID of an asynchronous InetAddr name lookup started with gnet_inetaddr_get_name_async(). The lookup can be canceled by calling gnet_inetaddr_get_name_async_cancel() with the ID.


GInetAddrGetNameAsyncFunc ()

void        (*GInetAddrGetNameAsyncFunc)    (gchar *hostname,
                                             gpointer data);

Callback for gnet_inetaddr_get_name_async(). Callee owns the name. The name will be NULL if the lookup failed.

hostname : Canonical name of the address (callee owned)
data : User data

gnet_inetaddr_get_name_async ()

GInetAddrGetNameAsyncID gnet_inetaddr_get_name_async
                                            (GInetAddr *inetaddr,
                                             GInetAddrGetNameAsyncFunc func,
                                             gpointer data);

Asynchronously gets the host name for a GInetAddr. The callback is called once the reverse DNS lookup is complete. The call back will not be called during the call to this function.

See gnet_inetaddr_new_list_async() for implementation notes.

inetaddr : a GInetAddr
func : callback function
data : data to pass to func on the callback
Returns : the ID of the lookup; NULL on failure. The ID can be used with gnet_inetaddr_get_name_async_cancel() to cancel the lookup.

gnet_inetaddr_get_name_async_cancel ()

void        gnet_inetaddr_get_name_async_cancel
                                            (GInetAddrGetNameAsyncID id);

Cancels an asynchronous name lookup that was started with gnet_inetaddr_get_name_async().

id : ID of the lookup

GNET_INETADDR_MAX_LEN

#define GNET_INETADDR_MAX_LEN 16

Maximum length of a GInetAddr's address in bytes. This can be used to allocate a buffer large enough for gnet_inetaddr_get_bytes().


gnet_inetaddr_get_length ()

gint        gnet_inetaddr_get_length        (const GInetAddr *inetaddr);

Get the length of a GInetAddr's address in bytes. An IPv4 address is 4 bytes long. An IPv6 address is 16 bytes long.

inetaddr : a GInetAddr
Returns : the length in bytes.

gnet_inetaddr_get_bytes ()

void        gnet_inetaddr_get_bytes         (const GInetAddr *inetaddr,
                                             gchar *buffer);

Get a GInetAddr's address as bytes. buffer should be 4 bytes long for an IPv4 address or 16 bytes long for an IPv6 address. Use GNET_INETADDR_MAX_LEN when allocating a static buffer and gnet_inetaddr_get_length() when allocating a dynamic buffer.

inetaddr : a GInetAddr
buffer : buffer to store address in

gnet_inetaddr_set_bytes ()

void        gnet_inetaddr_set_bytes         (GInetAddr *inetaddr,
                                             const gchar *bytes,
                                             gint length);

Sets the address of a GInetAddr from bytes. buffer will be 4 bytes long for an IPv4 address and 16 bytes long for an IPv6 address.

inetaddr : a GInetAddr
bytes : address in raw bytes
length : length of bytes

gnet_inetaddr_get_canonical_name ()

gchar*      gnet_inetaddr_get_canonical_name
                                            (const GInetAddr *inetaddr);

Gets the canonical name of a GInetAddr. An IPv4 canonical name is a dotted decimal name (e.g., 141.213.8.59). An IPv6 canonical name is a semicoloned hexidecimal name (e.g., 23:de:ad:be:ef).

inetaddr : a GInetAddr
Returns : the canonical name; NULL on error.

gnet_inetaddr_get_port ()

gint        gnet_inetaddr_get_port          (const GInetAddr *inetaddr);

Gets the port number of a GInetAddr.

inetaddr : a GInetAddr
Returns : the port number.

gnet_inetaddr_set_port ()

void        gnet_inetaddr_set_port          (const GInetAddr *inetaddr,
                                             gint port);

Set the port number of a GInetAddr.

inetaddr : a GInetAddr
port : new port number

gnet_inetaddr_is_canonical ()

gboolean    gnet_inetaddr_is_canonical      (const gchar *hostname);

Checks if the host name is in canonical form.

hostname : host name
Returns : TRUE if name is canonical; FALSE otherwise.

gnet_inetaddr_is_internet ()

gboolean    gnet_inetaddr_is_internet       (const GInetAddr *inetaddr);

Checks if a GInetAddr is a sensible internet address. This mean it is not private, reserved, loopback, multicast, or broadcast.

Note that private and loopback address are often valid addresses, so this should only be used to check for general internet connectivity. That is, if the address passes, it is reachable on the internet.

inetaddr : a GInetAddr
Returns : TRUE if the address is an internet address; FALSE otherwise.

gnet_inetaddr_is_private ()

gboolean    gnet_inetaddr_is_private        (const GInetAddr *inetaddr);

Checks if a GInetAddr is an address reserved for private networks. For IPv4, this includes:

10.0.0.0 - 10.255.255.255 (10/8 prefix) 172.16.0.0 - 172.31.255.255 (172.16/12 prefix) 192.168.0.0 - 192.168.255.255 (192.168/16 prefix)

(from RFC 1918. See also draft-manning-dsua-02.txt)

For IPv6, this includes link local addresses (fe80::/64) and site local addresses (fec0::/64).

inetaddr : a GInetAddr
Returns : TRUE if inetaddr is private; FALSE otherwise.

gnet_inetaddr_is_reserved ()

gboolean    gnet_inetaddr_is_reserved       (const GInetAddr *inetaddr);

Checks if a GInetAddr is reserved for some purpose. This excludes addresses reserved for private networks.

For IPv4, we check for: 0.0.0.0/16 (top 16 bits are 0's) Class E (top 5 bits are 11110)

For IPv6, we check for the 00000000 prefix.

inetaddr : a GInetAddr
Returns : TRUE if inetaddr is reserved; FALSE otherwise.

gnet_inetaddr_is_loopback ()

gboolean    gnet_inetaddr_is_loopback       (const GInetAddr *inetaddr);

Checks if a GInetAddr is a loopback address. The IPv4 loopback addresses have the prefix 127.0.0.1/24. The IPv6 loopback address is ::1.

inetaddr : a GInetAddr
Returns : TRUE if inetaddr is a loopback address; FALSE otherwise.

gnet_inetaddr_is_multicast ()

gboolean    gnet_inetaddr_is_multicast      (const GInetAddr *inetaddr);

Checks if a GInetAddr is a multicast address. IPv4 multicast addresses are in the range 224.0.0.0 to 239.255.255.255 (ie, the top four bits are 1110). IPv6 multicast addresses have the prefix FF.

inetaddr : a GInetAddr
Returns : TRUE if inetaddr is a multicast address; FALSE otherwise.

gnet_inetaddr_is_broadcast ()

gboolean    gnet_inetaddr_is_broadcast      (const GInetAddr *inetaddr);

Checks if a GInetAddr is a broadcast address. The broadcast address is 255.255.255.255. (Network broadcast addresses are network dependent.)

inetaddr : a GInetAddr
Returns : TRUE if inetaddr is a broadcast address; FALSE otherwise.

gnet_inetaddr_is_ipv4 ()

gboolean    gnet_inetaddr_is_ipv4           (const GInetAddr *inetaddr);

Checks if a GInetAddr is an IPv4 address.

inetaddr : a GInetAddr
Returns : TRUE if inetaddr is an IPv4 address; FALSE otherwise.

gnet_inetaddr_is_ipv6 ()

gboolean    gnet_inetaddr_is_ipv6           (const GInetAddr *inetaddr);

Check if a GInetAddr is an IPv6 address.

inetaddr : a GInetAddr
Returns : TRUE if inetaddr is an IPv6 address; FALSE otherwise.

gnet_inetaddr_hash ()

guint       gnet_inetaddr_hash              (gconstpointer p);

Creates a hash code for a GInetAddr for use with GHashTable.

p : Pointer to an GInetAddr.
Returns : the hash code for p.

gnet_inetaddr_equal ()

gboolean    gnet_inetaddr_equal             (gconstpointer p1,
                                             gconstpointer p2);

Compares two GInetAddr's for equality. IPv4 and IPv6 addresses are always unequal.

p1 : a GInetAddr.
p2 : another GInetAddr.
Returns : TRUE if they are equal; FALSE otherwise.

gnet_inetaddr_noport_equal ()

gboolean    gnet_inetaddr_noport_equal      (gconstpointer p1,
                                             gconstpointer p2);

Compares two GInetAddr's for equality, but does not compare the port numbers.

p1 : a GInetAddr
p2 : another GInetAddr
Returns : TRUE if they are equal; FALSE otherwise.

gnet_inetaddr_get_host_name ()

gchar*      gnet_inetaddr_get_host_name     (void);

Gets the host's name.

Returns : the name of the host; NULL on error.

gnet_inetaddr_get_host_addr ()

GInetAddr*  gnet_inetaddr_get_host_addr     (void);

Get the host's address.

Returns : the address of the host; NULL on error.

gnet_inetaddr_autodetect_internet_interface ()

GInetAddr*  gnet_inetaddr_autodetect_internet_interface
                                            (void);

Finds an interface likely to be connected to the internet. This function can be used to automatically configure peer-to-peer applications. The function relies on heuristics and does not always work correctly, especially if the host is behind a NAT.

Returns : an address of an internet interface; NULL if it couldn't find one or on error.

gnet_inetaddr_get_interface_to ()

GInetAddr*  gnet_inetaddr_get_interface_to  (const GInetAddr *inetaddr);

Figures out which local interface would be used to send a packet to inetaddr. This works on some systems, but not others. We recommend using gnet_inetaddr_autodetect_internet_interface() to find an Internet interface since it's more likely to work.

inetaddr : a GInetAddr
Returns : the address of an interface used to route packets to inetaddr; NULL if there is no such interface or the system does not support this check.

gnet_inetaddr_get_internet_interface ()

GInetAddr*  gnet_inetaddr_get_internet_interface
                                            (void);

Finds an internet interface. This function finds the first interface that is an internet address. IPv6 policy is followed.

This function does not work on some systems. We recommend using gnet_inetaddr_autodetect_internet_interface(), which performs additional checks.

Returns : the address of an internet interface; NULL if no internet interfaces or on error.

gnet_inetaddr_is_internet_domainname ()

gboolean    gnet_inetaddr_is_internet_domainname
                                            (const gchar *name);

Checks if a name is a sensible internet domain name. This function uses heuristics. It does not use DNS and will not block. For example, "localhost" and "10.10.23.42" are not sensible internet domain names. (10.10.23.42 is a network address, but not accessible to the internet at large.)

name : name
Returns : TRUE if name is a sensible Internet domain name; FALSE otherwise.

gnet_inetaddr_list_interfaces ()

GList*      gnet_inetaddr_list_interfaces   (void);

Gets a list of GInetAddr interfaces's on this host. This list includes all "up" Internet interfaces and the loopback interface, if it exists.

On Windows if you do not have IPv6 installed then this function will return up to 10 interfaces.

This function may not work on some systems.

Returns : A list of GInetAddr's representing available interfaces. The caller should delete the list and the addresses.