ProtocolCoReceiveNetBufferLists routine

The ProtocolCoReceiveNetBufferLists function processes receive indications from underlying drivers.

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

Syntax


PROTOCOL_CO_RECEIVE_NET_BUFFER_LISTS ProtocolCoReceiveNetBufferLists;

VOID ProtocolCoReceiveNetBufferLists(
  _In_  NDIS_HANDLE ProtocolBindingContext,
  _In_  NDIS_HANDLE ProtocolVcContext,
  _In_  INPNET_BUFFER_LIST NetBufferLists,
  _In_  ULONG NumberOfNetBufferLists,
  _In_  ULONG ReceiveFlags
)
{ ... }

Parameters

ProtocolBindingContext [in]

A handle to a context area that the protocol driver allocated to maintain state information for a binding. This handle was passed to NDIS in a previous call to NdisOpenAdapterEx.

ProtocolVcContext [in]

A handle to a protocol driver-allocated context area in which this driver maintains the per-virtual connection (VC) run-time state information. A client or stand-alone call manager supplied this handle either when it called the NdisCoCreateVc function or from its ProtocolCoCreateVc function.

NetBufferLists [in]

A linked list of NET_BUFFER_LIST structures that the underlying driver allocated. Each NET_BUFFER_LIST structure is usually associated with one NET_BUFFER structure.

NumberOfNetBufferLists [in]

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

ReceiveFlags [in]

Flags that define attributes for the send operation. The flags can be combined with a bitwise OR operation. To clear all of the flags, set this parameter to zero. ProtocolCoReceiveNetBufferLists supports the following flags:

NDIS_RECEIVE_FLAGS_DISPATCH_LEVEL

The current IRQL is DISPATCH_LEVEL. For more information about this flag, see Dispatch IRQL Tracking.

NDIS_RECEIVE_FLAGS_RESOURCES

NDIS reclaims ownership of the NET_BUFFER_LIST structures and any attached NET_BUFFER structures immediately after the call to ProtocolCoReceiveNetBufferLists returns.

Return value

None

Remarks

The ProtocolCoReceiveNetBufferLists function is required for CoNDIS protocol drivers. NDIS calls ProtocolCoReceiveNetBufferLists after a bound miniport driver calls the NdisMCoIndicateReceiveNetBufferLists function. A call to ProtocolCoReceiveNetBufferLists can also occur as a result of a loopback.

If the NDIS_RECEIVE_FLAGS_RESOURCES flag in the CoReceiveFlags parameter is not set, the protocol driver retains ownership of the NET_BUFFER_LIST structures until it calls the NdisReturnNetBufferLists function. If NDIS sets the NDIS_RECEIVE_FLAGS_RESOURCES flag, the protocol driver cannot retain the NET_BUFFER_LIST structure and associated resources. NDIS_RECEIVE_FLAGS_RESOURCES indicates that an underlying driver has low receive resources. In this case, the ProtocolCoReceiveNetBufferLists function should copy the received data into protocol-allocated storage and return as quickly as possible.

On a multiprocessor system, ProtocolCoReceiveNetBufferLists can run concurrently on more than one processor. In this situation, apply protection (for example, use spin locks) to critical data structures that ProtocolCoReceiveNetBufferLists accesses.

NDIS calls ProtocolCoReceiveNetBufferLists at IRQL<= DISPATCH_LEVEL.

Examples

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


PROTOCOL_CO_RECEIVE_NET_BUFFER_LISTS MyCoReceiveNetBufferLists;

Then, implement your function as follows:


_Use_decl_annotations_
VOID
 MyCoReceiveNetBufferLists(
    NDIS_HANDLE  ProtocolBindingContext,
    NDIS_HANDLE  ProtocolVcContext,
    INPNET_BUFFER_LIST  NetBufferLists,
    ULONG  NumberOfNetBufferLists,
    ULONG  ReceiveFlags
    )
  {...}

The PROTOCOL_CO_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 PROTOCOL_CO_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

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

<= DISPATCH_LEVEL

See also

MiniportReturnNetBufferLists
NdisCoCreateVc
NdisMCoIndicateReceiveNetBufferLists
NdisOpenAdapterEx
NdisReturnNetBufferLists
NET_BUFFER
NET_BUFFER_LIST
ProtocolCoCreateVc
ProtocolCoSendNetBufferListsComplete
CoNDIS Protocol Driver Send and Receive Functions

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft