NAME
Win32::IPHelper - Perl wrapper for Win32 IP Helper functions and structures.
SYNOPSIS
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);DESCRIPTION
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)
EXPORT
None by default.
FUNCTIONS
GetInterfaceInfo(\%IP_INTERFACE_INFO)
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.
GetAdaptersInfo(\@IP_ADAPTER_INFO)
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);
}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
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.
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.
GetAdapterIndex(\$AdapterName,\$IfIndex)
The GetAdapterIndex function obtains the index of an adapter, given its name.
Example
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);
}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).
Requirements
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.
GetIfEntry($IfIndex,\%MIB_IFROW)
The GetIfEntry function retrieves a MIB_IFROW structure information for the specified interface on the local computer.
Example
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);
}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).
Requirements
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.
AddIPAddress($Address,$IpMask,$IfIndex,\$NTEContext,\$NTEInstance)
The AddIPAddress function adds the specified IP address to the specified adapter.
Example
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);
}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 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.
Requirements
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.
DeleteIPAddress($NTEContext)
The DeleteIPAddress function deletes an IP address previously added using AddIPAddress.
Example
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);
}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).
Requirements
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.
IpReleaseAddress(\%AdapterInfo)
The IpReleaseAddress function releases an IP address previously obtained through Dynamic Host Configuration Protocol (DHCP).
Example
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);
}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).
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.
IpRenewAddress(\%AdapterInfo)
The IpRenewAddress function renews a lease on an IP address previously obtained through Dynamic Host Configuration Protocol (DHCP).
Example
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);
}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).
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.
GetTcpTable(\@TCP_TABLE,$bOrder)
The GetTcpTable function retrieves the TCP connection table.
Example
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);
}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).
Requirements
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.
AllocateAndGetTcpExTableFromStack(\@TCP_EX_TABLE,$bOrder)
The AllocateAndGetTcpExTableFromStack function retrieves the TCP connection table with the additional ProcessId.
Example
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);
}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 AllocateAndGetTcpExTableFromStack function is undocumented and is available only in Windows XP and Windows Server 2003.
Requirements
Client: Requires Windows XP. Server: Requires Windows Server 2003. Header: Undeclared. Library: Iphlpapi.dll.
GetExtendedTcpTable(\@TCP_EX_TABLE,$bOrder)
The GetExtendedTcpTable function retrieves the TCP connection table with the additional ProcessId.
Example
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);
}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 GetExtendedTcpTable function is available in Windows Server 2003 SP1, Sever 2008, XP SP2 and Vista.
Requirements
Client: Requires Windows XP or Vista. Server: Requires Windows Server 2003 SP2 or Server 2008. Library: Iphlpapi.dll.
GetTcpTableAuto(\@TCP_EX_TABLE,$bOrder)
The GetExtendedTcpTable function retrieves the TCP connection table with the additional ProcessId (if supported)
Example
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);
}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 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.
Requirements
Library: Iphlpapi.dll.
GetUdpTable(\@UDP_TABLE,$bOrder)
The GetUdpTable function retrieves the User Datagram Protocol (UDP) listener table.
Example
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);
}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).
Requirements
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.
AllocateAndGetUdpExTableFromStack(\@UDP_EX_TABLE,$bOrder)
The AllocateAndGetTcpExTableFromStack function retrieves the User Datagram Protocol (UDP) listener table with the additional ProcessId.
Example
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);
}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 AllocateAndGetUdpExTableFromStack function is undocumented and is available only in Windows XP and Windows Server 2003.
Requirements
Client: Requires Windows XP. Server: Requires Windows Server 2003. Header: Undeclared. Library: Iphlpapi.dll.
GetExtendedUdpTable(\@UDP_EX_TABLE,$bOrder)
The GetExtendedUdpTable function retrieves the User Datagram Protocol (UDP) listener table with the additional ProcessId.
Example
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);
}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 GetExtendedUdpTable function is available in Windows Server 2003 SP1, Sever 2008, XP SP2 and Vista.
Requirements
Client: Requires Windows XP or Vista. Server: Requires Windows Server 2003 SP2 or Server 2008. Library: Iphlpapi.dll.
GetUdpTableAuto(\@UDP_EX_TABLE,$bOrder)
The GetUdpTableAuto function retrieves the User Datagram Protocol (UDP) listener table with the additional ProcessId (if supported).
Example
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);
}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 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.
Requirements
Library: Iphlpapi.dll.
GetNetworkParams(\%FIXED_INFO)
The GetNetworkParams function retrieves network parameters for the local computer.
Example
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);
}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).
Requirements
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.
CREDITS
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.
AUTHOR
Luigino Masarati, <lmasarati at hotmail.com>