Win32::IPHelper - Perl wrapper for Win32 IP Helper functions and structures.
use Win32::IPHelper; $ret = Win32::IPHelper::GetInterfaceInfo(\%IP_INTERFACE_INFO); $ret = Win32::IPHelper::GetAdaptersInfo(\@IP_ADAPTER_INFO); $ret = Win32::IPHelper::GetAdapterIndex(\$AdapterName, \$IfIndex); $ret = Win32::IPHelper::GetIfEntry($IfIndex, \%MIB_IFROW); $ret = Win32::IPHelper::AddIPAddress($Address, $IpMask, $IfIndex, \$NTEContext, \$NTEInstance); $ret = Win32::IPHelper::DeleteIPAddress($NTEContext); $ret = Win32::IPHelper::IpReleaseAddress(\%AdapterInfo); $ret = Win32::IPHelper::IpRenewAddress(\%AdapterInfo); $ret = Win32::IPHelper::GetTcpTable(\@TCP_TABLE, $bOrder); $ret = Win32::IPHelper::AllocateAndGetTcpExTableFromStack(\@TCP_EX_TABLE, $bOrder); $ret = Win32::IPHelper::GetExtendedTcpTable(\@TCP_EX_TABLE, $bOrder); $ret = Win32::IPHelper::GetUdpTable(\@UDP_TABLE, $bOrder); $ret = Win32::IPHelper::AllocateAndGetUdpExTableFromStack(\@UDP_EX_TABLE, $bOrder); $ret = Win32::IPHelper::GetExtendedUdpTable(\@UDP_EX_TABLE, $bOrder);
Interface to Win32 IP Helper functions and data structures, needed to retrieve and modify configuration settings for the Transmission Control Protocol/Internet Protocol (TCP/IP) transport on the local computer.
This module covers a small subset of the functions and data structures provided by the Win32 IP Helper API.
Purpose
The Internet Protocol Helper (IP Helper) API enables the retrieval and modification of network configuration settings for the local computer.
Where Applicable
The IP Helper API is applicable in any computing environment where programmatically manipulating TCP/IP configuration is useful. Typical applications include IP routing protocols and Simple Network Management Protocol (SNMP) agents.
Developer Audience
The IP Helper API is designed for use by C/C++ programmers. Programmers should also be familiar with TCP/IP networking concepts.
Run-time Requirements
The IP Helper API is supported on:
Microsoft Windows 98
Microsoft Windows Millennium Edition
Microsoft Windows NT version 4.0 with Service Pack 4
Microsoft Windows 2000
Microsoft Windows XP
Microsoft Windows Vista
Microsoft Windows Server 2003 family
Microsoft Windows Server 2008 family
Note
Not all operating systems support all functions. If an IP Helper function is called on a platform that does not support the function, ERROR_NOT_SUPPORTED is returned. For more specific information about which operating systems support a particular function, refer to the Requirements sections in the documentation.
The complete SDK Reference documentation is available online through Microsoft MSDN Library (http://msdn.microsoft.com/library/default.asp)
None by default.
The GetInterfaceInfo function obtains a IP_INTERFACE_INFO structure that contains the list of the network interface adapters on the local system.
Example
use Win32::IPHelper; use Data::Dumper; my %IP_INTERFACE_INFO; $ret = Win32::IPHelper::GetInterfaceInfo(\%IP_INTERFACE_INFO); if ($ret == 0) { print Data::Dumper->Dump([\%IP_INTERFACE_INFO], [qw(IP_INTERFACE_INFO)]); } else { printf "GetInterfaceInfo() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
Return Values
If the function succeeds, the return value is 0.
If the function fails, the error code can be decoded with Win32::FormatMessage($ret).
Remarks
The GetAdaptersInfo and GetInterfaceInfo functions do not return information about the loopback interface
Requirements
Client: Included in Windows XP, Windows 2000 Professional, Windows Me, Windows 98. Server: Included in Windows .NET Server 2003, Windows 2000 Server. Header: Declared in Iphlpapi.h. Library: Iphlpapi.dll.
The GetAdaptersInfo function obtains a list of IP_ADAPTER_INFO structures that contains adapter information for the local computer.
Examples
use Win32::IPHelper; use Data::Dumper; my @IP_ADAPTER_INFO; $ret = Win32::IPHelper::GetAdaptersInfo(\@IP_ADAPTER_INFO); if ($ret == 0) { print Data::Dumper->Dump([\@IP_ADAPTER_INFO], [qw(IP_ADAPTER_INFO)]); } else { printf "GetAdaptersInfo() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
Windows XP/Windows .NET Server 2003 family or later: The list of adapters returned by GetAdaptersInfo includes unidirectional adapters. To generate a list of adapters that can both send and receive data, call GetUniDirectionalAdapterInfo, and exclude the returned adapters from the list returned by GetAdaptersInfo.
The GetAdapterIndex function obtains the index of an adapter, given its name.
use Win32::IPHelper; my $IfIndex; # the value for AdapterName is found in @IP_ADAPTER_INFO, for example # $IP_ADAPTER_INFO[0]{'AdapterName'}; my $AdapterName = '{88CE272F-847A-40CF-BFBA-001D9AD97450}'; $ret = Win32::IPHelper::GetAdapterIndex(\$AdapterName,\$IfIndex); if ($ret == 0) { printf "Index for '%s' interface is %u\n", $AdapterName, $IfIndex; } else { printf "GetAdapterIndex() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
Client: Included in Windows XP, Windows 2000 Professional. Server: Included in Windows .NET Server 2003, Windows 2000 Server. Header: Declared in Iphlpapi.h. Library: Iphlpapi.dll.
The GetIfEntry function retrieves a MIB_IFROW structure information for the specified interface on the local computer.
use Win32::IPHelper; use Data::Dumper; my $IfIndex; # the value for AdapterName is found in @IP_ADAPTER_INFO, for example # $IP_ADAPTER_INFO[0]{'AdapterName'}; my $AdapterName = '{88CE272F-847A-40CF-BFBA-001D9AD97450}'; $ret = Win32::IPHelper::GetAdapterIndex(\$AdapterName,\$IfIndex); if ($ret == 0) { my %MIB_IFROW; $ret = Win32::IPHelper::GetIfEntry($IfIndex,\%MIB_IFROW); if ($ret == 0) { print Data::Dumper->Dump([\%MIB_IFROW], [qw(MIB_IFROW)]); } else { printf "GetIfEntry() error %u: %s\n", $ret, Win32::FormatMessage($ret); } } else { printf "GetAdapterIndex() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
Client: Included in Windows XP, Windows 2000 Professional, Windows NT Workstation 4.0 SP4 and later, Windows Me, Windows 98. Server: Included in Windows .NET Server 2003, Windows 2000 Server, Windows NT Server 4.0 SP4 and later. Header: Declared in Iphlpapi.h. Library: Iphlpapi.dll.
The AddIPAddress function adds the specified IP address to the specified adapter.
use Win32::IPHelper; my $IfIndex; # the value for AdapterName is found in @IP_ADAPTER_INFO, for example # $IP_ADAPTER_INFO[0]{'AdapterName'}; my $AdapterName = '{88CE272F-847A-40CF-BFBA-001D9AD97450}'; $ret = Win32::IPHelper::GetAdapterIndex(\$AdapterName,\$IfIndex); if ($ret == 0) { my $Address = '192.168.1.10'; my $IpMask = '255.255.255.0'; my $NTEContext; my $NTEInstance; $ret = Win32::IPHelper::AddIPAddress($Address,$IpMask,$IfIndex,\$NTEContext,\$NTEInstance); if ($ret == 0) { printf "Address has been added successfully with Context=%u\n", $NTEContext; } else { printf "AddIPAddress() error %u: %s\n", $ret, Win32::FormatMessage($ret); } } else { printf "GetAdapterIndex() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
The IP address created by AddIPAddress is not persistent. The address exists only as long as the adapter object exists. Restarting the computer destroys the address, as does manually resetting the network interface card (NIC). Also, certain PnP events may destroy the address.
The DeleteIPAddress function deletes an IP address previously added using AddIPAddress.
use Win32::IPHelper; my $NTEContext = 2; $ret = Win32::IPHelper::DeleteIPAddress($NTEContext); if ($ret == 0) { printf "Address has been deleted successfully from Context=%u\n", $NTEContext; } else { printf "DeleteIPAddress() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
The IpReleaseAddress function releases an IP address previously obtained through Dynamic Host Configuration Protocol (DHCP).
use Win32::IPHelper; my %IP_INTERFACE_INFO; $ret = Win32::IPHelper::GetInterfaceInfo(\%IP_INTERFACE_INFO); if ($ret == 0) { my %AdapterInfo = %{ $IP_INTERFACE_INFO{'Adapters'}[0] }; $ret = Win32::IPHelper::IpReleaseAddress(\%AdapterInfo); if ($ret == 0) { print "Address has been released successfully\n"; } else { printf "IpReleaseAddress() error %u: %s\n", $ret, Win32::FormatMessage($ret); } } else { printf "GetInterfaceInfo() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
The IpRenewAddress function renews a lease on an IP address previously obtained through Dynamic Host Configuration Protocol (DHCP).
use Win32::IPHelper; my %IP_INTERFACE_INFO; $ret = Win32::IPHelper::GetInterfaceInfo(\%IP_INTERFACE_INFO); if ($ret == 0) { my %AdapterInfo = %{ $IP_INTERFACE_INFO{'Adapters'}[0] }; $ret = Win32::IPHelper::IpRenewAddress(\%AdapterInfo); if ($ret == 0) { print "Address has been renewed successfully\n"; } else { printf "IpRenewAddress() error %u: %s\n", $ret, Win32::FormatMessage($ret); } } else { printf "GetInterfaceInfo() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
The GetTcpTable function retrieves the TCP connection table.
use Win32::IPHelper; use Data::Dumper; my @TCP_TABLE; my $bOrder = 1; $ret = Win32::IPHelper::GetTcpTable(\@TCP_TABLE, $bOrder); if ($ret == 0) { print Data::Dumper->Dump([\@TCP_TABLE], [qw(TCP_TABLE)]); } else { printf "GetTcpTable() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
Client: Requires Windows XP, Windows 2000 Professional, Windows NT Workstation 4.0 SP4 and later, Windows Me, or Windows 98. Server: Requires Windows Server 2003, Windows 2000 Server, or Windows NT Server 4.0 SP4 and later. Header: Declared in Iphlpapi.h. Library: Iphlpapi.dll.
The AllocateAndGetTcpExTableFromStack function retrieves the TCP connection table with the additional ProcessId.
use Win32::IPHelper; use Data::Dumper; my @TCP_EX_TABLE; my $bOrder = 1; $ret = Win32::IPHelper::AllocateAndGetTcpExTableFromStack(\@TCP_EX_TABLE, $bOrder); if ($ret == 0) { print Data::Dumper->Dump([\@TCP_EX_TABLE], [qw(TCP_EX_TABLE)]); } else { printf "AllocateAndGetTcpExTableFromStack() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
The AllocateAndGetTcpExTableFromStack function is undocumented and is available only in Windows XP and Windows Server 2003.
Client: Requires Windows XP. Server: Requires Windows Server 2003. Header: Undeclared. Library: Iphlpapi.dll.
The GetExtendedTcpTable function retrieves the TCP connection table with the additional ProcessId.
use Win32::IPHelper; use Data::Dumper; my @TCP_EX_TABLE; my $bOrder = 1; $ret = Win32::IPHelper::GetExtendedTcpTable(\@TCP_EX_TABLE, $bOrder); if($ret == 0) { print Data::Dumper->Dump([\@TCP_EX_TABLE], [qw(TCP_EX_TABLE)]); } else { printf "GetExtendedTcpTable() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
The GetExtendedTcpTable function is available in Windows Server 2003 SP1, Sever 2008, XP SP2 and Vista.
Client: Requires Windows XP or Vista. Server: Requires Windows Server 2003 SP2 or Server 2008. Library: Iphlpapi.dll.
The GetExtendedTcpTable function retrieves the TCP connection table with the additional ProcessId (if supported)
use Win32::IPHelper; use Data::Dumper; my @TCP_EX_TABLE; my $bOrder = 1; $ret = Win32::IPHelper::GetTcpTableAuto(\@TCP_EX_TABLE, $bOrder); if($ret == 0) { print Data::Dumper->Dump([\@TCP_EX_TABLE], [qw(TCP_EX_TABLE)]); } else { printf "GetTcpTableAuto() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
The GetTcpTableAuto function is a wrapper to functions GetExtendedTcpTable, AllocateAndGetTcpExTableFromStack and GetTcpTable; the first supported function is used to retrieve the best available detail from TCP connection table.
Library: Iphlpapi.dll.
The GetUdpTable function retrieves the User Datagram Protocol (UDP) listener table.
use Win32::IPHelper; use Data::Dumper; my @UDP_TABLE; my $bOrder = 1; $ret = Win32::IPHelper::GetTcpTable(\@UDP_TABLE, $bOrder); if ($ret == 0) { print Data::Dumper->Dump([\@UDP_TABLE], [qw(UDP_TABLE)]); } else { printf "GetUdpTable() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
The AllocateAndGetTcpExTableFromStack function retrieves the User Datagram Protocol (UDP) listener table with the additional ProcessId.
use Win32::IPHelper; use Data::Dumper; my @TCP_EX_TABLE; my $bOrder = 1; $ret = Win32::IPHelper::AllocateAndGetUdpExTableFromStack(\@UDP_EX_TABLE, $bOrder); if ($ret == 0) { print Data::Dumper->Dump([\@UDP_EX_TABLE], [qw(UDP_EX_TABLE)]); } else { printf "AllocateAndGetUdpExTableFromStack() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
The AllocateAndGetUdpExTableFromStack function is undocumented and is available only in Windows XP and Windows Server 2003.
The GetExtendedUdpTable function retrieves the User Datagram Protocol (UDP) listener table with the additional ProcessId.
use Win32::IPHelper; use Data::Dumper; my @UDP_EX_TABLE; my $bOrder = 1; $ret = Win32::IPHelper::GetExtendedUdpTable(\@UDP_EX_TABLE, $bOrder); if($ret == 0) { print Data::Dumper->Dump([\@UDP_EX_TABLE], [qw(UDP_EX_TABLE)]); } else { printf "GetExtendedUdpTable() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
The GetExtendedUdpTable function is available in Windows Server 2003 SP1, Sever 2008, XP SP2 and Vista.
The GetUdpTableAuto function retrieves the User Datagram Protocol (UDP) listener table with the additional ProcessId (if supported).
use Win32::IPHelper; use Data::Dumper; my @UDP_EX_TABLE; my $bOrder = 1; $ret = Win32::IPHelper::GetUdpTableAuto(\@UDP_EX_TABLE, $bOrder); if($ret == 0) { print Data::Dumper->Dump([\@UDP_EX_TABLE], [qw(UDP_EX_TABLE)]); } else { printf "GetUdpTableAuto() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
The GetUdpTableAuto function is a wrapper to functions GetExtendedUdpTable, AllocateAndGetUdpExTableFromStack and GetUdpTable; the first supported function is used to retrieve the best available detail from UDP listener table.
The GetNetworkParams function retrieves network parameters for the local computer.
use Win32::IPHelper; use Data::Dumper; my %FIXED_INFO; $ret = Win32::IPHelper::GetNetworkParams(\%FIXED_INFO); if ($ret == 0) { print Data::Dumper->Dump([\%FIXED_INFO], [qw(FIXED_INFO)]); } else { printf "GetNetworkParams() error %u: %s\n", $ret, Win32::FormatMessage($ret); }
Client: Requires Windows XP, Windows 2000 Professional, Windows Me or Windows 98. Server: Requires Windows Server 2003 or Windows 2000 Server. Header: Undeclared. Library: Iphlpapi.dll.
Thanks to Aldo Calpini for the powerful Win32::API module that makes this thing work.
Thanks to Hanno Stock (HANSTO) for the GetNetworkParams() and _FIXED_INFO() wrapper and helper.
Thanks to Peter Arnhold for the GetExtendedTcpTable() and GetExtendedUdpTable() functions.
Luigino Masarati, <lmasarati at hotmail.com>
To install Win32::IPHelper, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Win32::IPHelper
CPAN shell
perl -MCPAN -e shell install Win32::IPHelper
For more information on module installation, please visit the detailed CPAN module installation guide.