Função ReadFileEx (fileapi.h)
Lê dados do arquivo especificado ou do dispositivo de E/S (entrada/saída). Relata o status de conclusão de forma assíncrona, chamando a rotina de conclusão especificada quando a leitura é concluída ou cancelada e o thread de chamada está em um estado de espera de alerta.
Para ler dados de um arquivo ou dispositivo de forma síncrona, use a função ReadFile .
Sintaxe
BOOL ReadFileEx(
[in] HANDLE hFile,
[out, optional] LPVOID lpBuffer,
[in] DWORD nNumberOfBytesToRead,
[in, out] LPOVERLAPPED lpOverlapped,
[in] LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
Parâmetros
[in] hFile
Um identificador para o arquivo ou dispositivo de E/S (por exemplo, um arquivo, fluxo de arquivos, disco físico, volume, buffer de console, unidade de fita, soquete, recurso de comunicação, maillot ou pipe).
Esse parâmetro 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 .
Esse identificador também deve ter o acesso de GENERIC_READ correto. Para obter mais informações sobre direitos de acesso, consulte Segurança de arquivos e direitos de acesso.
[out, optional] lpBuffer
Um ponteiro para um buffer que recebe os dados lidos do arquivo ou dispositivo.
Esse buffer deve permanecer válido durante a operação de leitura. O aplicativo não deve usar esse buffer até que a operação de leitura seja concluída.
[in] nNumberOfBytesToRead
O número de bytes a serem lidos.
[in, out] lpOverlapped
Um ponteiro para uma estrutura de dados OVERLAPPED que fornece dados a serem usados durante a operação de leitura de arquivo assíncrona (sobreposta).
Para arquivos que dão suporte a deslocamentos de bytes, você deve especificar um deslocamento de bytes no qual iniciar a leitura do arquivo. Especifique esse deslocamento definindo os membros Offset e OffsetHigh da estrutura OVERLAPPED . Para arquivos ou dispositivos que não dão suporte a deslocamentos de bytes, Offset e OffsetHigh são ignorados.
A função ReadFileEx ignora o membro hEvent da estrutura OVERLAPPED. Um aplicativo é gratuito para usar esse membro para suas próprias finalidades no contexto de uma chamada ReadFileEx . ReadFileEx sinaliza a conclusão de sua operação de leitura chamando ou enfileirando uma chamada para a rotina de conclusão apontada por lpCompletionRoutine, portanto, ela não precisa de um identificador de evento.
A função ReadFileEx usa os membros Internal e InternalHigh da estrutura OVERLAPPED. Um aplicativo não deve definir esses membros.
A estrutura de dados OVERLAPPED deve permanecer válida durante a operação de leitura. Não deve ser uma variável que possa sair do escopo enquanto a operação de leitura estiver pendente de conclusão.
[in] lpCompletionRoutine
Um ponteiro para a rotina de conclusão a ser chamada quando a operação de leitura for concluída e o thread de chamada estiver em um estado de espera alertável. Para obter mais informações sobre a rotina de conclusão, consulte FileIOCompletionRoutine.
Valor retornado
Se a função for bem-sucedida, o valor retornado será diferente de zero.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Se a função for bem-sucedida, o thread de chamada terá uma operação de E/S assíncrona pendente: a operação de leitura sobreposta do arquivo. Quando essa operação de E/S é concluída e o thread de chamada é bloqueado em um estado de espera alertável, o sistema chama a função apontada por lpCompletionRoutine e o estado de espera é concluído com um código de retorno de WAIT_IO_COMPLETION.
Se a função for bem-sucedida e a operação de leitura de arquivo for concluída, mas o thread de chamada não estiver em um estado de espera alertável, o sistema enfileirará a chamada de rotina de conclusão, mantendo a chamada até que o thread de chamada insira um estado de espera alertável. Para obter informações sobre esperas alertáveis e operações de entrada/saída sobrepostas, consulte Sobre sincronização.
Se ReadFileEx tentar ler além do EOF (fim do arquivo), a chamada para GetOverlappedResult para essa operação retornará FALSE e GetLastError retornará ERROR_HANDLE_EOF.
Comentários
Ao usar ReadFileEx, você deve marcar GetLastError mesmo quando a função retorna "êxito" para marcar para condições que são "êxitos", mas têm algum resultado que talvez você queira saber. Por exemplo, um estouro de buffer ao chamar ReadFileEx retornará TRUE, mas GetLastError relatará o estouro com ERROR_MORE_DATA. Se a chamada de função for bem-sucedida e não houver condições de aviso, GetLastError retornará ERROR_SUCCESS.
A função ReadFileEx poderá falhar se houver muitas solicitações de E/S assíncronas pendentes. No caso de uma falha desse tipo, GetLastError pode retornar ERROR_INVALID_USER_BUFFER ou ERROR_NOT_ENOUGH_MEMORY.
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.
As operações de E/S canceladas são concluídas com o erro ERROR_OPERATION_ABORTED.
Se parte do arquivo especificado por hFile for bloqueada por outro processo e a operação de leitura especificada em uma chamada para ReadFileEx sobrepor a parte bloqueada, a chamada para ReadFileEx falhará.
Ao tentar ler dados de um maillot cujo buffer é muito pequeno, ReadFileEx retorna FALSE e GetLastError retorna ERROR_INSUFFICIENT_BUFFER.
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.
Um aplicativo usa as funções MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx, WaitForMultipleObjectsEx e SleepEx para inserir um estado de espera alertável. Para obter mais informações sobre esperas alertáveis e entrada/saída sobrepostas, consulte Sobre sincronização.
Há requisitos estritos para trabalhar com êxito com arquivos abertos com CreateFile usando FILE_FLAG_NO_BUFFERING. Para obter detalhes , consulte Buffer de arquivos.
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 |
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 informações adicionais, consulte Sobre o NTFS transacional.Exemplos
Para obter um exemplo, consulte Servidor de pipe nomeado usando rotinas de conclusão.
Requisitos
| Requisito | Valor |
|---|---|
| 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 |