Função ReadFile (fileapi.h)
Lê dados do arquivo ou dispositivo de E/S (entrada/saída) especificado. As leituras ocorrem na posição especificada pelo ponteiro do arquivo, se houver suporte para o dispositivo.
Essa função foi projetada para operações síncronas e assíncronas. Para uma função semelhante projetada exclusivamente para operação assíncrona, consulte ReadFileEx .
Sintaxe
BOOL ReadFile(
[in] HANDLE hFile,
[out] LPVOID lpBuffer,
[in] DWORD nNumberOfBytesToRead,
[out, optional] LPDWORD lpNumberOfBytesRead,
[in, out, optional] LPOVERLAPPED lpOverlapped
);
Parâmetros
[in] hFile
Um identificador para o dispositivo (por exemplo, um arquivo, fluxo de arquivos, disco físico, volume, buffer de console, unidade de fita, soquete, recurso de comunicação, emaillot ou pipe).
O parâmetro hFile deve ter sido criado com acesso de leitura. Para obter mais informações, consulte de direitos de acesso genéricos e de direitos de acesso e segurança de arquivos.
Para operações de leitura assíncronas,
[out] lpBuffer
Um ponteiro para o buffer que recebe os dados lidos de um arquivo ou dispositivo.
Esse buffer deve permanecer válido durante a operação de leitura. O chamador não deve usar esse buffer até que a operação de leitura seja concluída.
[in] nNumberOfBytesToRead
O número máximo de bytes a serem lidos.
[out, optional] lpNumberOfBytesRead
Um ponteiro para a variável que recebe o número de bytes lidos ao usar um parâmetro hFile síncrono. ReadFile define esse valor como zero antes de fazer qualquer verificação de erro ou trabalho. Use NULL para esse parâmetro se essa for uma operação assíncrona para evitar resultados potencialmente incorretos.
Esse parâmetro pode ser
Windows 7: Esse parâmetro não pode ser NULL.
Para obter mais informações, consulte a seção Comentários.
[in, out, optional] lpOverlapped
Um ponteiro para uma estrutura de
Se
Para um hFile que dá suporte a deslocamentos de bytes, se você usar esse parâmetro, deverá especificar um deslocamento de bytes no qual iniciar a leitura do arquivo ou dispositivo. Esse deslocamento é especificado definindo os membros
Para obter mais informações sobre diferentes combinações de
Valor de retorno
Se a função for bem-sucedida, o valor retornado não será zero (TRUE).
Se a função falhar ou estiver sendo concluída de forma assíncrona, o valor retornado será zero (FALSE). Para obter informações de erro estendidas, chame a função
Nota
O código
Observações
A função
- O número de bytes solicitados é lido.
- Uma operação de gravação é concluída na extremidade de gravação do pipe.
- Um identificador assíncrono está sendo usado e a leitura está ocorrendo de forma assíncrona.
- Ocorre um erro.
A função
Para cancelar todas as operações de E/S assíncronas pendentes, use:
- CancelIo: essa função cancela apenas as operações emitidas pelo thread de chamada para o identificador de arquivo especificado.
- CancelIoEx: essa função cancela todas as operações emitidas pelos threads para o identificador de arquivo especificado.
Use CancelSynchronousIo para cancelar operações de E/S síncronas pendentes.
As operações de E/S canceladas são concluídas com o erro ERROR_OPERATION_ABORTED.
A função
Se parte de um arquivo for bloqueada por outro processo e a operação de leitura se sobrepor à parte bloqueada, essa função falhará.
Acessar o buffer de entrada enquanto uma operação de leitura estiver usando o buffer pode levar à corrupção dos dados lidos nesse buffer. Os aplicativos não devem ler, gravar, realocar ou liberar o buffer de entrada que uma operação de leitura está usando até que a operação de leitura seja concluída. Isso pode ser particularmente problemático ao usar um identificador de arquivo assíncrono. Informações adicionais sobre identificadores de arquivo síncronos versus assíncronos podem ser encontradas na seção Sincronização e Posição do Arquivo e no tópico de referência CreateFile.
Os caracteres podem ser lidos do buffer de entrada do console usando ReadFile com um identificador para entrada do console. O modo de console determina o comportamento exato da função
Ao ler de um dispositivo de comunicação, o comportamento de ReadFile é determinado pelo tempo limite de comunicação atual como definido e recuperado usando as funções SetCommTimeouts e GetCommTimeouts. Resultados imprevisíveis podem ocorrer se você não definir os valores de tempo limite. Para obter mais informações sobre tempos limite de comunicação, consulte COMMTIMEOUTS.
Se ReadFile tentar ler de um emaillot que tenha um buffer muito pequeno, a função retornará FALSE e GetLastError retornará ERROR_INSUFFICIENT_BUFFER.
Há requisitos estritos para trabalhar com êxito com arquivos abertos com CreateFile usando o sinalizador FILE_FLAG_NO_BUFFERING. Para obter detalhes, consultede Buffer de Arquivos
Se hFile foi aberto com FILE_FLAG_OVERLAPPED, as seguintes condições estão em vigor:
- O parâmetro
lpOverlapped deve apontar para uma estrutura deOVERLAPPED válida e exclusiva; caso contrário, a função pode relatar incorretamente que a operação de leitura está concluída. - O parâmetro lpNumberOfBytesRead
deve ser definido como NULL. Use a função GetOverlappedResult para obter o número real de bytes lidos. Se o parâmetro hFile estiver associado a uma porta de conclusão de E/S, você também poderá obter o número de bytes lidos chamando a função GetQueuedCompletionStatus.
Sincronização e posição do arquivo
Se hFile for aberto com FILE_FLAG_OVERLAPPED, ele será um identificador de arquivo assíncrono; caso contrário, ele é síncrono. As regras para usar a estrutura de
Nota
Se um arquivo ou dispositivo for aberto para E/S assíncrona, chamadas subsequentes para funções como ReadFile usando esse identificador geralmente retornarão imediatamente, mas também poderão se comportar de forma síncrona em relação à execução bloqueada. Para obter mais informações, consulte E/S de disco assíncrono aparece como síncrona no Windows.
Considerações para trabalhar com identificadores de arquivo assíncronos:
-
ReadFile pode retornar antes que a operação de leitura seja concluída. Nesse cenário,
ReadFile retorna FALSE e a função GetLastError retorna ERROR_IO_PENDING , o que permite que o processo de chamada continue enquanto o sistema conclui a operação de leitura. - O parâmetro lpOverlapped
não deve ser NULL e deve ser usado com os seguintes fatos em mente: - Embora o evento especificado na estrutura de
OVERLAPPED seja definido e redefinido automaticamente pelo sistema, o deslocamento especificado na estrutura de OVERLAPPED não é atualizado automaticamente. - ReadFile redefine o evento para um estado não atribuído quando ele inicia a operação de E/S.
- O evento especificado na estrutura OVERLAPPED é definido como um estado sinalizado quando a operação de leitura é concluída; até esse momento, a operação de leitura é considerada pendente.
- Como a operação de leitura começa no deslocamento especificado na estrutura de
OVERLAPPED e readFile pode retornar antes que a operação de leitura no nível do sistema seja concluída (leitura pendente), nem o deslocamento nem qualquer outra parte da estrutura deve ser modificado, liberado ou reutilizado pelo aplicativo até que o evento seja sinalizado (ou seja, a leitura é concluída). - Se o EOF (fim do arquivo) for detectado durante operações assíncronas, a chamada para GetOverlappedResult para essa operação retornará FALSE e GetLastError retornará ERROR_HANDLE_EOF.
- Embora o evento especificado na estrutura de
Considerações para trabalhar com identificadores de arquivo síncronos:
- Se lpOverlapped for NULL, a operação de leitura será iniciada na posição do arquivo atual e ReadFile não retornará até que a operação seja concluída e o sistema atualizará o ponteiro de arquivo antes de readFile retornar.
- Se
lpOverlapped não for NULL, a operação de leitura será iniciada no deslocamento especificado na estrutura de OVERLAPPED e ReadFile não retornará até que a operação de leitura seja concluída. O sistema atualiza o deslocamento de OVERLAPPED e o ponteiro de arquivo antes de ReadFile retorna. - Se lpOverlapped for NULL, quando uma operação de leitura síncrona atingir o final de um arquivo, readFile retornará TRUE e definirá
*lpNumberOfBytesReadcomo zero. - Se lpOverlapped não estiver NULL, quando uma operação de leitura síncrona atingir o final de um arquivo, ReadFile retornará FALSE e GetLastError retornará ERROR_HANDLE_EOF.
Para obter mais informações, consulte CreateFile e de E/S síncrona e assíncrona.
Tubos
Se um pipe anônimo estiver sendo usado e o identificador de gravação tiver sido fechado, quando ReadFile tentar ler usando o identificador de leitura correspondente do pipe, a função retornará FALSE e GetLastError retornará ERROR_BROKEN_PIPE.
Se um pipe nomeado estiver sendo lido no modo de mensagem e a próxima mensagem for maior do que o parâmetro nNumberOfBytesToRead
Se o parâmetro lpNumberOfBytesRead for zero quando ReadFile retornar verdadeiro em um pipe, a outra extremidade do pipe chamada função WriteFile com nNumberOfBytesToWrite definida como zero.
Para obter mais informações sobre pipes, consulte Pipes.
Operações transacionadas
Se houver uma transação associada ao identificador de arquivo, a função retornará dados da exibição transacionada do arquivo. Um identificador de leitura transacionado tem a garantia de mostrar a mesma exibição de um arquivo durante a alça. Para obter mais informações, consulte Sobre o NTFS transacional.
No Windows 8 e no Windows Server 2012, essa função é compatível com as tecnologias a seguir.
| Tecnologia | Suportado |
|---|---|
| Protocolo SMB (Bloco de Mensagens do Servidor) 3.0 | Sim |
| TFO (Failover Transparente) do SMB 3.0 | Sim |
| SMB 3.0 com Compartilhamentos de Arquivos de Expansão (SO) | Sim |
| Sistema de Arquivos de Volume Compartilhado de Cluster (CsvFS) | Sim |
| ReFS (Sistema de Arquivos Resiliente) | Sim |
Exemplos
Para obter um exemplo de código que mostra como testar o fim do arquivo, consulte Testing for the End of a File. Para obter outros exemplos, consulte Criando e usando um arquivo temporário e abrindo um arquivo para leitura ou gravação.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | fileapi.h (inclua Windows.h) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |
Consulte também
cancelio
Funções de gerenciamento de arquivos
setCommTimeouts