GetInterfaceInfo (Compact 2013)
3/26/2014
This function obtains a list of the network interface adapters on the local system.
Syntax
DWORD GetInterfaceInfo(
PIP_INTERFACE_INFO pIfTable,
PULONG dwOutBufLen
);
Parameters
- pIfTable
[in, out] Pointer to an IP_INTERFACE_INFO structure that contains the list of adapters. This buffer should be allocated by the caller.
- dwOutBufLen
[out] A pointer to a DWORD variable that specifies the size of the buffer pointed to by pIfTable parameter to receive the IP_INTERFACE_INFO structure. If this size is insufficient to hold the IPv4 interface information, GetInterfaceInfo fills in this variable with the required size, and returns an error code of ERROR_INSUFFICIENT_BUFFER.
Return Value
Return code |
Description |
|---|---|
NO_ERROR |
The function succeeds. |
ERROR_INSUFFICIENT_BUFFER |
The buffer to receive the IPv4 adapter information is too small. This value is returned if the dwOutBufLen parameter indicates that the buffer pointed to by the pIfTable parameter is too small to retrieve the IPv4 interface information. The required size is returned in the DWORD variable pointed to by the dwOutBufLen parameter. |
ERROR_INVALID_PARAMETER |
An invalid parameter was passed to the function. This error is returned if the dwOutBufLen parameter is NULL, or GetInterfaceInfo is unable to write to the memory pointed to by the dwOutBufLen parameter. |
ERROR_NO_DATA |
There are no network adapters enabled for IPv4 on the local system. This value is also returned if all network adapters on the local system are disabled. |
ERROR_NOT_SUPPORTED |
This function is not supported on the operating system that is used on the local system. |
Other |
Use FormatMessage to obtain the message string for the returned error. |
Remarks
The GetInterfaceInfo function is specific to network adapters with IPv4 enabled. The function returns an IP_INTERFACE_INFO structure pointed to by the pIfTable parameter that contains the number of network adapters with IPv4 enabled on the local system and an array of IP_ADAPTER_INDEX_MAP structures with information on each network adapter with IPv4 enabled. The IP_INTERFACE_INFO structure returned by GetInterfaceInfo contains at least one IP_ADAPTER_INDEX_MAP structure even if the NumAdapters member of the IP_INTERFACE_INFO structure indicates that no network adapters with IPv4 are enabled. When the NumAdapters member of the IP_INTERFACE_INFO structure returned by GetInterfaceInfo is zero, the value of the members of the single IP_ADAPTER_INDEX_MAP structure returned in the IP_INTERFACE_INFO structure is undefined.
If the GetInterfaceInfo function is called by using too small a buffer to retrieve the IPv4 interface information (the dwOutBufLen parameter indicates that the buffer pointed to by the pIfTable parameter is too small), the function returns ERROR_INSUFFICIENT_BUFFER. The required size is returned in the DWORD variable pointed to by the dwOutBufLen parameter.
The correct way to use the GetInterfaceInfo function is to call this function twice. In the first call, pass a NULL pointer in the pIfTable parameter and zero in the variable pointed to by the dwOutBufLen parameter. The call will fail with ERROR_INSUFFICIENT_BUFFER and the required size for this buffer is returned in the DWORD variable pointed to by the dwOutBufLen parameter. A buffer can then be allocated of the required size by using the value pointed by the dwOutBufLen. Then the GetInterfaceInfo function can be called again with a pointer to this buffer that is passed in the pIfTable parameter and the length of the buffer set to the size of this buffer.
The GetInterfaceInfo function does not return information about the loopback interface. Information on the loopback interface is returned by the GetIpAddrTable function.
Requirements
Header |
iphlpapi.h |
Library |
Iphlpapi.lib |
See Also
Reference
IP Helper Functions
GetIpAddrTable
GetNumberOfInterfaces
IP_ADAPTER_INDEX_MAP
IP_INTERFACE_INFO