Funzione FwpsAllocateCloneNetBufferList0 (fwpsk.h)

Articolo
02/29/2024

La funzione FwpsAllocateCloneNetBufferList0 alloca una struttura NET_BUFFER_LIST che è un clone di una struttura NET_BUFFER_LIST esistente.

NotaFwpsAllocateCloneNetBufferList0 è una versione specifica di FwpsAllocateCloneNetBufferList. Per altre informazioni, vedere Wfp Version-Independent Names and Targeting Specific Versions of Windows .See WFP Version-Independent Names and Targeting Specific Versions of Windows.See WFP Version-Independent Names and Targeting Specific Versions of Windows for more information.

Sintassi

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
);

Parametri

[in, out] originalNetBufferList

Puntatore alla struttura NET_BUFFER_LIST originale clonata.

[in, optional] netBufferListPoolHandle

Handle del pool di NET_BUFFER_LIST ottenuto da una chiamata precedente all'oggetto Funzione NdisAllocateNetBufferListPool . Questo parametro è facoltativo e può essere NULL.

[in, optional] netBufferPoolHandle

Handle del pool NET_BUFFER ottenuto da una chiamata precedente alla funzione NdisAllocateNetBufferPool . Questo parametro è facoltativo e può essere NULL.

[in] allocateCloneFlags

Attualmente non sono stati definiti flag per questa funzione. I driver di callout devono impostare questo parametro su zero.

[out] netBufferList

Puntatore a una variabile che riceve un puntatore alla struttura di NET_BUFFER_LIST clone.

Valore restituito

La funzione FwpsAllocateCloneNetBufferList0 restituisce uno dei codici NTSTATUS seguenti.

Codice restituito	Descrizione
STATUS_SUCCESS	La struttura di NET_BUFFER_LIST clone è stata allocata correttamente.
Altri codici di stato	Si è verificato un errore.

Commenti

Un driver callout chiama la funzione FwpsAllocateCloneNetBufferList0 per allocare una struttura di clonazione NET_BUFFER_LIST di una struttura di NET_BUFFER_LIST esistente.

Questa funzione è un wrapper intorno a Funzione NdisAllocateCloneNetBufferList , ma è specializzata per l'uso da parte delle funzioni di inserimento di pacchetti WFP.

Se la struttura clone NET_BUFFER_LIST deve avere attributi associati a un pool specifico, il driver del callout deve specificare l'handle del pool nel parametro NetBufferListPoolHandle o NetBufferPoolHandle . Se questi parametri sono NULL, viene usato il pool predefinito preallocato da NDIS.

La struttura clone NET_BUFFER_LIST descrive gli stessi dati descritti dalla struttura di NET_BUFFER_LIST originale. La funzione FwpsAllocateCloneNetBufferList0 non copia i dati descritti dagli ELENCHI di dati originali in nuovi buffer di dati. Al contrario, la struttura clone NET_BUFFER_LIST fa riferimento ai buffer di dati originali. La struttura di NET_BUFFER_LIST clone non include un'inizializzazione NET_BUFFER_LIST_CONTEXT struttura.

Questa funzione imposta il membro ParentNetBufferList della struttura di clonazione appena creata NET_BUFFER_LIST in modo che punti alla struttura NET_BUFFER_LIST padre. Il membro ChildRefCount della struttura padre viene incrementato di 1.

Un driver di callout può modificare la struttura di clonazione NET_BUFFER_LIST e inserirla nello stack di rete al posto della struttura di NET_BUFFER_LIST originale chiamando le funzioni di inserimento dei pacchetti. Dopo che i dati descritti dalla struttura di NET_BUFFER_LIST clone sono stati inseriti correttamente nello stack di rete, il driver callout libera la struttura di clonazione NET_BUFFER_LIST chiamando la funzione FwpsFreeCloneNetBufferList0 .

Un driver di callout può inserire o sostituire singoli buffer net buffer (NET_BUFFER) o MDL all'interno dell'elenco clone net buffer. Tale driver deve anche annullare le modifiche prima di chiamare il Funzione FwpsFreeCloneNetBufferList0 .

Linee guida per la gestione dei pacchetti clonati

Un driver di callout non deve contenere pacchetti clonati per un periodo illimitato. Un pacchetto clonato può interferire con le operazioni di risparmio energia in un computer inattiva.

L'uso previsto per i pacchetti clonati nel WFP consiste nell'ottenere chiarimenti da un'applicazione in modalità utente o da un'altra operazione relativamente veloce. Il driver del callout non deve contenere pacchetti clonati mentre, ad esempio, attende l'input dell'utente o attende l'autorizzazione del servizio Web o attende qualsiasi altra operazione che potrebbe richiedere un periodo di tempo arbitrario.

Se il driver del callout deve attendere un'operazione potenzialmente lunga, esegue una copia completa del pacchetto usando FwpsAllocateNetBufferAndNetBufferList0 e blocca e assorbe il pacchetto originale.

I driver di callout devono sempre restituire pacchetti mantenuti il più rapidamente possibile.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows Vista.
Piattaforma di destinazione	Universale
Intestazione	fwpsk.h (include Fwpsk.h)
Libreria	Fwpkclnt.lib
IRQL	<= DISPATCH_LEVEL