FilterReceiveNetBufferLists

Windows Driver Kit: Network Devices and Protocols

NDIS calls the FilterReceiveNetBufferLists function to request a filter driver to process a receive indication.

VOID
  FilterReceiveNetBufferLists(
    IN NDIS_HANDLE  FilterModuleContext,
    IN PNET_BUFFER_LIST  NetBufferLists,
    IN  NDIS_PORT_NUMBER  PortNumber,
    IN  ULONG  NumberOfNetBufferLists,
    IN  ULONG  ReceiveFlags
    );

Parameters

FilterModuleContext

A handle to the context area for the filter module. The filter driver created and initialized this context area in the FilterAttach function.

NetBufferLists

A linked list of NET_BUFFER_LIST structures that were allocated by underlying drivers. Each NET_BUFFER_LIST structure contains one NET_BUFFER structure.

PortNumber

A port number that identifies a miniport adapter port. Miniport adapter port numbers are assigned by calling the NdisMAllocatePort function. A zero value identifies the default port of a miniport adapter.

NumberOfNetBufferLists

The number of NET_BUFFER_LIST structures that are in the linked list of structures at NetBufferLists.

ReceiveFlags

Flags that define attributes for the send operation. The flags can be combined with an OR operation. To clear all the flags, set this member to zero. This function supports the following flags:

NDIS_RECEIVE_FLAGS_DISPATCH_LEVEL: Specifies that the current IRQL is DISPATCH_LEVEL. For more information about this flag, see Dispatch IRQL Tracking.
NDIS_RECEIVE_FLAGS_RESOURCES: Specifies that NDIS reclaims ownership of the NET_BUFFER_LIST structures and any attached NET_BUFFER structures immediately after the call to FilterReceiveNetBufferLists returns.
NDIS_RECEIVE_FLAGS_SINGLE_ETHER_TYPE: Specifies that all the NET_BUFFER_LIST structures in the list at NetBufferLists have the same protocol type (EtherType).
NDIS_RECEIVE_FLAGS_SINGLE_VLAN: Specifies that all the NET_BUFFER_LIST structures in the list at NetBufferLists belong to the same VLAN.
NDIS_RECEIVE_FLAGS_PERFECT_FILTERED: Specifies that all the NET_BUFFER_LIST structures in the list at NetBufferLists include only data that matches the packet filter and multicast list that are assigned to the miniport adapter.
NDIS_RECEIVE_FLAGS_SINGLE_QUEUE: Specifies that all the NET_BUFFER_LIST structures in the list at NetBufferLists belong to the same VM queue. A miniport driver must set this flag for all receive indications on a queue if the NDIS_RECEIVE_QUEUE_PARAMETERS_PER_QUEUE_RECEIVE_INDICATION flag was set in the Flags member of the NDIS_RECEIVE_QUEUE_PARAMETERS structure when that queue was allocated.
NDIS_RECEIVE_FLAGS_SHARED_MEMORY_INFO_VALID: Specifies that all the NET_BUFFER_LIST structures in the list at NetBufferLists contain shared memory information that is valid. When this flag is set on a received NET_BUFFER_LIST, NDIS treats the shared memory information as valid. When this flag is not set, NDIS and drivers ignore the shared memory information. For example, intermediate drivers that modify packet data can use this flag to determine if data should be copied. Miniport drivers can use the flag to determine how to free the memory that is associated with a VM queue when a queue is deleted.
NDIS_RECEIVE_FLAGS_MORE_NBLS: Reserved.

Return Value

None

Comments

FilterReceiveNetBufferLists is an optional function. If a filter driver does not filter receive indications, it can set the entry point for this function to NULL when it calls the NdisFRegisterFilterDriver function.

Note A filter driver that does provide a FilterReceiveNetBufferLists function must provide a FilterStatus function.

The filter driver can call the NdisSetOptionalHandlers function, from the FilterSetModuleOptions function, to specify a FilterReceiveNetBufferLists function for a filter module.

NDIS calls FilterReceiveNetBufferLists to process receive indications that are initiated by underlying drivers. NDIS can also call this function as a result of loopback.

If the filter driver did not specify a FilterReceiveNetBufferLists function, NDIS calls the next higher filter driver in the stack that did specify a FilterReceiveNetBufferLists function. If there is no such filter driver, NDIS calls an overlying driver's ProtocolReceiveNetBufferLists function.

If the NDIS_RECEIVE_FLAGS_RESOURCES flag in the ReceiveFlags parameter is not set, the filter driver retains ownership of the NET_BUFFER_LIST structures until it calls the NdisFReturnNetBufferLists function.

If the NDIS_RECEIVE_FLAGS_RESOURCES flag in the ReceiveFlags parameter is set, the filter driver cannot keep the NET_BUFFER_LIST structure and associated underlying-driver-allocated resources. This flag can indicate that the underlying driver is running low on receive resources. The FilterReceiveNetBufferLists function should return as quickly as possible. Before returning, the FilterReceiveNetBufferLists function can copy the received data into filter-driver-allocated storage or pass the buffer on by calling the NdisFIndicateReceiveNetBufferLists function.

Note If the NDIS_RECEIVE_FLAGS_RESOURCES flag is set, the filter driver must retain the original set of NET_BUFFER_LIST structures in the linked list. For example, when this flag is set the driver might process the structures and indicate them up the stack one at a time but before the function returns it must restore the original linked list.

Filter drivers can filter received data before indicating the data to overlying drivers. For each buffer that is submitted to its FilterReceiveNetBufferLists function, a filter driver can do the following:

Pass the buffer on to the next overlying driver by calling the NdisFIndicateReceiveNetBufferLists function.
The driver can modify the contents of the buffer before calling NdisFIndicateReceiveNetBufferLists.

The driver can change the NDIS_RECEIVE_FLAGS_RESOURCES flag setting that NDIS passed to FilterReceiveNetBufferLists or simply pass it on to NdisFIndicateReceiveNetBufferLists.
Discard the buffer. If NDIS cleared the NDIS_RECEIVE_FLAGS_RESOURCES flag, call the NdisFReturnNetBufferLists function to discard the buffer. If NDIS set the NDIS_RECEIVE_FLAGS_RESOURCES flag, take no action and return from FilterReceiveNetBufferLists to discard the buffer.
Queue the buffer in a local data structure for later processing. If NDIS set the NDIS_RECEIVE_FLAGS_RESOURCES flag of FilterReceiveNetBufferLists, the filter driver must create a copy before returning from FilterReceiveNetBufferLists.
Copy the buffer and originate a receive indication with the copy. The receive indication is similar to a filter-driver-initiated receive indication. In this case, the driver must return the original buffer to the underlying driver.

If the filter driver called NdisFIndicateReceiveNetBufferLists and did not set the NDIS_RECEIVE_FLAGS_RESOURCES flag, NDIS calls the FilterReturnNetBufferLists function for the filter module. In its FilterReturnNetBufferLists function, the filter driver will undo the operations that it performed on the buffer on the receive indication path.

If a filter module is in the Paused state, the filter driver must not originate any receive indications for that filter module. The filter driver must not pass buffers that it created to NdisFIndicateReceiveNetBufferLists. However, the driver can pass on a receive indication from an underlying driver.

NDIS calls FilterReceiveNetBufferLists at IRQL <= DISPATCH_LEVEL.

Requirements

Versions: Supported for NDIS 6.0 drivers in Windows Vista.

IRQL: <= DISPATCH_LEVEL

Headers: Declared in Ndis.h. Include Ndis.h.

Parameters

Return Value

Comments

Requirements

See Also