FwpsAllocateCloneNetBufferList0 function (fwpsk.h)

Article
10/21/2021

The FwpsAllocateCloneNetBufferList0 function allocates a NET_BUFFER_LIST structure that is a clone of an existing NET_BUFFER_LIST structure.

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

Syntax

NTSTATUS FwpsAllocateCloneNetBufferList0(
  [in, out]      NET_BUFFER_LIST *originalNetBufferList,
  [in, optional] NDIS_HANDLE     netBufferListPoolHandle,
  [in, optional] NDIS_HANDLE     netBufferPoolHandle,
  [in]           ULONG           allocateCloneFlags,
  [out]          NET_BUFFER_LIST **netBufferList
);

Parameters

[in, out] originalNetBufferList

A pointer to the original NET_BUFFER_LIST structure that is being cloned.

[in, optional] netBufferListPoolHandle

A NET_BUFFER_LIST pool handle that was obtained from a previous call to the NdisAllocateNetBufferListPool function. This parameter is optional and can be NULL.

[in, optional] netBufferPoolHandle

A NET_BUFFER pool handle that was obtained from a previous call to the NdisAllocateNetBufferPool function. This parameter is optional and can be NULL.

[in] allocateCloneFlags

There are currently no flags defined for this function. Callout drivers should set this parameter to zero.

[out] netBufferList

A pointer to a variable that receives a pointer to the clone NET_BUFFER_LIST structure.

Return value

The FwpsAllocateCloneNetBufferList0 function returns one of the following NTSTATUS codes.

Return code	Description
STATUS_SUCCESS	The clone NET_BUFFER_LIST structure was successfully allocated.
Other status codes	An error occurred.

Remarks

A callout driver calls the FwpsAllocateCloneNetBufferList0 function to allocate a clone NET_BUFFER_LIST structure of an existing NET_BUFFER_LIST structure.

This function is a wrapper around the NdisAllocateCloneNetBufferList function, but it is specialized for use by WFP packet injection functions.

If the clone NET_BUFFER_LIST structure should have attributes that are associated with a specific pool, the callout driver must specify the pool handle in the NetBufferListPoolHandle or NetBufferPoolHandle parameter. If these parameters are NULL, the default pool preallocated by NDIS is used.

The clone NET_BUFFER_LIST structure describes the same data that is described by the original NET_BUFFER_LIST structure. The FwpsAllocateCloneNetBufferList0 function does not copy the data that is described by the original MDLs to new data buffers. Instead, the clone NET_BUFFER_LIST structure references the original data buffers. The clone NET_BUFFER_LIST structure does not include an initial NET_BUFFER_LIST_CONTEXT structure.

This function sets the ParentNetBufferList member of the newly created clone NET_BUFFER_LIST structure to point to the parent NET_BUFFER_LIST structure. The parent structure's ChildRefCount member is incremented by 1.

A callout driver can modify the clone NET_BUFFER_LIST structure and inject it into the network stack in place of the original NET_BUFFER_LIST structure by calling the packet injection functions. After the data described by the clone NET_BUFFER_LIST structure has been successfully injected into the network stack, the callout driver frees the clone NET_BUFFER_LIST structure by calling the FwpsFreeCloneNetBufferList0 function.

A callout driver can insert or replace individual net buffers (NET_BUFFER) or MDLs inside the clone net buffer list. Such a driver must also undo the modifications before it calls the FwpsFreeCloneNetBufferList0 function.

Guidelines for Managing Cloned Packets

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

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

If the callout driver needs to wait for a potentially lengthy operation, it makes a deep copy of the packet using FwpsAllocateNetBufferAndNetBufferList0, and it blocks and absorbs the original packet.

Callout drivers should always return held packets as quickly as possible.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows Vista.
Target Platform	Universal
Header	fwpsk.h (include Fwpsk.h)
Library	Fwpkclnt.lib
IRQL	<= DISPATCH_LEVEL