INFO: IP Helper APIs Add Net Config and Stat Info to Win32 Apps

ID: Q193059

The information in this article applies to:

• Microsoft Win32 Software Development Kit (SDK) on the following platforms:

      - Windows NT
      - Windows 98
  

SUMMARY

The IP Helper API (IPHLPAPI) is a public API that provides Windows network configuration and statistics information to Windows 32-bit applications. The API is available for Windows NT 4.0 Service Pack 4 and later, and for Windows 98. Not all IP Helper APIs are available for all Windows platforms.

MORE INFORMATION

This article provides a brief description of the IP Helper APIs available, grouped by the task they perform or the object they operate on. Additional information for the IP Helper APIs, including sample code, will be available on the Windows NT 5.0 Beta 2 Platform SDK release and later.

Interface Class

This class allows applications to retrieve network adapter characteristic information. The IP Helper APIs available for Windows NT 4.0 Service Pack 4 are listed below:

• GetIfTable: Retrieves all network adapters physical characteristics.
• GetIfEntry: Retrieves specific adapter characteristics.
• SetIfEntry: Updates a specific adapter's operating status, such as describing whether an interface is up, down, or in a testing mode.
• SetIpTTL: Allows applications to modify the Time to Live (TTL) field for all IP packets sent from your system.

IP Address Class

This class allows applications to modify and retrieve IP configuration information. However, most of these APIs are not supported on Windows NT 4.0 Service Pack 4. The IP Helper APIs available for Windows NT 4.0 SP 4 are listed below:

• GetIpAddrTable: Allows an application to retrieve IP address information.

ARP Table Class

This class provides access to the address resolution protocol (ARP) entries by mapping from an IP address to a physical address. The IP Helper APIs available for Windows NT 4.0 Service Pack 4 are listed below:

• GetIpNetTable: Retrieves address resolution table information.
• SetIpNetEntry: Adds entry to the ARP table.
• DeleteIpNetEntry: Deletes entry from the ARP table.

Route Table Class

This class allows applications to retrieve IP routing information and permits applications to make modifications to route entries in the table. Routing is the selection of the next hop address from a routing table over which a packet is sent. The IP Helper APIs available for Windows NT 4.0 Service Pack 4 are listed below:

• GetIpForwardTable: Retrieves routing table information.
• SetIpForwardEntry: Adds a route table entry.
• DeleteIpForwardEntry: Deletes a route table entry.
• GetRTTAndHopCount: Provides approximated round trip time information to a specific IP destination and also provides the hop count to that destination.

Statistics Class

This class provides information on various kinds of packet/connection statistics information on a local computer. The IP Helper APIs available for Windows NT 4.0 Service Pack 4 are listed below:

• GetIpStatistics: Retrieves Internet Protocol (IP) packet statistics.
• GetIcmpStatistics: Retrieves Internet Control Message Protocol (ICMP) statistics.
• GetTcpStatistics: Retrieves Transmission Control Protocol (TCP) statistics.
• GetUdpStatistics: Retrieves User Datagram Protocol (UDP) statistics.

IP Helper API Conventions

Interfaces are addressed by index, which is a large DWORD number. For applications that expect friendly interface numbers (for example, MIB, UI), use GetFriendlyIndex() for one-way conversion into friendly index.

Functions that return an array of structures take in/out size parameter pSize. The user initializes pSize so it points to the size of the buffer passed to the function. After a successful call, this parameter holds the actual size of the data returned. If the function fails because the buffer is too small, pSize points to the buffer size required to hold all available data and the function returns a Win32 error status. Most of these IP Helper APIs return ERROR_INSUFFICIENT_BUFFER; the exception is that the GetNetworkParams() and GetAdaptersInfo() APIs return ERROR_BUFFER_OVERFLOW.

Additional query words:

Keywords          : kbnetwork NT4SP4Fea kbAPI kbSDKPlatform kbWinOS95 kbWinOS98 kbIPHelp kbGrpNet 
Issue type        : kbinfo

Last Reviewed: October 22, 1998