The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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>