FILTER_CANCEL_SEND_NET_BUFFER_LISTS callback function (ndis.h)

Article
10/21/2021

NDIS calls a filter driver's FilterCancelSendNetBufferLists function to cancel the transmission of all NET_BUFFER_LIST structures that are marked with a specified cancellation identifier.

Note You must declare the function by using the FILTER_CANCEL_SEND_NET_BUFFER_LISTS type. For more information, see the following Examples section.

Syntax

FILTER_CANCEL_SEND_NET_BUFFER_LISTS FilterCancelSendNetBufferLists;

void FilterCancelSendNetBufferLists(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PVOID CancelId
)
{...}

Parameters

[in] FilterModuleContext

A handle to a context area that the filter driver allocated in its FilterAttach function. The filter driver uses this context area to maintain state information for a filter module.

[in] CancelId

A cancellation identifier. This identifier specifies the NET_BUFFER_LIST structures that are being canceled.

Return value

None

Remarks

The FilterCancelSendNetBufferLists function is optional. If a filter driver does not filter send requests, it can set the entry point for this function to NULL when it calls the NdisFRegisterFilterDriver function.

Filter drivers that queue NET_BUFFER_LIST structures before sending should export a FilterCancelSendNetBufferLists function. The FilterCancelSendNetBufferLists function cancels the pending transmission of the specified NET_BUFFER_LIST structures.

When an overlying NDIS driver calls the NdisCancelSendNetBufferLists or NdisFCancelSendNetBufferLists function, NDIS calls the FilterCancelSendNetBufferLists function of the filter modules on the binding.

A filter driver's FilterCancelSendNetBufferLists function performs the following operations:

Traverses its list of queued NET_BUFFER_LIST structures for the specified filter module and calls the NDIS_GET_NET_BUFFER_LIST_CANCEL_ID macro to obtain the cancellation identifier for each queued NET_BUFFER_LIST structure. The filter driver compares the cancellation ID that NDIS_GET_NET_BUFFER_LIST_CANCEL_ID returns with the cancellation ID that NDIS passed to FilterCancelSendNetBufferLists.
Removes from the send queue (unlinks) all NET_BUFFER_LIST structures whose cancellation identifiers match the specified cancellation identifier.
Calls the NdisFSendNetBufferListsComplete function for all unlinked NET_BUFFER_LIST structures to return the structures. The filter driver sets the status field of the NET_BUFFER_LIST structures to NDIS_STATUS_SEND_ABORTED.
Calls the NdisFCancelSendNetBufferLists function to pass the cancel send request to underlying drivers.

NDIS calls FilterCancelSendNetBufferLists at IRQL <= DISPATCH_LEVEL.

Examples

To define a FilterCancelSendNetBufferLists 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 FilterCancelSendNetBufferLists function that is named "MyCancelSendNetBufferLists", use the FILTER_CANCEL_SEND_NET_BUFFER_LISTS type as shown in this code example:

FILTER_CANCEL_SEND_NET_BUFFER_LISTS MyCancelSendNetBufferLists;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyCancelSendNetBufferLists(
    NDIS_HANDLE  FilterModuleContext,
    PVOID  CancelId
    )
  {...}

The FILTER_CANCEL_SEND_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_CANCEL_SEND_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