if_indextoname function

The if_indextoname function converts the local index for a network interface to the ANSI interface name.

Syntax


PCHAR NETIOAPI_API_ if_indextoname(
  _In_   NET_IFINDEX InterfaceIndex,
  _Out_  PCHAR InterfaceName
);

Parameters

InterfaceIndex [in]

The local index for a network interface.

InterfaceName [out]

A pointer to a buffer to hold the NULL-terminated ANSI string. If if_indextoname succeeds, InterfaceName contains the ANSI interface name. The length, in bytes, of the buffer that this parameter points to must be equal to or greater than IF_NAMESIZE. For more information about IF_NAMESIZE, see the following Remarks section.

Return value

If this function succeeds, if_indextoname returns a pointer to a NULL-terminated ANSI string that contains the interface name. If this function fails, if_indextoname returns a NULL pointer

Remarks

The if_indextoname function maps an interface index into its corresponding name. This function is designed as part of basic socket extensions for IPv6, as described by the IETF in RFC 2553.

The if_indextoname function is implemented for portability of drivers with Unix environments, but the ConvertInterfaceXxx functions are the preferred method to convert network interface identifiers. You can replace the if_indextoname function by a call to the ConvertInterfaceIndexToLuid function to convert an interface index to a NET_LUID union, followed by a call to the ConvertInterfaceLuidToNameA function to convert NET_LUID to the ANSI interface name.

The length, in bytes, of the buffer that the InterfaceName parameter points to must be equal or greater than IF_NAMESIZE. The IF_NAMESIZE value is defined in the Netioapi.h header file as equal to NDIS_IF_MAX_STRING_SIZE. The maximum length of an interface name, NDIS_IF_MAX_STRING_SIZE, without the terminating NULL character is declared in the Ntddndis.h header file. The NDIS_IF_MAX_STRING_SIZE is defined to be the IF_MAX_STRING_SIZE constant that is defined in the Ifdef.h header file.

Note  The Ntddndis.h and Ifdef.h header files are automatically included in the Netioapi.h header file. You should never use the Ntddndis.h and Ifdef.h header files directly.

If the if_indextoname function fails and returns a NULL pointer, you cannot determine an error code.

Requirements

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Netioapi.h (include Netioapi.h)

IRQL

PASSIVE_LEVEL

See also

ConvertInterfaceIndexToLuid
ConvertInterfaceLuidToNameA
NET_LUID

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft