GetBestRoute2 function

Article
03/03/2023

The GetBestRoute2 function retrieves the IP route entry on a local computer for the best route to the specified destination IP address.

Syntax

NETIOAPI_API GetBestRoute2(
  _In_opt_       NET_LUID            *InterfaceLuid,
  _In_           NET_IFINDEX         InterfaceIndex,
  _In_opt_ const SOCKADDR_INET       *SourceAddress,
  _In_     const SOCKADDR_INET       *DestinationAddress,
  _In_           ULONG               AddressSortOptions,
  _Out_          PMIB_IPFORWARD_ROW2 BestRoute,
  _Out_          SOCKADDR_INET       *BestSourceAddress
);

Parameters

InterfaceLuid [in, optional]
The locally unique identifier (LUID) to specify the network interface that is associated with an IP route entry.
InterfaceIndex [in]
The local index value to specify the network interface that is associated with an IP route entry. This index value might change when a network adapter is disabled and then enabled, or under other circumstances, so this value does not persistent.
SourceAddress [in, optional]
The source IP address. Your driver can omit this parameter and pass a NULL pointer.
DestinationAddress [in]
The destination IP address.
AddressSortOptions [in]
A set of options that affect how IP addresses are sorted. This parameter is currently not used.
BestRoute [out]
A pointer to the MIB_IPFORWARD_ROW2 structure for the best route from the source IP address to the destination IP address.
BestSourceAddress [out]
A pointer to the best source IP address.

Return value

GetBestRoute2 returns STATUS_SUCCESS if the function succeeds.

If the function fails, GetBestRoute2 returns one of the following error codes:

Return code	Description
STATUS_INVALID_PARAMETER	An invalid parameter was passed to the function. This error is returned if a NULL pointer is passed in the DestinationAddress, BestSourceAddress, or BestRoute parameters. This error is also returned if both InterfaceLuid and InterfaceIndex parameters were unspecified. This error is also returned if the DestinationAddress parameter does not specify an IPv4 or IPv6 address and family
STATUS_NOT_FOUND	The specified interface could not be found. This error is returned if the network interface that the InterfaceLuid or InterfaceIndex parameter specifies could not be found.
STATUS_NOT_SUPPORTED	The request is not supported. This error is returned if no IPv4 stack is located on the local computer and an IPv4 address and family was specified in the DestinationAddress parameter, or if no IPv6 stack is located on the local computer and an IPv4 address and family was specified in the DestinationAddress parameter.
Other	Use the FormatMessage function to obtain the message string for the returned error.

Remarks

The GetBestRoute2 function is used to retrieve a MIB_IPFORWARD_ROW2 structure entry for the best route from a source IP address to a destination IP address.

On input, your driver must initialize the following parameters.

DestinationAddress
Set to a valid IPv4 or IPv6 address and family.
InterfaceLuid or InterfaceIndex
These parameters are used in the order that is listed earlier. So if InterfaceLuid is specified, this parameter is used to determine the interface. If no value was set for the InterfaceLuid member (the value of this parameter was set to zero), the InterfaceIndex parameter is next used to determine the interface.

In addition, on input, your driver can initialize the SourceAddress parameter to the preferred IPv4 or IPv6 address and family.

On output, when the call is successful, GetBestRoute2 retrieves an MIB_IPFORWARD_ROW2 structure for the best route from the source IP address the destination IP address.

Requirements

Target platform	Universal
Version	Available in Windows Vista and later versions of the Windows operating systems.
Header	Netioapi.h (include Netioapi.h)
Library	Netio.lib
IRQL	< DISPATCH_LEVEL