função de retorno de chamada PFLT_PRE_OPERATION_CALLBACK (fltkernel.h)
A rotina de PFLT_PRE_OPERATION_CALLBACK de um driver de minifiltro executa o processamento de pré-operação para operações de E/S.
Sintaxe
PFLT_PRE_OPERATION_CALLBACK PfltPreOperationCallback;
FLT_PREOP_CALLBACK_STATUS PfltPreOperationCallback(
[in, out] PFLT_CALLBACK_DATA Data,
[in] PCFLT_RELATED_OBJECTS FltObjects,
[out] PVOID *CompletionContext
)
{...}
Parâmetros
[in, out] Data
Um ponteiro para a estrutura de dados de retorno de chamada (FLT_CALLBACK_DATA) para a operação de E/S.
[in] FltObjects
Um ponteiro para uma estrutura de FLT_RELATED_OBJECTS que contém ponteiros opacos para os objetos relacionados à solicitação de E/S atual.
[out] CompletionContext
Se essa rotina de retorno de chamada retornar FLT_PREOP_SUCCESS_WITH_CALLBACK ou FLT_PREOP_SYNCHRONIZE, esse parâmetro será um ponteiro de contexto opcional a ser passado para a rotina de retorno de chamada pós-operação correspondente. Caso contrário, ele deverá ser NULL.
Retornar valor
Essa rotina de retorno de chamada retorna um dos seguintes valores de FLT_PREOP_CALLBACK_STATUS.
| Código de retorno | Descrição |
|---|---|
| FLT_PREOP_COMPLETE | O minifiltro está concluindo a operação de E/S. Consulte Comentários para obter detalhes. |
| FLT_PREOP_DISALLOW_FASTIO | A operação é uma operação de E/S rápida e o minifiltro não permite que o caminho de E/S rápido seja usado para essa operação. Consulte Comentários para obter detalhes. |
| FLT_PREOP_PENDING | O minifiltro tem pendente a operação de E/S e a operação ainda está pendente. Consulte Comentários para obter detalhes. |
| FLT_PREOP_SUCCESS_NO_CALLBACK | O minifiltro está retornando a operação de E/S para FltMgr para processamento adicional. Nesse caso, o FltMgr não chamará o retorno de chamada pós-operação do driver de minifiltro, se houver, durante a conclusão de E/S. |
| FLT_PREOP_SUCCESS_WITH_CALLBACK | O minifiltro está retornando a operação de E/S para FltMgr para processamento adicional. Nesse caso, o FltMgr chama o retorno de chamada pós-operação do minifiltro durante a conclusão de E/S. |
| FLT_PREOP_SYNCHRONIZE | O minifiltro está retornando a operação de E/S para o FltMgr para processamento adicional, mas não está concluindo a operação. Consulte Comentários para obter detalhes. |
| FLT_PREOP_DISALLOW_FSFILTER_IO | O minifiltro não está permitindo uma operação queryOpen rápida e forçando a operação pelo caminho lento. Isso faz com que o gerente de E/S ate a solicitação executando uma consulta/fechamento/abertura do arquivo. Os drivers de minifiltro só devem retornar esse status para QueryOpen. |
Comentários
Consulte Gravando rotinas de retorno de chamada pré-operação para obter informações adicionais.
A rotina de retorno de chamada pré-operação de um minifiltro processa um ou mais tipos de operações de E/S. (Essa rotina de retorno de chamada é semelhante a uma rotina de expedição no modelo de filtro herdado.)
Um minifiltro registra uma rotina de retorno de chamada pré-operação para um tipo específico de operação de E/S armazenando o ponto de entrada da rotina de retorno de chamada na matriz OperationRegistration da estrutura FLT_REGISTRATION . O minifiltro passa essa estrutura como um parâmetro para FltRegisterFilter em sua rotina DriverEntry . Um minifiltro pode registrar uma rotina de retorno de chamada pré-operação para um determinado tipo de operação de E/S sem registrar uma rotina de retorno de chamada pós-operação (PFLT_POST_OPERATION_CALLBACK) e vice-versa.
A rotina de retorno de chamada de pré-operação ou pós-operação de um driver de minifiltro pode modificar o conteúdo da estrutura de dados de retorno de chamada para a operação. Se isso acontecer, ele deverá chamar FltSetCallbackDataDirty, a menos que tenha alterado o conteúdo do campo IoStatus da estrutura de dados de retorno de chamada.
O IRQL para essa rotina de retorno de chamada genérica depende de seus caminhos de E/S específicos. Você pode chamar KeGetCurrentIRQL de forma rápida e barata se precisar saber o IRQL atual. Consulte Gravando rotinas de retorno de chamada pré-operação para obter informações adicionais sobre IRQL.
Os sistemas de arquivos arredondam as operações de gravação e leitura no final do arquivo para um múltiplo do tamanho do setor do dispositivo de armazenamento de arquivos subjacente. Ao processar operações de pré-leitura ou pré-gravação, os filtros que alocam e trocam buffers precisam arredondar o tamanho de um buffer alocado até um múltiplo do tamanho do setor do dispositivo associado. Se não o fizerem, o comprimento dos dados transferidos do sistema de arquivos subjacente excederá o comprimento alocado do buffer. Para obter mais informações sobre como trocar buffers, consulte o Exemplo de Minifiltro SwapBuffers.
Começando com Windows 8, CompletionContext usa a anotação Flt_CompletionContext_Outptr que define valores de contexto válidos com base no resultado da operação. Veja a seguir um exemplo de uso para o retorno de chamada com a anotação de CompletionContext.
FLT_PREOP_CALLBACK_STATUS
SwapPreReadBuffers(
_Inout_ PFLT_CALLBACK_DATA Data,
_In_ PCFLT_RELATED_OBJECTS FltObjects,
_Flt_CompletionContext_Outptr_ PVOID *CompletionContext
);
Retornando FLT_PREOP_COMPLETE
Se essa rotina retornar FLT_PREOP_COMPLETE, ela deverá definir o campo IoStatus.Status da estrutura de dados de retorno de chamada como o valor final de NTSTATUS para a operação de E/S. Esse valor NTSTATUS não pode ser STATUS_PENDING. Para uma operação de limpeza ou fechamento, deve ser um valor NTSTATUS de êxito diferente de STATUS_PENDING porque as operações de limpeza e fechamento não podem falhar.
Quando essa rotina retornar FLT_PREOP_COMPLETE, o FltMgr não enviará a operação de E/S para nenhum drivers de minifiltro abaixo do chamador na pilha do driver ou para o sistema de arquivos. Nesse caso, o FltMgr chama apenas as rotinas de retorno de chamada pós-operação dos drivers de minifiltro acima do chamador na pilha de driver.
Retornando FLT_PREOP_DISALLOW_FASTIO
Se essa rotina retornar FLT_PREOP_DISALLOW_FASTIO, ela não deverá definir o campo IoStatus.Status da estrutura de dados de retorno de chamada porque o FltMgr define automaticamente esse campo como STATUS_FLT_DISALLOW_FAST_IO.
FLT_PREOP_DISALLOW_FASTIO só pode ser retornado para uma operação rápida de E/S. Para determinar se uma determinada estrutura de dados de retorno de chamada representa uma operação de E/S rápida, use a macro FLT_IS_FASTIO_OPERATION .
Quando essa rotina retornar FLT_PREOP_DISALLOW_FASTIO, o FltMgr não enviará a operação de E/S rápida para nenhum drivers de minifiltro abaixo do chamador na pilha do driver ou para o sistema de arquivos. Nesse caso, o FltMgr chama apenas as rotinas de retorno de chamada pós-operação dos drivers de minifiltro acima do chamador na pilha de driver.
Retornando FLT_PREOP_PENDING
FLT_PREOP_PENDING só pode ser retornado para operações de E/S baseadas em IRP porque somente operações de E/S baseadas em IRP podem ser pendentes. Para determinar se uma determinada estrutura de dados de retorno de chamada representa uma operação de E/S baseada em IRP, use a macro FLT_IS_IRP_OPERATION .
Quando essa rotina retornar FLT_PREOP_PENDING, o FltMgr não processará ainda mais a operação de E/S até que o driver de minifiltro chame FltCompletePendedPreOperation.
Retornando FLT_PREOP_SYNCHRONIZE
Se a rotina de retorno de chamada pré-operação de um minifiltro retornar FLT_PREOP_SYNCHRONIZE, o minifiltro deverá ter registrado um retorno de chamada pós-operação correspondente para a operação. Quando essa rotina retorna FLT_PREOP_SYNCHRONIZE, o FltMgr chama o retorno de chamada pós-operação do minifiltro no contexto do thread atual em IRQL <= APC_LEVEL.
FLT_PREOP_SYNCHRONIZE só deve ser retornado para operações de E/S baseadas em IRP. Se ele for retornado para uma operação de E/S que não seja uma operação baseada em IRP, o FltMgr tratará esse valor retornado como se fosse FLT_PREOP_SUCCESS_WITH_CALLBACK.
Os drivers de minifiltro não devem retornar FLT_PREOP_SYNCHRONIZE para operações de criação, pois essas operações já estão sincronizadas pelo FltMgr.
Os minifiltros nunca devem retornar FLT_PREOP_SYNCHRONIZE para operações assíncronas de leitura e gravação. Isso pode prejudicar severamente o desempenho do driver de minifiltro e do sistema.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Pacote cumulativo de atualizações do Microsoft Windows 2000 1 para SP4, Windows XP SP2, Windows Server 2003 SP1 e sistemas operacionais Windows posteriores. |
| Plataforma de Destino | Área de Trabalho |
| Cabeçalho | fltkernel.h (inclua FltKernel.h) |
| IRQL | Consulte a seção Comentários |