1 // 2 // NetworkInterface.h 3 // 4 // Library: Net 5 // Package: Sockets 6 // Module: NetworkInterface 7 // 8 // Definition of the NetworkInterface class. 9 // 10 // Copyright (c) 2005-2006, Applied Informatics Software Engineering GmbH. 11 // and Contributors. 12 // 13 // SPDX-License-Identifier: BSL-1.0 14 // 15 16 17 #ifndef Net_NetworkInterface_INCLUDED 18 #define Net_NetworkInterface_INCLUDED 19 20 21 #include "Poco/Net/Net.h" 22 23 24 #ifdef POCO_NET_HAS_INTERFACE 25 26 27 #include "Poco/Net/IPAddress.h" 28 #include "Poco/Mutex.h" 29 #include "Poco/Tuple.h" 30 #include <map> 31 #include <ostream> 32 33 34 namespace Poco { 35 namespace Net { 36 37 38 class NetworkInterfaceImpl; 39 40 41 class Net_API NetworkInterface 42 /// This class represents a network interface. 43 /// 44 /// NetworkInterface is used with MulticastSocket to specify 45 /// multicast interfaces for sending and receiving multicast 46 /// messages. 47 /// 48 /// The class also provides static member functions for 49 /// enumerating or searching network interfaces and their 50 /// respective configuration values. 51 /// 52 /// On Windows, detection capabilities vary depending on the 53 /// OS version/service pack. Although the best effort is made 54 /// not to attempt access to non-existent features through a 55 /// combination of compile/runtime checks, when running binaries 56 /// compiled on a newer version of the OS on an older one 57 /// problems may occur; if possible, it is best to run 58 /// binaries on the OS version where they were compiled. 59 /// This particularly applies to OS versions older than Vista 60 /// and XP. 61 { 62 public: 63 typedef std::vector<NetworkInterface> List; 64 typedef List NetworkInterfaceList;//@deprecated 65 typedef std::map<unsigned, NetworkInterface> Map; 66 typedef Poco::Tuple<IPAddress, IPAddress, IPAddress> AddressTuple; 67 typedef std::vector<AddressTuple> AddressList; 68 typedef AddressList::iterator AddressIterator; 69 typedef AddressList::const_iterator ConstAddressIterator; 70 typedef std::vector<unsigned char> MACAddress; 71 72 enum AddressType 73 { 74 IP_ADDRESS, 75 SUBNET_MASK, 76 BROADCAST_ADDRESS 77 }; 78 79 enum Type 80 { 81 NI_TYPE_ETHERNET_CSMACD, 82 NI_TYPE_ISO88025_TOKENRING, 83 NI_TYPE_FRAMERELAY, 84 NI_TYPE_PPP, 85 NI_TYPE_SOFTWARE_LOOPBACK, 86 NI_TYPE_ATM, 87 NI_TYPE_IEEE80211, 88 NI_TYPE_TUNNEL, 89 NI_TYPE_IEEE1394, 90 NI_TYPE_OTHER 91 }; 92 93 enum IPVersion 94 { 95 IPv4_ONLY, /// Return interfaces with IPv4 address only 96 IPv6_ONLY, /// Return interfaces with IPv6 address only 97 IPv4_OR_IPv6 /// Return interfaces with IPv4 or IPv6 address 98 }; 99 100 static const unsigned NO_INDEX = ~0; 101 #if defined(POCO_OS_FAMILY_WINDOWS) 102 static const char MAC_SEPARATOR = '-'; 103 #else 104 static const char MAC_SEPARATOR = ':'; 105 #endif 106 107 NetworkInterface(unsigned index = NO_INDEX); 108 /// Creates a NetworkInterface representing the 109 /// default interface. 110 /// 111 /// The name is empty, the IP address is the wildcard 112 /// address and the index is max value of unsigned integer. 113 114 NetworkInterface(const NetworkInterface& interfc); 115 /// Creates the NetworkInterface by copying another one. 116 117 ~NetworkInterface(); 118 /// Destroys the NetworkInterface. 119 120 NetworkInterface& operator = (const NetworkInterface& interfc); 121 /// Assigns another NetworkInterface. 122 123 bool operator < (const NetworkInterface& other) const; 124 /// Operator less-than. 125 126 bool operator == (const NetworkInterface& other) const; 127 /// Operator equal. Compares interface indices. 128 129 void swap(NetworkInterface& other); 130 /// Swaps the NetworkInterface with another one. 131 132 unsigned index() const; 133 /// Returns the interface OS index. 134 135 const std::string& name() const; 136 /// Returns the interface name. 137 138 const std::string& displayName() const; 139 /// Returns the interface display name. 140 /// 141 /// On Windows platforms, this is currently the network adapter 142 /// name. This may change to the "friendly name" of the network 143 /// connection in a future version, however. 144 /// 145 /// On other platforms this is the same as name(). 146 147 const std::string& adapterName() const; 148 /// Returns the interface adapter name. 149 /// 150 /// On Windows platforms, this is the network adapter LUID. 151 /// The adapter name is used by some Windows Net APIs like DHCP. 152 /// 153 /// On other platforms this is the same as name(). 154 155 const IPAddress& firstAddress(IPAddress::Family family) const; 156 /// Returns the first IP address bound to the interface. 157 /// Throws NotFoundException if the address family is not 158 /// configured on the interface. 159 160 void firstAddress(IPAddress& addr, IPAddress::Family family = IPAddress::IPv4) const; 161 /// Returns the first IP address bound to the interface. 162 /// If the address family is not configured on the interface, 163 /// the address returned in addr will be unspecified (wildcard). 164 165 const IPAddress& address(unsigned index = 0) const; 166 /// Returns the IP address bound to the interface at index position. 167 168 void addAddress(const IPAddress& address); 169 /// Adds address to the interface. 170 171 void addAddress(const IPAddress& address, const IPAddress& subnetMask, const IPAddress& broadcastAddress); 172 /// Adds address to the interface. 173 174 const AddressList& addressList() const; 175 /// Returns the list of IP addresses bound to the interface. 176 177 const IPAddress& subnetMask(unsigned index = 0) const; 178 /// Returns the subnet mask for this network interface. 179 180 const IPAddress& broadcastAddress(unsigned index = 0) const; 181 /// Returns the broadcast address for this network interface. 182 183 const IPAddress& destAddress(unsigned index = 0) const; 184 /// Returns the IPv4 point-to-point destination address for this network interface. 185 186 const MACAddress& macAddress() const; 187 /// Returns MAC (Media Access Control) address for the interface. 188 189 unsigned mtu() const; 190 /// Returns the MTU for this interface. 191 192 NetworkInterface::Type type() const; 193 /// returns the MIB IfType of the interface. 194 195 bool supportsIP() const; 196 /// Returns true if the interface supports IP. 197 198 bool supportsIPv4() const; 199 /// Returns true if the interface supports IPv4. 200 201 bool supportsIPv6() const; 202 /// Returns true if the interface supports IPv6. 203 204 bool supportsBroadcast() const; 205 /// Returns true if the interface supports broadcast. 206 207 bool supportsMulticast() const; 208 /// Returns true if the interface supports multicast. 209 210 bool isLoopback() const; 211 /// Returns true if the interface is loopback. 212 213 bool isPointToPoint() const; 214 /// Returns true if the interface is point-to-point. 215 216 bool isRunning() const; 217 /// Returns true if the interface is running. 218 219 bool isUp() const; 220 /// Returns true if the interface is up. 221 222 static NetworkInterface forName(const std::string& name, bool requireIPv6 = false); 223 /// Returns the NetworkInterface for the given name. 224 /// 225 /// If requireIPv6 is false, an IPv4 interface is returned. 226 /// Otherwise, an IPv6 interface is returned. 227 /// 228 /// Throws an InterfaceNotFoundException if an interface 229 /// with the give name does not exist. 230 231 static NetworkInterface forName(const std::string& name, IPVersion ipVersion); 232 /// Returns the NetworkInterface for the given name. 233 /// 234 /// The ipVersion argument can be used to specify whether 235 /// an IPv4 (IPv4_ONLY) or IPv6 (IPv6_ONLY) interface is required, 236 /// or whether the caller does not care (IPv4_OR_IPv6). 237 /// 238 /// Throws an InterfaceNotFoundException if an interface 239 /// with the give name does not exist. 240 241 static NetworkInterface forAddress(const IPAddress& address); 242 /// Returns the NetworkInterface for the given IP address. 243 /// 244 /// Throws an InterfaceNotFoundException if an interface 245 /// with the give address does not exist. 246 247 static NetworkInterface forIndex(unsigned index); 248 /// Returns the NetworkInterface for the given interface index. 249 /// 250 /// Throws an InterfaceNotFoundException if an interface 251 /// with the given index does not exist. 252 253 static List list(bool ipOnly = true, bool upOnly = true); 254 /// Returns a list with all network interfaces 255 /// on the system. 256 /// 257 /// If ipOnly is true, only interfaces supporting IP 258 /// are returned. Otherwise, all system network interfaces 259 /// are returned. 260 /// 261 /// If upOnly is true, only interfaces being up are returned. 262 /// Otherwise, both interfaces being up and down are returned. 263 /// 264 /// If there are multiple addresses bound to one interface, 265 /// multiple NetworkInterface entries are listed for 266 /// the same interface. 267 268 static Map map(bool ipOnly = true, bool upOnly = true); 269 /// Returns a map containing system network interfaces 270 /// Map is keyed by interface system indices. 271 /// 272 /// If ipOnly is true, only interfaces supporting IP 273 /// are returned. Otherwise, all system network interfaces 274 /// are returned. 275 /// 276 /// If upOnly is true, only interfaces being up are returned. 277 /// Otherwise, both interfaces being up and down are returned. 278 /// 279 /// If there are multiple addresses bound to one interface, 280 /// they are contained within the NetworkInterface (second) 281 /// member of the pair. 282 283 protected: 284 NetworkInterface(const std::string& name, const std::string& displayName, const std::string& adapterName, const IPAddress& address, unsigned index, MACAddress* pMACAddress = 0); 285 /// Creates the NetworkInterface. 286 287 NetworkInterface(const std::string& name, const std::string& displayName, const std::string& adapterName, unsigned index, MACAddress* pMACAddress = 0); 288 /// Creates the NetworkInterface. 289 290 NetworkInterface(const std::string& name, const IPAddress& address, unsigned index, MACAddress* pMACAddress = 0); 291 /// Creates the NetworkInterface. 292 293 NetworkInterface(const std::string& name, 294 const std::string& displayName, 295 const std::string& adapterName, 296 const IPAddress& address, 297 const IPAddress& subnetMask, 298 const IPAddress& broadcastAddress, 299 unsigned index, 300 MACAddress* pMACAddress = 0); 301 /// Creates the NetworkInterface. 302 303 NetworkInterface(const std::string& name, 304 const IPAddress& address, 305 const IPAddress& subnetMask, 306 const IPAddress& broadcastAddress, 307 unsigned index, 308 MACAddress* pMACAddress = 0); 309 /// Creates the NetworkInterface. 310 311 IPAddress interfaceNameToAddress(const std::string& interfaceName) const; 312 /// Determines the IPAddress bound to the interface with the given name. 313 314 unsigned interfaceNameToIndex(const std::string& interfaceName) const; 315 /// Determines the interface index of the interface with the given name. 316 impl()317 NetworkInterfaceImpl& impl() { return *_pImpl; }; 318 319 private: 320 NetworkInterfaceImpl* _pImpl; 321 322 static Poco::FastMutex _mutex; 323 }; 324 325 326 /// 327 /// inlines 328 /// 329 330 331 inline bool NetworkInterface::operator < (const NetworkInterface& other) const 332 { 333 return this->index() < other.index(); 334 } 335 336 337 inline bool NetworkInterface::operator == (const NetworkInterface& other) const 338 { 339 return this->index() == other.index(); 340 } 341 342 343 } } // namespace Poco::Net 344 345 346 Net_API std::ostream& operator << (std::ostream& ostr, const Poco::Net::NetworkInterface::MACAddress& addr); 347 348 349 #endif // POCO_NET_HAS_INTERFACE 350 351 352 #endif // Net_NetworkInterface_INCLUDED 353