File Information
Library: Net
Package: Sockets
Header: Poco/Net/NetworkInterface.h
Description
This class represents a network interface.
NetworkInterface is used with MulticastSocket to specify multicast interfaces for sending and receiving multicast messages.
The class also provides static member functions for enumerating or searching network interfaces and their respective configuration values.
On Windows, detection capabilities vary depending on the OS version/service pack. Although the best effort is made not to attempt access to non-existent features through a combination of compile/runtime checks, when running binaries compiled on a newer version of the OS on an older one problems may occur; if possible, it is best to run binaries on the OS version where they were compiled. This particularly applies to OS versions older than Vista and XP.
Member Summary
Member Functions: adapterName, addAddress, address, addressList, broadcastAddress, destAddress, displayName, firstAddress, forAddress, forIndex, forName, impl, index, interfaceNameToAddress, interfaceNameToIndex, isLoopback, isPointToPoint, isRunning, isUp, list, macAddress, map, mtu, name, operator <, operator =, operator ==, subnetMask, supportsBroadcast, supportsIP, supportsIPv4, supportsIPv6, supportsMulticast, swap, type
Types
AddressIterator
typedef AddressList::iterator AddressIterator;
AddressList
typedef std::vector < AddressTuple > AddressList;
AddressTuple
typedef Poco::Tuple < IPAddress, IPAddress, IPAddress > AddressTuple;
ConstAddressIterator
typedef AddressList::const_iterator ConstAddressIterator;
List
typedef std::vector < NetworkInterface > List;
MACAddress
typedef std::vector < unsigned char > MACAddress;
Map
typedef std::map < unsigned, NetworkInterface > Map;
NetworkInterfaceList
typedef List NetworkInterfaceList;
Enumerations
AddressType
IPVersion
Return interfaces with IPv4 address only
Return interfaces with IPv6 address only
Return interfaces with IPv4 or IPv6 address
Type
Constructors
NetworkInterface
NetworkInterface(
unsigned index = NO_INDEX
);
Creates a NetworkInterface representing the default interface.
The name is empty, the IP address is the wildcard address and the index is max value of unsigned integer.
NetworkInterface
NetworkInterface(
const NetworkInterface & interfc
);
Creates the NetworkInterface by copying another one.
NetworkInterface 
NetworkInterface(
const std::string & name,
const IPAddress & address,
unsigned index,
MACAddress * pMACAddress = 0
);
Creates the NetworkInterface.
NetworkInterface
NetworkInterface(
const std::string & name,
const std::string & displayName,
const std::string & adapterName,
unsigned index,
MACAddress * pMACAddress = 0
);
Creates the NetworkInterface.
NetworkInterface
NetworkInterface(
const std::string & name,
const std::string & displayName,
const std::string & adapterName,
const IPAddress & address,
unsigned index,
MACAddress * pMACAddress = 0
);
Creates the NetworkInterface.
NetworkInterface
NetworkInterface(
const std::string & name,
const IPAddress & address,
const IPAddress & subnetMask,
const IPAddress & broadcastAddress,
unsigned index,
MACAddress * pMACAddress = 0
);
Creates the NetworkInterface.
NetworkInterface
NetworkInterface(
const std::string & name,
const std::string & displayName,
const std::string & adapterName,
const IPAddress & address,
const IPAddress & subnetMask,
const IPAddress & broadcastAddress,
unsigned index,
MACAddress * pMACAddress = 0
);
Creates the NetworkInterface.
Destructor
~NetworkInterface
~NetworkInterface();
Destroys the NetworkInterface.
Member Functions
adapterName
const std::string & adapterName() const;
Returns the interface adapter name.
On Windows platforms, this is the network adapter LUID. The adapter name is used by some Windows Net APIs like DHCP.
On other platforms this is the same as name().
addAddress
void addAddress(
const IPAddress & address
);
Adds address to the interface.
addAddress
void addAddress(
const IPAddress & address,
const IPAddress & subnetMask,
const IPAddress & broadcastAddress
);
Adds address to the interface.
address
const IPAddress & address(
unsigned index = 0
) const;
Returns the IP address bound to the interface at index position.
addressList
const AddressList & addressList() const;
Returns the list of IP addresses bound to the interface.
broadcastAddress
const IPAddress & broadcastAddress(
unsigned index = 0
) const;
Returns the broadcast address for this network interface.
destAddress
const IPAddress & destAddress(
unsigned index = 0
) const;
Returns the IPv4 point-to-point destination address for this network interface.
displayName
const std::string & displayName() const;
Returns the interface display name.
On Windows platforms, this is currently the network adapter name. This may change to the "friendly name" of the network connection in a future version, however.
On other platforms this is the same as name().
firstAddress
const IPAddress & firstAddress(
IPAddress::Family family
) const;
Returns the first IP address bound to the interface. Throws NotFoundException if the address family is not configured on the interface.
firstAddress
void firstAddress(
IPAddress & addr,
IPAddress::Family family = IPAddress::IPv4
) const;
Returns the first IP address bound to the interface. If the address family is not configured on the interface, the address returned in addr will be unspecified (wildcard).
forAddress 
static NetworkInterface forAddress(
const IPAddress & address
);
Returns the NetworkInterface for the given IP address.
Throws an InterfaceNotFoundException if an interface with the give address does not exist.
forIndex
static NetworkInterface forIndex(
unsigned index
);
Returns the NetworkInterface for the given interface index.
Throws an InterfaceNotFoundException if an interface with the given index does not exist.
forName
static NetworkInterface forName(
const std::string & name,
bool requireIPv6 = false
);
Returns the NetworkInterface for the given name.
If requireIPv6 is false, an IPv4 interface is returned. Otherwise, an IPv6 interface is returned.
Throws an InterfaceNotFoundException if an interface with the give name does not exist.
forName
static NetworkInterface forName(
const std::string & name,
IPVersion ipVersion
);
Returns the NetworkInterface for the given name.
The ipVersion argument can be used to specify whether an IPv4 (IPv4_ONLY) or IPv6 (IPv6_ONLY) interface is required, or whether the caller does not care (IPv4_OR_IPv6).
Throws an InterfaceNotFoundException if an interface with the give name does not exist.
index
unsigned index() const;
Returns the interface OS index.
isLoopback
bool isLoopback() const;
Returns true if the interface is loopback.
isPointToPoint
bool isPointToPoint() const;
Returns true if the interface is point-to-point.
isRunning
bool isRunning() const;
Returns true if the interface is running.
isUp
bool isUp() const;
Returns true if the interface is up.
list
static List list(
bool ipOnly = true,
bool upOnly = true
);
Returns a list with all network interfaces on the system.
If ipOnly is true, only interfaces supporting IP are returned. Otherwise, all system network interfaces are returned.
If upOnly is true, only interfaces being up are returned. Otherwise, both interfaces being up and down are returned.
If there are multiple addresses bound to one interface, multiple NetworkInterface entries are listed for the same interface.
macAddress
const MACAddress & macAddress() const;
Returns MAC (Media Access Control) address for the interface.
map
static Map map(
bool ipOnly = true,
bool upOnly = true
);
Returns a map containing system network interfaces Map is keyed by interface system indices.
If ipOnly is true, only interfaces supporting IP are returned. Otherwise, all system network interfaces are returned.
If upOnly is true, only interfaces being up are returned. Otherwise, both interfaces being up and down are returned.
If there are multiple addresses bound to one interface, they are contained within the NetworkInterface (second) member of the pair.
mtu
unsigned mtu() const;
Returns the MTU for this interface.
name
const std::string & name() const;
Returns the interface name.
operator < 
bool operator < (
const NetworkInterface & other
) const;
Operator less-than.
operator =
NetworkInterface & operator = (
const NetworkInterface & interfc
);
Assigns another NetworkInterface.
operator ==
bool operator == (
const NetworkInterface & other
) const;
Operator equal. Compares interface indices.
subnetMask
const IPAddress & subnetMask(
unsigned index = 0
) const;
Returns the subnet mask for this network interface.
supportsBroadcast
bool supportsBroadcast() const;
Returns true if the interface supports broadcast.
supportsIP
bool supportsIP() const;
Returns true if the interface supports IP.
supportsIPv4
bool supportsIPv4() const;
Returns true if the interface supports IPv4.
supportsIPv6
bool supportsIPv6() const;
Returns true if the interface supports IPv6.
supportsMulticast
bool supportsMulticast() const;
Returns true if the interface supports multicast.
swap
void swap(
NetworkInterface & other
);
Swaps the NetworkInterface with another one.
type
NetworkInterface::Type type() const;
returns the MIB IfType of the interface.
impl
NetworkInterfaceImpl & impl();
interfaceNameToAddress
IPAddress interfaceNameToAddress(
const std::string & interfaceName
) const;
Determines the IPAddress bound to the interface with the given name.
interfaceNameToIndex
unsigned interfaceNameToIndex(
const std::string & interfaceName
) const;
Determines the interface index of the interface with the given name.
Variables
MAC_SEPARATOR
static const char MAC_SEPARATOR = ':';
NO_INDEX
static const unsigned NO_INDEX = ~0;