RtmGetFirstRoute

[This is preliminary documentation and subject to change.]

The RtmGetFirstRoute function returns the first route from the specified subset of routes in the table.

DWORD RtmGetFirstRoute(
  DWORD   ProtocolFamily,     // type of network (IP or IPX)
  DWORD   EnumerationFlags,   // flags that specify type of criteria
  PVOID   Route               // structure for criteria values and
                              // returned route.
);
 

Parameters

ProtocolFamily

Identifies the protocol family (for example, IP or IPX) of routes to retrieve.

EnumerationFlags

Limits the set of deleted routes to a subset defined by these flags and the values in the corresponding members of the structure pointed to by the CriteriaRoute parameter. The flags are the same as those used in RtmCreateEnumerationHandle.

Route

Points to a protocol-family-specific structure (RTM_IP_ROUTE or RTM_IPX_ROUTE).

The calling function provides member values for this structure. These values in conjunction with the EnumerationFlags parameter, specify the set from which to return routes.

On successful return, this structure receives the first route that matched the specified criteria.

Return Values

NO_ERROR

The first matching route was placed in the structure pointed to by the Route parameter.

ERROR_INVALID_PARAMETER

One or more of the input parameters is invalid (for example, unknown protocol family, or invalid enumeration flags).

ERROR_NO_ROUTES

No routes exist that match the specified criteria.

ERROR_NO_SYSTEM_RESOURCES

Insufficient resources to carry out the operation.

Remarks

The routes are returned in the following order:

1. Network Number
2. Routing Protocol
3. Interface Identifier
4. Next Hop Address

This function is less efficient than the corresponding enumeration handle functions.

QuickInfo

  Windows NT: Use version 5.0 and later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in rtm.h.
  Import Library: Link with rtm.lib.

See Also

RtmCloseEnumerationHandle, RtmCreateEnumerationHandle, RtmEnumerateGetNextRoute, RtmGetNextRoute