Local Interfaces

Local Interfaces — Local interface information.

Synopsis




struct      GNetworkInterfaceInfo;
enum        GNetworkInterfaceFlags;
enum        GNetworkProtocols;
GNetworkInterfaceInfo* gnetwork_interface_get_info
                                            (const gchar *name);
GNetworkInterfaceInfo* gnetwork_interface_get_info_by_address
                                            (const gchar *address);
GSList*     gnetwork_interface_get_all_interfaces
                                            (void);
gchar*      gnetwork_interface_info_get_name
                                            (const GNetworkInterfaceInfo *info);
guint       gnetwork_interface_info_get_index
                                            (const GNetworkInterfaceInfo *info);
GNetworkProtocols gnetwork_interface_info_get_protocols
                                            (const GNetworkInterfaceInfo *info);
gconstpointer gnetwork_interface_info_get_address
                                            (const GNetworkInterfaceInfo *info,
                                             GNetworkProtocols protocol);
gconstpointer gnetwork_interface_info_get_netmask
                                            (const GNetworkInterfaceInfo *info,
                                             GNetworkProtocols protocol);
gconstpointer gnetwork_interface_info_get_broadcast_address
                                            (const GNetworkInterfaceInfo *info,
                                             GNetworkProtocols protocol);
gconstpointer gnetwork_interface_info_get_destination
                                            (const GNetworkInterfaceInfo *info,
                                             GNetworkProtocols protocol);
G_CONST_RETURN GSList* gnetwork_interface_info_get_multicasts
                                            (const GNetworkInterfaceInfo *info,
                                             GNetworkProtocols protocol);
GNetworkInterfaceFlags gnetwork_interface_info_get_flags
                                            (const GNetworkInterfaceInfo *info);
GNetworkInterfaceInfo* gnetwork_interface_info_ref
                                            (GNetworkInterfaceInfo *info);
void        gnetwork_interface_info_unref   (GNetworkInterfaceInfo *info);
gint        gnetwork_interface_info_collate (const GNetworkInterfaceInfo *info1,
                                             const GNetworkInterfaceInfo *info2);

Description

These functions provide a means to allow applications to retrieve information about configured local networking interfaces.

The interface information is static, and provides only a snapshot of the interfaces when the function was called. Typically, if one needs to provide a list of interfaces, one should use gnetwork_interface_get_all_interfaces() to create the list. However, if one only needs data for one interface, gnetwork_interface_get_info() will suffice. When the interface snapshots are no longer needed, then can be unreferenced using gnetwork_interface_info_unref().

Details

struct GNetworkInterfaceInfo

struct GNetworkInterfaceInfo;

An opaque, reference-counted structure representing known information about a particular local interface. This function should be retrieved and examined using the functions below.


enum GNetworkInterfaceFlags

typedef enum /* <flags,prefix=GNETWORK_INTERFACE> */
{
  GNETWORK_INTERFACE_NONE		= 0,

  /* Status */
  GNETWORK_INTERFACE_IS_UP		= 1 << 0,
  GNETWORK_INTERFACE_IS_RUNNING		= 1 << 1,
  GNETWORK_INTERFACE_IS_DEBUGGING	= 1 << 2,

  /* Special Types */
  GNETWORK_INTERFACE_IS_LOOPBACK        = 1 << 3,
  GNETWORK_INTERFACE_IS_POINT_TO_POINT  = 1 << 4,
  GNETWORK_INTERFACE_IS_LOAD_MASTER	= 1 << 5,
  GNETWORK_INTERFACE_IS_LOAD_SLAVE	= 1 << 6,

  /* Capabilities */
  GNETWORK_INTERFACE_CAN_BROADCAST	= 1 << 7,
  GNETWORK_INTERFACE_CAN_MULTICAST	= 1 << 8,
  GNETWORK_INTERFACE_NO_TRAILERS	= 1 << 9,

  GNETWORK_INTERFACE_NO_ARP		= 1 << 10,
  GNETWORK_INTERFACE_CAN_SET_MEDIA	= 1 << 11,
  GNETWORK_INTERFACE_ALTERNATE_LINK	= 1 << 12,
  GNETWORK_INTERFACE_AUTOSELECTED_MEDIA = 1 << 13,

  /* Modes */
  GNETWORK_INTERFACE_RECV_ALL_PACKETS	= 1 << 14,
  GNETWORK_INTERFACE_RECV_ALL_MULTICAST	= 1 << 15
}
GNetworkInterfaceFlags;

A bitwise enumeration of flags can be set on an interface. These correspond to flags defined by the operating system in <net/if.h>.

GNETWORK_INTERFACE_NONEno flags are set.
GNETWORK_INTERFACE_IS_UPthe interface is up.
GNETWORK_INTERFACE_IS_RUNNINGthe interface is running (has resources allocated to it).
GNETWORK_INTERFACE_IS_DEBUGGINGthe interface is in debug mode.
GNETWORK_INTERFACE_IS_LOOPBACKthe interface is a local-only interface.
GNETWORK_INTERFACE_IS_POINT_TO_POINTthe interface is a one-to-one connection.
GNETWORK_INTERFACE_IS_LOAD_MASTERthe interface is the master of a load-balancing network.
GNETWORK_INTERFACE_IS_LOAD_SLAVEthe interface is a slave in a load-balancing network.
GNETWORK_INTERFACE_CAN_BROADCASTthe interface supports broadcasting.
GNETWORK_INTERFACE_CAN_MULTICASTthe interface supports multicasting.
GNETWORK_INTERFACE_NO_TRAILERSthe interface does not support specifying the size of data being used (only useful in very low-level socket programming).
GNETWORK_INTERFACE_NO_ARPthe interface does not support the Address Resolution Protocol.
GNETWORK_INTERFACE_CAN_SET_MEDIAthe interface media type (speed) can be selected.
GNETWORK_INTERFACE_ALTERNATE_LINK
GNETWORK_INTERFACE_AUTOSELECTED_MEDIAthe interface media type (speed) is being automatically selected.
GNETWORK_INTERFACE_RECV_ALL_PACKETSthe interface will inform listeners about all incoming packets.
GNETWORK_INTERFACE_RECV_ALL_MULTICASTthe interface will inform listeners about all incoming multicast packets.

enum GNetworkProtocols

typedef enum
{
  GNETWORK_PROTOCOL_NONE    = 0,
  GNETWORK_PROTOCOL_IPv4    = 1 << 0,
  GNETWORK_PROTOCOL_IPv6    = 1 << 1,
  GNETWORK_PROTOCOL_PACKET  = 1 << 2
}
GNetworkProtocols;

A bitwise enumeration of support protocols for an interface.

GNETWORK_PROTOCOL_NONEno known protocols are supported.
GNETWORK_PROTOCOL_IPv4version 4 of the IP protocol is supported.
GNETWORK_PROTOCOL_IPv6version 6 of the IP protocol is supported.
GNETWORK_PROTOCOL_PACKETthe ethernet protocol is supported.

gnetwork_interface_get_info ()

GNetworkInterfaceInfo* gnetwork_interface_get_info
                                            (const gchar *name);

Retrieves the information for the interface referred to by name. The name should be something like "eth0", "lo", etc.

name : the name of the interface.
Returns : a structure describing a local interface.

Since 1.0


gnetwork_interface_get_info_by_address ()

GNetworkInterfaceInfo* gnetwork_interface_get_info_by_address
                                            (const gchar *address);

Retrieves the GNetworkInterfaceInfo which uses the address in address.

address : a valid address string.
Returns : a list of local interfaces.

Since 1.0


gnetwork_interface_get_all_interfaces ()

GSList*     gnetwork_interface_get_all_interfaces
                                            (void);

Retrieves a list of GNetworkInterfaceInfo structures representing the local interfaces for this host. The returned list and list data should be freed using the following code:

g_slist_foreach (list, (GFunc) gnetwork_interface_info_unref, NULL);
g_slist_free (list);

Returns : a list of local interfaces.

Since 1.0


gnetwork_interface_info_get_name ()

gchar*      gnetwork_interface_info_get_name
                                            (const GNetworkInterfaceInfo *info);

Retrieves the configured name of the interface described by info (e.g. "eth0"). If info is invalid, NULL will be returned.

info : the interface information to examine.
Returns : the name of info, or NULL.

Since 1.0


gnetwork_interface_info_get_index ()

guint       gnetwork_interface_info_get_index
                                            (const GNetworkInterfaceInfo *info);

Retrieves the index of the interface described by info. If info is invalid or the index is unknown, 0 is returned.

info : the interface information to examine.
Returns : the index of interface.

Since 1.0


gnetwork_interface_info_get_protocols ()

GNetworkProtocols gnetwork_interface_info_get_protocols
                                            (const GNetworkInterfaceInfo *info);

Retrieves the protocols used by the interface at info. If info is invalid, or the interface does not support any known protcols, GNETWORK_PROTOCOL_NONE will be returned.

info : the interface information to examine.
Returns : the protocols used by info.

Since 1.0


gnetwork_interface_info_get_address ()

gconstpointer gnetwork_interface_info_get_address
                                            (const GNetworkInterfaceInfo *info,
                                             GNetworkProtocols protocol);

Retrieves the configured protocol address of the interface described by info (e.g. "127.0.0.1" for IPv4, "::1" for IPv6, or "00:00:00:00:00:00" for hardware). If info is invalid, protocol contains more than one flag, or if info does not support protocol, NULL will be returned.

info : the interface information to examine.
protocol : the protocol type to use.
Returns : the protocol address of info, or NULL.

Since 1.0


gnetwork_interface_info_get_netmask ()

gconstpointer gnetwork_interface_info_get_netmask
                                            (const GNetworkInterfaceInfo *info,
                                             GNetworkProtocols protocol);

Retrieves the protocol network mask of the interface described by info (e.g. "255.255.255.255" for IPv4, or "ffff:ffff:ffff:ffff" for IPv6). If info is invalid, NULL will be returned.

info : the interface information to examine.
protocol : the protocol to use.
Returns : the network mask of info, or NULL.

Since 1.0


gnetwork_interface_info_get_broadcast_address ()

gconstpointer gnetwork_interface_info_get_broadcast_address
                                            (const GNetworkInterfaceInfo *info,
                                             GNetworkProtocols protocol);

Retrieves the broadcast address of the interface described by info (e.g. "127.0.0.255" for IPv4 or "00:00:00:00:00:00" for hardware). If info is invalid or is a "point-to-point" interface, or if protocol does not support broadcasting (like IPv6), NULL will be returned.

info : the interface information to examine.
protocol : the protocol type to use.
Returns : the protocol broadcast address of info, or NULL.

Since 1.0


gnetwork_interface_info_get_destination ()

gconstpointer gnetwork_interface_info_get_destination
                                            (const GNetworkInterfaceInfo *info,
                                             GNetworkProtocols protocol);

Retrieves the destination address of the interface described by info, (e.g. "127.0.0.1" for IPv4, "::1" for IPv6, or "00:00:00:00:00:00" for hardware). The returned data should not be modified or freed. If info is invalid or is not a "point-to-point" interface, NULL will be returned.

See also: gnetwork_interface_info_get_flags().

info : the interface information to examine.
protocol : the protocol type to use.
Returns : the protocol destination address of info, or NULL.

Since 1.0


gnetwork_interface_info_get_multicasts ()

G_CONST_RETURN GSList* gnetwork_interface_info_get_multicasts
                                            (const GNetworkInterfaceInfo *info,
                                             GNetworkProtocols protocol);

Retrieves a list of current multicast IP addresses for protocol from the interface described by info (e.g. "224.0.0.1" for IPv4, or "ff02::1" for IPv6). If info or protocol is invalid, or protocol does not support multicasting (like the packet protocol), NULL will be returned.

info : the interface information to examine.
protocol : the protocol to use.
Returns : the multicast addresses of info, or NULL.

Since 1.0


gnetwork_interface_info_get_flags ()

GNetworkInterfaceFlags gnetwork_interface_info_get_flags
                                            (const GNetworkInterfaceInfo *info);

Retrieves the flags set on interface described by info. If info is invalid or no flags have been set, GNETWORK_INTERFACE_NONE is returned.

info : the interface information to examine.
Returns : the flags set on interface.

Since 1.0


gnetwork_interface_info_ref ()

GNetworkInterfaceInfo* gnetwork_interface_info_ref
                                            (GNetworkInterfaceInfo *info);

Creates a reference to the data in info. When no longer needed, this reference should be released with gnetwork_interface_info_unref().

info : the data to reference.
Returns : a reference to info, or NULL.

Since 1.0


gnetwork_interface_info_unref ()

void        gnetwork_interface_info_unref   (GNetworkInterfaceInfo *info);

Releases a reference to the data in info. When all references have been released, the data in info will be destroyed.

info : the local interface reference to release.

Since 1.0


gnetwork_interface_info_collate ()

gint        gnetwork_interface_info_collate (const GNetworkInterfaceInfo *info1,
                                             const GNetworkInterfaceInfo *info2);

Determines which interface of the arguments is "greater" (should be sorted before) than the other, using the name.

info1 : a structure describing a local interface.
info2 : a structure describing a local interface.
Returns : -1 if info1 should be sorted first, 1 if info2 should be sorted first, or 0 if they are equal.

Since 1.0