Função FwpsFlowAssociateContext0 (fwpsk.h)

Artigo
08/07/2023

A função FwpsFlowAssociateContext0 associa um contexto definido pelo driver de texto explicativo a um fluxo de dados.

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

Sintaxe

NTSTATUS FwpsFlowAssociateContext0(
  [in] UINT64 flowId,
  [in] UINT16 layerId,
  [in] UINT32 calloutId,
  [in] UINT64 flowContext
);

Parâmetros

[in] flowId

Um identificador de tempo de execução que especifica o fluxo de dados ao qual associar o contexto. O identificador de tempo de execução de um fluxo de dados é fornecido a um driver de texto explicativo por meio do FWPS_METADATA_FIELD_FLOW_HANDLE valor de metadados que foi passado para a função de texto explicativo classifyFn do driver de texto explicativo.

[in] layerId

O identificador de tempo de execução para a camada de filtragem à qual o contexto está sendo associado. O contexto será associado somente à camada de filtragem especificada. Para obter mais informações, consulte Identificadores de camada de filtragem em tempo de execução.

[in] calloutId

O identificador de tempo de execução para o texto explicativo no mecanismo de filtro. Esse identificador foi retornado quando o driver de texto explicativo chamou a função FwpsCalloutRegister0, FwpsCalloutRegister1 ou FwpsCalloutRegister2 para registrar o texto explicativo com o mecanismo de filtro.

[in] flowContext

O contexto definido pelo driver de texto explicativo a ser associado ao fluxo de dados. Esse parâmetro não deve ser zero. Esse contexto é opaco para o mecanismo de filtro.

Retornar valor

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

Código de retorno	Descrição
STATUS_SUCCESS	O contexto foi associado com êxito ao fluxo de dados.
PARÂMETRO STATUS_INVALID	O parâmetro flowContext é NULL ou o texto explicativo especificado pelo parâmetro calloutID não tem um flowDeleteFn registrado.
STATUS_OBJECT_NAME_EXISTS	Um contexto já está associado ao fluxo de dados. Nesse caso, um driver de texto explicativo deve primeiro chamar a função FwpsFlowRemoveContext0 para remover o contexto existente e, em seguida, chamar a função FwpsFlowAssociateContext0 novamente para associar o novo contexto ao fluxo de dados.
Outros códigos de status	Ocorreu um erro.

Comentários

Ao filtrar um fluxo de dados, um driver de texto explicativo pode chamar a função FwpsFlowAssociateContext0 para associar um contexto ao fluxo de dados. Em seguida, ele pode usar esse contexto para preservar quaisquer dados específicos do driver ou informações de estado entre chamadas pelo mecanismo de filtro para a função de texto explicativo classifyFn de um texto explicativo para esse fluxo de dados.

Deve haver um texto explicativo no mecanismo de filtro na camada identificada pelo parâmetro layerId que registrou uma função de texto explicativo flowDeleteFn . Caso contrário, a chamada para a função FwpsFlowAssociateContext0 retornará STATUS_INVALID_PARAMETER. O mecanismo de filtro chama essa função de texto explicativo flowDeleteFn quando o fluxo é encerrado para que o driver de texto explicativo possa limpo o contexto associado ao fluxo.

Você pode chamar FwpsFlowAssociateContext0 várias vezes para o mesmo fluxo. Em cada chamada, você deve especificar um texto explicativo diferente e um contexto diferente— um contexto por texto explicativo adicionado.

A função FwpsFlowAssociateContext0 associa um único contexto a um único texto explicativo adicionado.

Você pode associar vários contextos a um fluxo. No entanto, cada contexto deve ser associado a um texto explicativo diferente. O novo texto explicativo pode estar na mesma camada que o anterior ou em uma camada diferente.

Para obter mais informações e código de exemplo, consulte Associando contexto a um Fluxo de Dados e o exemplo da plataforma de filtragem do Windows.

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