FILTER_RECEIVE_NET_BUFFER_LISTS callback function (ndis.h)
NDIS calls the FilterReceiveNetBufferLists function to request a filter driver to process a receive indication.
Syntax
FILTER_RECEIVE_NET_BUFFER_LISTS FilterReceiveNetBufferLists;
void FilterReceiveNetBufferLists(
[in] NDIS_HANDLE FilterModuleContext,
[in] PNET_BUFFER_LIST NetBufferLists,
[in] NDIS_PORT_NUMBER PortNumber,
[in] ULONG NumberOfNetBufferLists,
[in] ULONG ReceiveFlags
)
{...}
Parameters
[in] FilterModuleContext
A handle to the context area for the filter module. The filter driver created and initialized this context area in the FilterAttach function.
[in] 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.
[in] 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.
[in] NumberOfNetBufferLists
The number of NET_BUFFER_LIST structures that are in the linked list of structures at NetBufferLists .
[in] ReceiveFlags
Flags that define attributes for the receive indication. 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 address 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.
NDIS_RECEIVE_FLAGS_SWITCH_SINGLE_SOURCE
If this flag is set, all packets in a linked list of NET_BUFFER_LIST structures originated from the same Hyper-V extensible switch source port.
For more information, see Hyper-V Extensible Switch Send and Receive Flags.
NDIS_RECEIVE_FLAGS_SWITCH_DESTINATION_GROUP
If this flag is set, all packets in a linked list of NET_BUFFER_LIST structures are to be forwarded to the same extensible switch destination port.
For more information, see Hyper-V Extensible Switch Send and Receive Flags.
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.
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.
-
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 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.
Examples
To define a FilterReceiveNetBufferLists function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.For example, to define a FilterReceiveNetBufferLists function that is named "MyReceiveNetBufferLists", use the FILTER_RECEIVE_NET_BUFFER_LISTS type as shown in this code example:
FILTER_RECEIVE_NET_BUFFER_LISTS MyReceiveNetBufferLists;
Then, implement your function as follows:
_Use_decl_annotations_
VOID
MyReceiveNetBufferLists(
NDIS_HANDLE FilterModuleContext,
PNET_BUFFER_LIST NetBufferLists,
NDIS_PORT_NUMBER PortNumber,
ULONG NumberOfNetBufferLists,
ULONG ReceiveFlags
)
{...}
The FILTER_RECEIVE_NET_BUFFER_LISTS function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the FILTER_RECEIVE_NET_BUFFER_LISTS function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.
For information about Use_decl_annotations, see Annotating Function Behavior.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Supported in NDIS 6.0 and later. |
Target Platform | Windows |
Header | ndis.h (include Ndis.h) |
IRQL | <= DISPATCH_LEVEL |