GetBestRoute2 (NETIOAPI) (Compact 2013)

  • Article

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)