Função FwpsAllocateCloneNetBufferList0 (fwpsk.h)

Artigo
08/07/2023

A função FwpsAllocateCloneNetBufferList0 aloca uma estrutura NET_BUFFER_LIST que é um clone de uma estrutura NET_BUFFER_LIST existente.

ObservaçãoFwpsAllocateCloneNetBufferList0 é uma versão específica de FwpsAllocateCloneNetBufferList. Consulte Nomes de Version-Independent WFP e Direcionamento de versões específicas do Windows para obter mais informações.

Sintaxe

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

Parâmetros

[in, out] originalNetBufferList

Um ponteiro para a estrutura de NET_BUFFER_LIST original que está sendo clonada.

[in, optional] netBufferListPoolHandle

Um identificador de pool de NET_BUFFER_LIST obtido de uma chamada anterior para o Função NdisAllocateNetBufferListPool . Esse parâmetro é opcional e pode ser NULL.

[in, optional] netBufferPoolHandle

Um identificador de pool de NET_BUFFER obtido de uma chamada anterior para a função NdisAllocateNetBufferPool . Esse parâmetro é opcional e pode ser NULL.

[in] allocateCloneFlags

No momento, não há nenhum sinalizador definido para essa função. Os drivers de texto explicativo devem definir esse parâmetro como zero.

[out] netBufferList

Um ponteiro para uma variável que recebe um ponteiro para o clone NET_BUFFER_LIST estrutura.

Retornar valor

A função FwpsAllocateCloneNetBufferList0 retorna um dos seguintes códigos NTSTATUS.

Código de retorno	Descrição
STATUS_SUCCESS	A estrutura de NET_BUFFER_LIST do clone foi alocada com êxito.
Outros códigos status	Ocorreu um erro.

Comentários

Um driver de texto explicativo chama a função FwpsAllocateCloneNetBufferList0 para alocar um clone NET_BUFFER_LIST estrutura de uma estrutura de NET_BUFFER_LIST existente.

Essa função é um wrapper ao redor do Função NdisAllocateCloneNetBufferList , mas é especializada para uso por funções de injeção de pacote WFP.

Se a estrutura clonar NET_BUFFER_LIST deve ter atributos associados a um pool específico, o driver de texto explicativo deverá especificar o identificador de pool no parâmetro NetBufferListPoolHandle ou NetBufferPoolHandle . Se esses parâmetros forem NULL, o pool padrão pré-alocado pelo NDIS será usado.

A estrutura clone NET_BUFFER_LIST descreve os mesmos dados descritos pela estrutura de NET_BUFFER_LIST original. A função FwpsAllocateCloneNetBufferList0 não copia os dados descritos pelos MDLs originais para novos buffers de dados. Em vez disso, a estrutura clone NET_BUFFER_LIST faz referência aos buffers de dados originais. A estrutura clone NET_BUFFER_LIST não inclui uma inicial NET_BUFFER_LIST_CONTEXT estrutura.

Essa função define o membro ParentNetBufferList da estrutura de NET_BUFFER_LIST clone recém-criada para apontar para a estrutura de NET_BUFFER_LIST pai. O membro ChildRefCount da estrutura pai é incrementado em 1.

Um driver de texto explicativo pode modificar o clone NET_BUFFER_LIST estrutura e injetá-lo na pilha de rede no lugar da estrutura de NET_BUFFER_LIST original chamando as funções de injeção de pacote. Depois que os dados descritos pelo clone NET_BUFFER_LIST estrutura tiverem sido injetados com êxito na pilha de rede, o driver de texto explicativo libera o clone NET_BUFFER_LIST estrutura chamando a função FwpsFreeCloneNetBufferList0 .

Um driver de texto explicativo pode inserir ou substituir buffers de rede individuais (NET_BUFFER) ou MDLs dentro da lista de buffers de rede de clone. Esse driver também deve desfazer as modificações antes de chamar o Função FwpsFreeCloneNetBufferList0 .

Diretrizes para gerenciar pacotes clonados

Um driver de texto explicativo não deve conter pacotes clonados indefinidamente. Um pacote clonado pode interferir nas operações de gerenciamento de energia em um computador ocioso.

O uso pretendido para pacotes clonados no WFP é obter esclarecimentos de um aplicativo no modo de usuário ou de outra operação relativamente rápida. O driver de texto explicativo não deve conter pacotes clonados enquanto, por exemplo, aguardar a entrada do usuário ou aguardar a liberação do serviço Web ou aguardar qualquer outra operação que possa levar um tempo arbitrário.

Se o driver de texto explicativo precisar aguardar uma operação potencialmente longa, ele fará uma cópia profunda do pacote usando FwpsAllocateNetBufferAndNetBufferList0 e bloqueia e absorve o pacote original.

Os drivers de texto explicativo sempre devem retornar pacotes mantidos o mais rápido possível.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows Vista.
Plataforma de Destino	Universal
Cabeçalho	fwpsk.h (inclua Fwpsk.h)
Biblioteca	Fwpkclnt.lib
IRQL	<= DISPATCH_LEVEL