Função FltReadFile (fltkernel.h)
FltReadFile lê dados de um arquivo aberto, fluxo ou dispositivo.
Sintaxe
NTSTATUS FLTAPI FltReadFile(
[in] PFLT_INSTANCE InitiatingInstance,
[in] PFILE_OBJECT FileObject,
[in, optional] PLARGE_INTEGER ByteOffset,
[in] ULONG Length,
[out] PVOID Buffer,
[in] FLT_IO_OPERATION_FLAGS Flags,
[out, optional] PULONG BytesRead,
[in, optional] PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
[in, optional] PVOID CallbackContext
);
Parâmetros
[in] InitiatingInstance
Ponteiro de instância opaca para a instância do driver de minifiltro para a qual a operação deve ser enviada. A instância deve ser anexada ao volume em que o arquivo reside. Esse parâmetro é necessário e não pode ser NULL.
[in] FileObject
Ponteiro para um FILE_OBJECT do arquivo do qual os dados devem ser lidos. Este objeto de arquivo deve estar aberto no momento. Chamar FltReadFile quando o objeto de arquivo ainda não estiver aberto ou não estiver mais aberto (por exemplo, em uma rotina de retorno de chamada pré-criar ou pós-limpeza) faz com que o sistema asserte em um build verificado. Esse parâmetro é necessário e não pode ser NULL.
[in, optional] ByteOffset
Ponteiro para uma variável alocada por chamador que especifica o deslocamento de bytes inicial dentro do arquivo em que a operação de leitura deve começar.
Se byteOffset for especificado, a E/S será executada nesse deslocamento, independentemente do valor atual do campo CurrentByteOffset do objeto de arquivo.
- Se o arquivo foi aberto para E/S síncrono (FO_SYNCHRONOUS_IO é definido no campo sinalizadores do objeto de arquivo), o chamador pode definir ByteOffset->LowPart para FILE_USE_FILE_POINTER_POSITION e >>High Part para -1 executar a E/S no campo CurrentByteOffset do objeto de arquivo. Se o arquivo não tiver sido aberto para E/S síncrona, usar FILE_USE_FILE_POINTER_POSITION será um erro.
Se ByteOffset não for especificado:
- Se o arquivo não foi aberto para E/S síncrona, isso é um erro.
- Caso contrário, a E/S será executada no currentByteOffsetdo objeto de arquivo.
Se o objeto de arquivo foi aberto para E/S síncrona, o campo CurrentByteOffset será atualizado, a menos que o chamador passe o sinalizador FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET.
- Observação: o sistema de arquivos ainda atualiza CurrentByteOffset nesse caso. O Gerenciador de Filtros salva o valor CurrentByteOffset antes de enviar a E/S para baixo na pilha e restaura-a quando a E/S retorna. Da perspectiva do chamador de fltReadFile (e filtros em altitudes mais altas), o CurrrentByteOffset não é atualizado. Mas os filtros abaixo do chamador veem o currentByteOffset atualizado valor em seus retornos de chamada pós-leitura/gravação.
Se o objeto de arquivo não tiver sido aberto para E/S síncrona, o campo CurrentByteOffset não será atualizado independentemente do estado do parâmetro byteOffset.
[in] Length
Tamanho, em bytes, do buffer ao qual o Buffer parâmetro aponta.
[out] Buffer
Ponteiro para um buffer alocado por chamador que recebe os dados lidos do arquivo.
[in] Flags
Máscara de bits de sinalizadores especificando o tipo de operação de leitura a ser executada.
| Bandeira | Significado |
|---|---|
| FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET | Os drivers de minifiltro podem definir esse sinalizador para especificar que FltReadFile não deve atualizar o campo CurrentByteOffset do objeto de arquivo. |
| FLTFL_IO_OPERATION_NON_CACHED | Os drivers de minifiltro podem definir esse sinalizador para especificar uma leitura não em cache, mesmo que o objeto de arquivo não tenha sido aberto com FILE_NO_INTERMEDIATE_BUFFERING. |
| FLTFL_IO_OPERATION_PAGING | Os drivers de minifiltro podem definir esse sinalizador para especificar uma leitura de paginação. |
| FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING | Os drivers de minifiltro podem definir esse sinalizador para especificar uma leitura de E/S de paginação síncrona. Os drivers de minifiltro que definem esse sinalizador também devem definir o sinalizador FLTFL_IO_OPERATION_PAGING. Disponível a partir do Windows Vista. |
[out, optional] BytesRead
Ponteiro para uma variável alocada por chamador que recebe o número de bytes lidos do arquivo. Se CallbackRoutine não for NULL, esse parâmetro será ignorado. Caso contrário, esse parâmetro é opcional e pode ser NULL.
[in, optional] CallbackRoutine
Ponteiro para uma rotina de retorno de chamada PFLT_COMPLETED_ASYNC_IO_CALLBACKtipada para chamar quando a operação de leitura for concluída. Esse parâmetro é opcional e pode ser NULL.
[in, optional] CallbackContext
Ponteiro de contexto a ser passado para o CallbackRoutine se houver um. Esse parâmetro é opcional e pode ser NULL. Se CallbackRoutine for NULL, esse parâmetro será ignorado.
Valor de retorno
fltReadFile retorna o valor NTSTATUS que foi retornado pelo sistema de arquivos.
Observações
Um driver de minifiltro chama FltReadFile para ler dados de um arquivo aberto.
FltReadFile cria uma solicitação de leitura e a envia para as instâncias de driver de minifiltro anexadas abaixo da instância de inicialização e para o sistema de arquivos. A instância especificada e as instâncias anexadas acima não recebem a solicitação de leitura.
FltReadFile executará E/S não em cache se qualquer uma das seguintes opções for verdadeira:
O chamador define o sinalizador FLTFL_IO_OPERATION_NON_CACHED no parâmetro sinalizadores.
O objeto de arquivo foi aberto para E/S não armazenado em cache. Normalmente, isso é feito especificando o sinalizador FILE_NO_INTERMEDIATE_BUFFERING CreateOptions na chamada anterior para FltCreateFile, FltCreateFileExou ZwCreateFile.
A E/S não em cache impõe as seguintes restrições aos valores de parâmetro passados para FltReadFile:
O buffer para o qual o buffer parâmetro deve ser alinhado de acordo com o requisito de alinhamento do dispositivo de armazenamento subjacente. Para alocar esse buffer alinhado, chame FltAllocatePoolAlignedWithTag.
O deslocamento de bytes que o ByteOffset parâmetro aponta deve ser um múltiplo nãonegativo do tamanho do setor do volume.
O comprimento especificado no parâmetro Length deve ser um múltiplo nãonegativo do tamanho do setor do volume.
Se for feita uma tentativa de ler além do final do arquivo, FltReadFile retornará um erro.
Se o valor do parâmetro CallbackRoutine não for NULL, a operação de leitura será executada de forma assíncrona.
Se o valor do parâmetro CallbackRoutine for NULL, a operação de leitura será executada de forma síncrona. Ou seja, fltReadFile aguarda até que a operação de leitura seja concluída antes de retornar. Isso é verdadeiro mesmo se o objeto de arquivo que FileObject aponta para foi aberto para E/S assíncrono.
Se vários threads chamarem FltReadFile para o mesmo objeto de arquivo e o objeto de arquivo tiver sido aberto para E/S síncrona, o Gerenciador de Filtros não tentará serializar a E/S no arquivo. Nesse sentido, FltReadFile difere de ZwReadFile.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Universal |
| cabeçalho | fltkernel.h (inclua Fltkernel.h) |
| biblioteca | FltMgr.lib |
| de DLL | Fltmgr.sys |
| IRQL | PASSIVE_LEVEL |