Expand Minimize

FwpsReferenceNetBufferList0 function

The FwpsReferenceNetBufferList0 function increments the reference count for a NET_BUFFER_LIST structure.

Note  FwpsReferenceNetBufferList0 is a specific version of FwpsReferenceNetBufferList. See WFP Version-Independent Names and Targeting Specific Versions of Windows for more information.

Syntax


void NTAPI FwpsReferenceNetBufferList0(
  _Inout_  NET_BUFFER_LIST *netBufferList,
  _In_     BOOLEAN intendToModify
);

Parameters

netBufferList [in, out]

A pointer to the NET_BUFFER_LIST structure for which the reference count is being incremented.

intendToModify [in]

A value that indicates whether a callout intends to modify the cloned network buffer list, whose parent is pointed to by the netBufferList parameter, after the classifyFn function has returned. If TRUE, the callout intends to modify the cloned net buffer list after classifyFn has returned (an out-of-band modification). Otherwise, set to FALSE.

Return value

None.

Remarks

A callout driver calls the FwpsReferenceNetBufferList0 function to increment the reference count for a NET_BUFFER_LIST structure such that the network buffer list remains valid outside of the classifyFn function.

For example, when a callout driver performs packet reassembly, it increments the reference count for each of the received NET_BUFFER_LIST structures that describe the packet fragments that make up an individual packet. This allows the new NET_BUFFER_LIST structure that describes the reassembled packet to safely reference the memory descriptor lists (MDLs) pointed to by the NET_BUFFER_LIST structures that describe the packet fragments. After the callout driver has injected the new NET_BUFFER_LIST structure into the network stack, it decrements the reference count for each of the NET_BUFFER_LIST structures that describe the packet fragments from its packet injection completion routine.

A callout driver must call the FwpsDereferenceNetBufferList0 function for the NET_BUFFER_LIST structure after the callout driver has finished referencing the structure.

Guidelines for Managing Referenced Packets

A callout driver must not hold referenced packets indefinitely. A referenced packet can interfere with power management operations on an idle computer.

The intended use for referenced packets in WFP is to get clarification from a user-mode application or other relatively fast operation. The callout driver must not hold referenced packets while, for example, waiting for user input, web service clearance, or any other operation that might take an arbitrary amount of time.

If the callout driver must wait for a potentially lengthy operation, it should make a deep copy of the packet using FwpsAllocateNetBufferAndNetBufferList0 and block and absorb the original packet.

Another alternative is for the callout driver to listen to query power management, for example by using the I/O request packet (IRP) IRP_MN_QUERY_POWER. When the computer enters sleep or hibernation state, the callout must release any held packets.

Requirements

Version

Available starting with Windows Vista.

Header

Fwpsk.h (include Fwpsk.h)

IRQL

<= DISPATCH_LEVEL

See also

classifyFn
FwpsDereferenceNetBufferList0
NET_BUFFER_LIST

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft