GetBestRoute2 function
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 |