FilterReceiveNetBufferLists (Compact 2013)

3/26/2014

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

Syntax

VOIDS
  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.
  • 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.

Return Value

None

Remarks

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.

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 because 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 keeps 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 it returns, the FilterReceiveNetBufferLists function can copy the received data into filter-driver-allocated storage or pass the buffer on by calling the NdisFIndicateReceiveNetBufferLists function.

Filter drivers can filter received data before they indicate 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 it calls NdisFIndicateReceiveNetBufferLists.
  The driver can change the NDIS_RECEIVE_FLAGS_RESOURCES flag setting that NDIS passed to FilterReceiveNetBufferLists or 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 it returns from FilterReceiveNetBufferLists.
• Copy the buffer and originate a receive indication with the copy. The receive indication resembles 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

See Also

Reference

NDIS Filter Driver Functions
FilterAttach
FilterReturnNetBufferLists
FilterSetModuleOptions
NdisFIndicateReceiveNetBufferLists
NdisFRegisterFilterDriver
NdisFReturnNetBufferLists
NdisSetOptionalHandlers
NET_BUFFER
NET_BUFFER_LIST