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.

GInetAddrNewAsyncID

typedef struct _GInetAddrNewState * 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.

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.

gnet_inetaddr_new_async_full ()

GInetAddrNewAsyncID gnet_inetaddr_new_async_full        (const gchar *hostname,
                                                         gint port,
                                                         GInetAddrNewAsyncFunc func,
                                                         gpointer data,
                                                         GDestroyNotify notify,
                                                         GMainContext *context,
                                                         gint priority);

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.

Since 2.0.8

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().

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.

gnet_inetaddr_delete_list ()

void                gnet_inetaddr_delete_list           (GList *list);

Deletes a GList of GInetAddr's.

GInetAddrNewListAsyncID

typedef struct _GInetAddrNewListState * 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.

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 (meaning that it is your responsibility to free the list and each GInetAddr in the list).

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.

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 GThread version.

gnet_inetaddr_new_list_async_full ()

GInetAddrNewListAsyncID gnet_inetaddr_new_list_async_full
                                                        (const gchar *hostname,
                                                         gint port,
                                                         GInetAddrNewListAsyncFunc func,
                                                         gpointer data,
                                                         GDestroyNotify notify,
                                                         GMainContext *context,
                                                         gint priority);

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 (meaning that it is your responsibility to free the list and each GInetAddr in the list).

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.

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 GThread version.

Since 2.0.8

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().

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.

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.

gnet_inetaddr_clone ()

GInetAddr*          gnet_inetaddr_clone                 (const GInetAddr *inetaddr);

Copies a GInetAddr.

gnet_inetaddr_delete ()

void                gnet_inetaddr_delete                (GInetAddr *inetaddr);

Deletes a GInetAddr.

gnet_inetaddr_ref ()

void                gnet_inetaddr_ref                   (GInetAddr *inetaddr);

Adds a reference to 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.

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.

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.

GInetAddrGetNameAsyncID

typedef struct _GInetAddrReverseAsyncState * 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 (that is: you) owns the name. Free it with g_free() when no longer needed. The name will be NULL if the lookup failed.

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.

gnet_inetaddr_get_name_async_full ()

GInetAddrGetNameAsyncID gnet_inetaddr_get_name_async_full
                                                        (GInetAddr *inetaddr,
                                                         GInetAddrGetNameAsyncFunc func,
                                                         gpointer data,
                                                         GDestroyNotify notify,
                                                         GMainContext *context,
                                                         gint priority);

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

See gnet_inetaddr_new_list_async_full() for implementation notes.

Since 2.0.8

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(). This function should only be called from the application's main thread, ie. the thread in which context the callback delivering the result would be called (In a GTK+/GUI application this would be your normal GUI thread).

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.

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.

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.

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).

gnet_inetaddr_get_port ()

gint                gnet_inetaddr_get_port              (const GInetAddr *inetaddr);

Gets the port number of a GInetAddr.

gnet_inetaddr_set_port ()

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

Set the port number of a GInetAddr.

gnet_inetaddr_is_canonical ()

gboolean            gnet_inetaddr_is_canonical          (const gchar *hostname);

Checks if the host name is in canonical form.

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.

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).

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.

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.

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.

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.)

gnet_inetaddr_is_ipv4 ()

gboolean            gnet_inetaddr_is_ipv4               (const GInetAddr *inetaddr);

Checks if a GInetAddr is an IPv4 address.

gnet_inetaddr_is_ipv6 ()

gboolean            gnet_inetaddr_is_ipv6               (const GInetAddr *inetaddr);

Check if a GInetAddr is an IPv6 address.

gnet_inetaddr_hash ()

guint               gnet_inetaddr_hash                  (gconstpointer p);

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

gnet_inetaddr_equal ()

gboolean            gnet_inetaddr_equal                 (gconstpointer p1,
                                                         gconstpointer p2);

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

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.

gnet_inetaddr_get_host_name ()

gchar*              gnet_inetaddr_get_host_name         (void);

Gets the host's name.

gnet_inetaddr_get_host_addr ()

GInetAddr*          gnet_inetaddr_get_host_addr         (void);

Get the host's address.

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.

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.

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.

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.)

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.