Rtnl2GetPcpDispatchRules

Rtnl2GetPcpDispatchRules gets the list of PCP dispatch rules currently set up in the interface.

Syntax

Copy 
BOOL Rtnl2GetPcpDispatchRules(
  [in]    RTNL2_HINTERFACE Interface,
  [out]   RTNL2_PCP_DISPATCH_RULE *RulesArray,
  [in]    ULONG RuleStructSize,
  [in]    ULONG NbMaxRules,
  [out]   ULONG *pNbWrittenRules,
  [out]   ULONG *pNbTotalRules
);

Parameters

[in] Interface

A handle to the interface.

[out] RulesArray

The array allocated by the caller.

[in] RuleStructSize

The size of the RTNL2_PCP_DISPATCH_RULE structure.

[in] NbMaxRules

The maximum number of rules the function can write in RulesArray.

[out] pNbWrittenRules

The number of rules that the function could fit into the array.

[out] pNbTotalRules

The total number of rules in the interface.

Return Value

If the function succeeds, it returns TRUE. If the function fails, it returns FALSE. Call GetLastError to obtain an error code.

Possible error codes:

Error code Meaning

ERROR_NOT_READY

The calling process has not called Rtnl2Init.

ERROR_INVALID_PARAMETER

One of the following conditions occurred:

  • The supplied interface handle is invalid.
  • NbMaxRules is a nonzero value while RulesArray is NULL.
  • NbMaxRules is a nonzero value while pNbWrittenRules is NULL.

RTNL2_ERROR_SERIALIZED_COMMAND_TIMEOUT

The NL2 process didn’t reply within an acceptable delay.

RTNL2_ERROR_NO_MORE_COMMUNICATION

Unable to communicate with the NL2 process. This might be because the NL2 process is not running anymore, or because an application process thread was terminated during a previous call to an NL2 API function.

Remarks

The caller MUST set RuleStructSize to sizeof(RTNL2_LINK_STATUS) to ensure backward and forward compatibility.

The caller SHOULD provide an array with a length equal to the maximum number of PCP rules supported by this interface (see Rtnl2GetInterfaceFeatures and PcpDispatchRulesCount in RTNL2_INTERFACE_FEATURES). Otherwise, there is a risk that the function does not return all the rules currently set. To know whether all the set rules have been returned, the caller can check whether the value pointed by pNbWrittenRules equals the value pointed by pNbTotalRules.

If the caller sets RulesArray to NULL and NbMaxRules to zero, the function will not write any rules. Instead, it will return the total number of currently set rules in pTotalRules. While rules can be dynamically added and deleted by other threads, there is no guarantee that a second call to Rtnl2GetPcpDispatchRules will return the same number of total rules.

Characteristics

Real-time

Deterministic

No

Shutdown-safe

No
Local memory usage

Process

External MSpace usage

Internal MSpace usage

System

No

No

NL2 process

No

No

Calling process

No

No
Windows contiguous memory usage

Usage

No

Requirements

Minimum supported version Header Library

wRTOS 1.0 SDK

Rtnl2Api.h

Rtnl2Api.lib

See Also: