Função ReadFile (fileapi.h)
Lê dados do arquivo especificado ou do dispositivo de E/S (entrada/saída). As leituras ocorrerão 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 Direitos de Acesso Genéricos e Segurança de Arquivos e Direitos de Acesso.
Para operações de leitura assíncronas, hFile pode ser qualquer identificador aberto com o sinalizador FILE_FLAG_OVERLAPPED pela função CreateFile ou um identificador de soquete retornado pela função socket ou accept .
[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 esta for uma operação assíncrona para evitar resultados potencialmente incorretos.
Esse parâmetro só pode ser NULL quando o parâmetro lpOverlapped não é NULL.
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 OVERLAPPED será necessário se o parâmetro hFile tiver sido aberto com FILE_FLAG_OVERLAPPED, caso contrário, poderá ser NULL.
Se hFile for aberto com FILE_FLAG_OVERLAPPED, o parâmetro lpOverlapped deverá apontar para uma estrutura OVERLAPPED válida e exclusiva, caso contrário, a função poderá relatar incorretamente que a operação de leitura está concluída.
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 Offset e OffsetHigh da estrutura OVERLAPPED . Para um hFile que não dá suporte a deslocamentos de bytes, Offset e OffsetHigh são ignorados.
Para obter mais informações sobre diferentes combinações de lpOverlapped e FILE_FLAG_OVERLAPPED, consulte a seção Comentários e a seção Sincronização e Posição do Arquivo .
Valor retornado
Se a função for bem-sucedida, o valor retornado será diferente de 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 GetLastError.
Comentários
A função ReadFile retorna quando ocorre uma das seguintes condições:
- 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.
- Ocorrerá um erro.
A função ReadFile pode falhar com ERROR_INVALID_USER_BUFFER ou ERROR_NOT_ENOUGH_MEMORY sempre que houver muitas solicitações de E/S assíncronas pendentes.
Para cancelar todas as operações de E/S assíncronas pendentes, use:
- CancelIo: essa função cancela apenas operações emitidas pelo thread de chamada do 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 ReadFile pode falhar com ERROR_NOT_ENOUGH_QUOTA, o que significa que o buffer do processo de chamada não pôde ser bloqueado por página. Para obter informações adicionais, consulte SetProcessWorkingSetSize.
Se parte de um arquivo for bloqueada por outro processo e a operação de leitura sobrepor a 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 Synchronization e File Position 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 a entrada do console. O modo de console determina o comportamento exato da função ReadFile . Por padrão, o modo de console é ENABLE_LINE_INPUT, o que indica que ReadFile deve ser lido até atingir um retorno de carro. Se você pressionar Ctrl+C, a chamada será bem-sucedida, mas GetLastError retornará ERROR_OPERATION_ABORTED. Para obter mais informações, consulte CreateFile.
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 poderão 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 rígidos para trabalhar com êxito com arquivos abertos com CreateFile usando o sinalizador FILE_FLAG_NO_BUFFERING . Para obter detalhes , consulte 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 OVERLAPPED 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 será síncrono. As regras para usar a estrutura OVERLAPPED são ligeiramente diferentes para cada uma, conforme observado anteriormente.- ReadFile pode retornar antes da conclusão da operação de leitura. 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 OVERLAPPED seja definido e redefinido automaticamente pelo sistema, o deslocamento especificado na estrutura 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 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 devem ser modificados, liberados ou reutilizados 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.
- Se lpOverlapped for NULL, a operação de leitura começará na posição atual do arquivo e ReadFile não retornará até que a operação seja concluída e o sistema atualizará o ponteiro do arquivo antes que ReadFile retorne.
- Se lpOverlapped não for NULL, a operação de leitura começará no deslocamento especificado na estrutura OVERLAPPED e ReadFile não retornará até que a operação de leitura seja concluída. O sistema atualiza o deslocamento OVERLAPPED e o ponteiro do arquivo antes que ReadFile retorne.
- 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 for NULL, quando uma operação de leitura síncrona atingir o final de um arquivo, ReadFile retornará FALSE e GetLastError retornará ERROR_HANDLE_EOF.
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 especificar, ReadFile retornará FALSE e GetLastError retornará ERROR_MORE_DATA. O restante da mensagem pode ser lido por uma chamada subsequente para a função ReadFile ou PeekNamedPipe .
Se o parâmetro lpNumberOfBytesRead for zero quando ReadFile retornar TRUE em um pipe, a outra extremidade do pipe chamada função WriteFile com nNumberOfBytesToWrite definido 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 do modo exibição transacionado do arquivo. É garantido que um identificador de leitura transacionado mostre o mesmo modo de exibição de um arquivo por toda duração do identificador. Para obter mais informações, consulte Sobre o NTFS transacional.No Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.
| Tecnologia | Com suporte |
|---|---|
| Protocolo SMB (SMB) 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 Clusterizado (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 Testando para o fim de um arquivo. Para outros exemplos, consulte Criando e usando um arquivo temporário e abrindo um arquivo para leitura ou gravação.
Requisitos
| Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | fileapi.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |