Função NtReadFile (ntifs.h)
A rotina NtReadFile lê dados de um arquivo aberto.
Sintaxe
__kernel_entry NTSYSCALLAPI NTSTATUS NtReadFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[out] PVOID Buffer,
[in] ULONG Length,
[in, optional] PLARGE_INTEGER ByteOffset,
[in, optional] PULONG Key
);
Parâmetros
[in] FileHandle
Manipule para o objeto de arquivo. Esse identificador é criado por uma chamada bem-sucedida para NtCreateFile ou NtOpenFile.
[in, optional] Event
Opcionalmente, um identificador para um objeto de evento a ser definido como o estado sinalizado após a conclusão da operação de leitura. Os drivers intermediários e de dispositivo devem definir esse parâmetro como NULL.
[in, optional] ApcRoutine
Esse parâmetro é reservado. Os drivers intermediários e de dispositivo devem definir esse ponteiro como NULL.
[in, optional] ApcContext
Esse parâmetro é reservado. Os drivers intermediários e de dispositivo devem definir esse ponteiro como NULL.
[out] IoStatusBlock
Ponteiro para uma estrutura de IO_STATUS_BLOCK que recebe a status de conclusão final e informações sobre a operação de leitura solicitada. O membro Information recebe o número de bytes realmente lidos do arquivo.
[out] Buffer
Ponteiro para um buffer alocado pelo chamador que recebe os dados lidos do arquivo.
[in] Length
O tamanho, em bytes, do buffer apontado por Buffer.
[in, optional] ByteOffset
Ponteiro para uma variável que especifica o deslocamento de bytes inicial no arquivo em que a operação de leitura será iniciada. Se for feita uma tentativa de leitura além do final do arquivo, NtReadFile retornará um erro.
Se a chamada para NtCreateFile definir um dos sinalizadores CreateOptions FILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT, o Gerenciador de E/S manterá a posição do arquivo atual. Nesse caso, o chamador de NtReadFile pode especificar que o deslocamento de posição do arquivo atual seja usado em vez de um valor byteOffset explícito. Essa especificação pode ser feita usando um dos seguintes métodos:
- Especifique um ponteiro para um valor LARGE_INTEGER com o membro HighPart definido como -1 e o membro LowPart definido como o valor definido pelo sistema FILE_USE_FILE_POINTER_POSITION.
- Passe um ponteiro NULL para ByteOffset.
O NtReadFile atualiza a posição do arquivo atual adicionando o número de bytes lidos quando conclui a operação de leitura, se estiver usando a posição de arquivo atual mantida pelo Gerenciador de E/S.
Mesmo quando o Gerenciador de E/S está mantendo a posição do arquivo atual, o chamador pode redefinir essa posição passando um valor byteOffset explícito para NtReadFile. Fazer isso altera automaticamente a posição do arquivo atual para esse valor ByteOffset , executa a operação de leitura e atualiza a posição de acordo com o número de bytes realmente lidos. Essa técnica fornece ao chamador um serviço de busca e leitura atômica.
[in, optional] Key
Os drivers intermediários e de dispositivo devem definir esse ponteiro como NULL.
Retornar valor
NtReadFile retorna STATUS_SUCCESS ou o código de erro NTSTATUS apropriado.
Comentários
Os chamadores de NtReadFile já devem ter chamado NtCreateFile com o valor FILE_READ_DATA ou GENERIC_READ definido no parâmetro DesiredAccess .
Se a chamada anterior para NtCreateFile definir o sinalizador FILE_NO_INTERMEDIATE_BUFFERING no parâmetro CreateOptions como NtCreateFile, os parâmetros Length e ByteOffset como NtReadFile deverão ser múltiplos do tamanho do setor.
NtReadFile começa a leitura do ByteOffset fornecido ou da posição do arquivo atual no Buffer fornecido. Ele encerra a operação de leitura em uma das seguintes condições:
- O buffer está cheio porque o número de bytes especificado pelo parâmetro Length foi lido. Portanto, não é possível colocar mais dados no buffer sem um estouro.
- O fim do arquivo é alcançado durante a operação de leitura, portanto, não há mais dados no arquivo a serem transferidos para o buffer.
Se o chamador abriu o arquivo com o sinalizador SYNCHRONIZE definido em DesiredAccess, o thread de chamada poderá ser sincronizado com a conclusão da operação de leitura aguardando o identificador de arquivo , FileHandle. O identificador é sinalizado sempre que uma operação de E/S emitida no identificador é concluída. No entanto, o chamador não deve esperar em um identificador aberto para acesso a arquivos síncronos (FILE_SYNCHRONOUS_IO_NONALERT ou FILE_SYNCHRONOUS_IO_ALERT). Nesse caso, NtReadFile aguarda em nome do chamador e não retorna até que a operação de leitura seja concluída. O chamador poderá aguardar com segurança no identificador do arquivo somente se todas as três condições a seguir forem atendidas:
- O identificador foi aberto para acesso assíncrono (ou seja, nenhum sinalizador FILE_SYNCHRONOUS_IO_XXX foi especificado).
- O identificador está sendo usado para apenas uma operação de E/S por vez.
- NtReadFile retornou STATUS_PENDING.
Um driver deve chamar NtReadFile no contexto do processo do sistema se alguma das seguintes condições existir:
- O driver criou o identificador de arquivo que ele passa para NtReadFile.
- O NtReadFile notificará o driver de conclusão de E/S por meio de um evento que o driver criou.
- O NtReadFile notificará o driver de conclusão de E/S por meio de uma rotina de retorno de chamada de APC que o driver passa para NtReadFile.
Identificadores de arquivo e evento são válidos somente no contexto do processo em que os identificadores são criados. Portanto, para evitar falhas de segurança, o driver deve criar qualquer identificador de arquivo ou evento que ele passe para NtReadFile no contexto do processo do sistema, em vez do contexto do processo em que o driver está.
Da mesma forma, NtReadFile deverá ser chamado no contexto do processo do sistema se ele notificar o driver de conclusão de E/S por meio de um APC, pois as APCs são sempre acionadas no contexto do thread que emite a solicitação de E/S. Se o driver chamar NtReadFile no contexto de um processo diferente do sistema, o APC poderá ser adiado indefinidamente ou não será acionado.
Para obter mais informações sobre como trabalhar com arquivos, consulte Usando arquivos em um driver.
Os chamadores do NtReadFile devem estar em execução em IRQL = PASSIVE_LEVEL e com APCs de kernel especiais habilitadas.
Se a chamada para essa função ocorrer no modo de usuário, você deverá usar o nome "NtReadFile" em vez de "ZwReadFile".
Para chamadas de drivers no modo kernel, as versões NtXxx e ZwXxx de uma rotina dos Serviços do Sistema Nativo do Windows podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Usando versões Nt e Zw das rotinas dos Serviços de Sistema Nativo.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 2000 |
| Plataforma de Destino | Universal |
| Cabeçalho | ntifs.h (inclui Wdm.h, Ntddk.h, Ntifs.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (consulte a seção Comentários) |
| Regras de conformidade de DDI | BufAfterReqCompletedIntIoctlA, BufAfterReqCompletedIoctlA, BufAfterReqCompletedReadA, BufAfterReqCompletedWriteA, HwStorPortProhibitedDDIs, PowerIrpDDis |