FwpsAllocateDeepCloneNetBufferList0 function (fwpsk.h)

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

Syntax

NTSTATUS FwpsAllocateDeepCloneNetBufferList0(
  [in, out]      NET_BUFFER_LIST *originalNetBufferList,
  [in, optional] NDIS_HANDLE     netBufferListPoolHandle,
  [in, optional] NDIS_HANDLE     netBufferPoolHandle,
  [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_LIST pool handle that was obtained from a previous call to the NdisAllocateNetBufferPool function. This parameter is optional and can be NULL.

[out] netBufferList

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

Return value

The FwpsAllocateDeepCloneNetBufferList0 function returns one of the following NTSTATUS codes.

Remarks

A callout driver calls the FwpsAllocateDeepCloneNetBufferList0 function to allocate a deep 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 deep 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 deep clone NET_BUFFER_LIST structure describes the same data that is described by the original NET_BUFFER_LIST structure. The FwpsAllocateDeepCloneNetBufferList0 function copies the data that is described by the original MDLs to new data buffers. The clone NET_BUFFER_LIST structure includes 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 deep clone NET_BUFFER_LIST. The driver must undo these 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 deep cloned packets in WFP is to get clarification from a user-mode application or other relatively fast operation that needs a packet independent of the original. The callout driver must not hold cloned packets while waiting for user input, web service clearance, or any other operation that might take an arbitrary amount of time.

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

Requirements

See also

FwpsFreeCloneNetBufferList0

NET_BUFFER

NET_BUFFER_LIST

NET_BUFFER_LIST_CONTEXT

NdisAllocateNetBufferListPool

NdisAllocateNetBufferPool

Packet injection functions