GetBestRoute2 (NETIOAPI) (Compact 2013)
3/26/2014
This function retrieves the IP route entry on a local device for the best route to the specified destination IP address.
Syntax
NETIOAPI_API
GetBestRoute2(
IN NET_LUID* InterfaceLuid,
IN NET_IFINDEX InterfaceIndex,
const IN SOCKADDR_INET* SourceAddress,
const IN SOCKADDR_INET* DestinationAddress,
IN ULONG AddressSortOptions,
OUT PMIB_IPFORWARD_ROW2 BestRoute,
OUT SOCKADDR_INET* BestSourceAddress
);
Parameters
- InterfaceLuid
The locally unique identfier (LUID) to specify the network interface that is associated with an IP route entry.
- InterfaceIndex
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
The source IP address. Your driver can omit this parameter and pass a NULL pointer.
- DestinationAddress
The destination IP address.
- AddressSortOptions
A set of options that affect how IP addresses are sorted. This parameter is currently not used.
- BestRoute
A pointer to the MIB_IPFORWARD_ROW2 structure for the best route from the source IP address to the destination IP address.
- BestSourceAddress
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:
Error Code |
Meaning |
---|---|
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 device and an IPv4 address and family was specified in the DestinationAddress parameter, or if no IPv6 stack is located on the local device 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.
See Also
Reference
IP Helper Kernel-Mode Functions
CreateIpForwardEntry2 (NETIOAPI)
DeleteIpForwardEntry2 (NETIOAPI)
GetIpForwardEntry2 (NETIOAPI)
GetIpForwardTable2 (NETIOAPI)
InitializeIpForwardEntry (NETIOAPI)
MIB_IPFORWARD_ROW2
MIB_IPFORWARD_TABLE2
NotifyRouteChange2 (NETIOAPI)
SetIpForwardEntry2 (NETIOAPI)