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);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 .NET Server 2003 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.
CREDITS
Thanks to Aldo Calpini for the powerful Win32::API module that makes this thing work.
AUTHOR
Luigino Masarati, <lmasarati@hotmail.com>