if_indextoname (NETIOAPI) (Compact 2013)

  • Article

3/26/2014

This 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_ecount(IF_NAMESIZE) PCHAR  InterfaceName
    );

Parameters

  • InterfaceIndex
    The local index for a network interface.
  • InterfaceName
    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_indextoname returns a pointer to a NULL-terminated ANSI string that contains the interface name if this function succeeds. 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 that have 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 (NETIOAPI) function to convert an interface index to a NET_LUID structure, followed by a call to the ConvertInterfaceLuidToNameA (NETIOAPI) 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.

The Ntddndis.h and Ifdef.h header files are automatically included in the Netioapi.h header file.

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

See Also

Reference

IP Helper Kernel-Mode Functions
ConvertInterfaceIndexToLuid (NETIOAPI)
ConvertInterfaceLuidToNameA (NETIOAPI)
NET_LUID