Rtnl2SetLogicalRxQueueMulticastFilter

Rtnl2SetLogicalRxQueueMulticastFilter configures the per-queue list of allowed Multicast Addresses for a given Logical Receive Queue.

Syntax

Copy

BOOL Rtnl2SetLogicalRxQueueMulticastFilter(
  [in]    RTNL2_HLOGICAL_RX_QUEUE LogicalRxQueue, 
  [in]    BYTE (*pMulticastAddresses)[6], 
  [in]    ULONG NbMulticastAddresses,
  [in]    ULONG Flags
);

Parameters

[in] LogicalRxQueue

A handle to the Physical Receive Queue.

[in] (pMulticastAddresses)[6]

The address of an array of MAC Addressses containing the list of allowed Multicast Addresses.

[in] NbMulticastAddresses

The count of elements in the pMulticastAddresses array.

[in] Flags

A bitwise OR of these optional flags:

Value	Description
RTNL2_LOGICAL_RX_QUEUE_MULTICAST_FILTER_FLAG_PASS_ALL	Pass all Multicast Addresses instead of filtering based on the pMulticastAddresses array.

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 Physical Rx Queue handle is not valid. pMulticastAddresses is NULL while NbMulticastAddresses is not 0. One of the entries in pMulticastAddresses is not a Multicast Address (both Unicast and Broadcast are rejected). Or Flags has a bit set to 1 which is unknown by this version of the NL2.
ERROR_OUTOFMEMORY	Failed to allocate memory.
RTNL2_ERROR_INCOMPATIBLE_REQUEST	The supplied Flags parameter is not the result of a bitwise OR operation between a set of the supported flags defined above. This may be due to using a new SDK (that defines new flag values) with an old NL2 (that doesn’t know how to interpret those new flags).
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 one thread of the application process was terminated during a previous call to a NL2 API function.
RTNL2_ERROR_SERIALIZED_COMMAND_TIMEOUT	The NL2 process didn’t reply within an acceptable amount of time.
RTNL2_ERROR_TOO_MANY_MULTICAST_ADDRESSES	NbMulticastAddresses contains too many entries (>RTNL2_MULTICAST_FILTER_MAX_ENTRIES).

Remarks

The Logical Receive Multicast filter is one of the following types:

PassAll if the RTNL2_LOGICAL_RX_QUEUE_MULTICAST_FILTER_FLAG_PASS_ALL flag is set
PassNone if the RTNL2_LOGICAL_RX_QUEUE_MULTICAST_FILTER_FLAG_PASS_ALL flag is not set and pMulticastAddresses is NULL
Perfect match otherwise

If the list of received frames of the Logical Receive Queue is not empty when this function is called, the NL2 immediately applies the new Multicast filter on the list. As a result, some frames that were already received may be dropped from the Logical Receive Queue.

Modifying the per-queue list of allowed Multicast Addresses impacts the entire interface, as the Multicast Hash Filter is a per-interface component, not per-queue. For a given interface, the NL2 aggregates all per-queue lists to build the global list of Multicast Addresses allowed to enter into the NIC. This can cause some traffic to enter which may end up in a Physical Receive Queue of another application that may not desire it. That other application then must filter out the undesired packets in software.

Characteristics

Real-time
Deterministic	No
Local memory usage
Process	External MSpace usage	Internal MSpace usage
System	No	No
NL2 process	No	No
Calling process	No	No
Contiguous memory usage
Usage	No

Requirements

Minimum supported version	Header	Library
eRTOS 1.0 SDK	Rtnl2Api.h	Rtnl2Api.lib