Função FltLockUserBuffer (fltkernel.h)

Artigo
07/16/2024

A rotina FltLockUserBuffer bloqueia o buffer de usuário para uma determinada operação de E/S.

Sintaxe

NTSTATUS FLTAPI FltLockUserBuffer(
  [in] PFLT_CALLBACK_DATA CallbackData
);

Parâmetros

[in] CallbackData

Ponteiro para a estrutura de dados de retorno de chamada FLT_CALLBACK_DATA para a operação de E/S.

Valor de retorno

FltLockUserBuffer retornará STATUS_SUCCESS se bloquear com êxito o buffer de usuário (ou se o buffer já estiver bloqueado por uma chamada anterior para FltLockUserBuffer.) Caso contrário, ele retornará um valor NTSTATUS apropriado, como um dos seguintes:

Código de retorno	Descrição
STATUS_INSUFFICIENT_RESOURCES	fltLockUserBuffer encontrou uma falha de alocação de pool. Este é um código de erro.
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi encontrado. Por exemplo, a operação de E/S não tem um parâmetro MDL ou as operações de E/S IRP_MJ_READ ou IRP_MJ_WRITE têm um código secundário de IRP_MN_MDL. Este é um código de erro.

Observações

Para obter melhor desempenho, os drivers de filtro não devem chamar FltLockUserBuffer, a menos que seja absolutamente necessário. A desaceleração do desempenho não ocorre devido a FltLockUserBuffer em si, mas sim devido à penalidade de desempenho incorrida pela chamada subsequente para MmGetSystemAddressForMdlSafe ; consulte comentários posteriores para obter mais informações.

Um driver de minifiltro pode chamar FltLockUserBuffer para bloquear o buffer de usuário para uma das seguintes operações de E/S:

IRP_MJ_DEVICE_CONTROL
IRP_MJ_DIRECTORY_CONTROL
IRP_MJ_FILE_SYSTEM_CONTROL
IRP_MJ_INTERNAL_DEVICE_CONTROL
IRP_MJ_QUERY_EA
IRP_MJ_QUERY_QUOTA
IRP_MJ_QUERY_SECURITY
IRP_MJ_READ (exceto com IRP_MN_MDL)
IRP_MJ_SET_EA
IRP_MJ_SET_QUOTA
IRP_MJ_WRITE (exceto com IRP_MN_MDL)

FltLockUserBuffer determina o método de acesso apropriado (IoReadAccess, IoWriteAccess ou IoModifyAccess) a ser aplicado ao buffer bloqueado com base no tipo de operação de E/S.

fltLockUserBuffer define o membro MdlAddress (ou OutputMdlAddress) na estrutura do parâmetro de dados de retorno de chamada (FLT_PARAMETERS) para apontar para o MDL para as páginas bloqueadas. Se não houver MDL, FltLockUserBuffer alocará um. (Observe que o FltMgr não pode gerar um MDL antes do sistema de arquivos, e é por isso que FltLockUserBuffer retorna STATUS_INVALID_PARAMETER para IRP_MJ_READ ou IRP_MJ_WRITE com IRP_MN_MDL).

Se a estrutura do parâmetro de dados de retorno de chamada contiver um buffer do sistema (Irp->AssociatedIrp.SystemBuffer) e não contiver um buffer de usuário (Irp->UserBuffer), FltLockUserBuffer bloqueará o buffer do sistema. Se não houver MDL para o buffer do sistema, FltLockUserBuffer alocará um.

Se a estrutura de parâmetros de dados de retorno de chamada contiver um buffer de usuário, FltLockUserBufferinvestigações e bloqueios buffer do usuário.

O chamador pode estar em execução em qualquer contexto de processo. FltLockUserBuffer bloqueia automaticamente o buffer no contexto de processo correto.

Se FltLockUserBuffer for chamado de uma rotina de retorno de chamada pré-operação (PFLT_PRE_OPERATION_CALLBACK) e alocar um MDL, FltLockUserBuffer definirá o sinalizador de FLTFL_CALLBACK_DATA_DIRTY na estrutura de dados de retorno de chamada (FLT_CALLBACK_DATA) para que o sistema de E/S libere o MDL quando a operação de E/S for concluída.

Para conservar PTEs (entradas de tabela de página do sistema), FltLockUserBuffer não mapeia as páginas bloqueadas. Depois de chamar FltLockUserBuffer, o chamador deve chamar membro MmGetSystemAddressForMdlSafe, passando o membro MdlAddress (ou OutputMdlAddress) na estrutura de parâmetros de dados de retorno de chamada como o valor do parâmetro Mdl, para obter um buffer do sistema que representa essa memória.

Quando a estrutura de dados de retorno de chamada é liberada, o buffer bloqueado é desbloqueado automaticamente e o MDL é liberado. O chamador nunca deve liberar o MDL; o sistema de E/S faz isso automaticamente.

fltLockUserBuffer pode ser chamado para operações rápidas baseadas em E/S e IRP.