Poco::Net

class NetworkInterface

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

IP_ADDRESS

SUBNET_MASK

BROADCAST_ADDRESS

IPVersion

IPv4_ONLY

Return interfaces with IPv4 address only

IPv6_ONLY

Return interfaces with IPv6 address only

IPv4_OR_IPv6

Return interfaces with IPv4 or IPv6 address

Type

NI_TYPE_ETHERNET_CSMACD

NI_TYPE_ISO88025_TOKENRING

NI_TYPE_FRAMERELAY

NI_TYPE_PPP

NI_TYPE_SOFTWARE_LOOPBACK

NI_TYPE_ATM

NI_TYPE_IEEE80211

NI_TYPE_TUNNEL

NI_TYPE_IEEE1394

NI_TYPE_OTHER

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 protected

NetworkInterface(
    const std::string & name,
    const IPAddress & address,
    unsigned index,
    MACAddress * pMACAddress = 0
);

Creates the NetworkInterface.

NetworkInterface protected

NetworkInterface(
    const std::string & name,
    const std::string & displayName,
    const std::string & adapterName,
    unsigned index,
    MACAddress * pMACAddress = 0
);

Creates the NetworkInterface.

NetworkInterface protected

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 protected

NetworkInterface(
    const std::string & name,
    const IPAddress & address,
    const IPAddress & subnetMask,
    const IPAddress & broadcastAddress,
    unsigned index,
    MACAddress * pMACAddress = 0
);

Creates the NetworkInterface.

NetworkInterface protected

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

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

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

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

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

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

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 < inline

bool operator < (
    const NetworkInterface & other
) const;

Operator less-than.

operator =

NetworkInterface & operator = (
    const NetworkInterface & interfc
);

Assigns another NetworkInterface.

operator == inline

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
) noexcept;

Swaps the NetworkInterface with another one.

type

NetworkInterface::Type type() const;

returns the MIB IfType of the interface.

impl protected inline

NetworkInterfaceImpl & impl();

interfaceNameToAddress protected

IPAddress interfaceNameToAddress(
    const std::string & interfaceName
) const;

Determines the IPAddress bound to the interface with the given name.

interfaceNameToIndex protected

unsigned interfaceNameToIndex(
    const std::string & interfaceName
) const;

Determines the interface index of the interface with the given name.

Variables

MAC_SEPARATOR static

static const char MAC_SEPARATOR = ':';

NO_INDEX static

static const unsigned NO_INDEX = ~0;