Função ReadFileScatter (fileapi.h)
Lê dados de um arquivo e armazena-os em uma matriz de buffers.
A função começa a ler dados do arquivo em uma posição especificada por uma estrutura OVERLAPPED . A função ReadFileScatter opera de forma assíncrona.
Sintaxe
BOOL ReadFileScatter(
[in] HANDLE hFile,
[in] FILE_SEGMENT_ELEMENT [] aSegmentArray,
[in] DWORD nNumberOfBytesToRead,
LPDWORD lpReserved,
[in, out] LPOVERLAPPED lpOverlapped
);
Parâmetros
[in] hFile
Um identificador para o arquivo a ser lido.
O identificador de arquivo deve ser criado com o GENERIC_READ direito e os sinalizadores FILE_FLAG_OVERLAPPED e FILE_FLAG_NO_BUFFERING . Para obter mais informações, consulte Segurança de arquivo e direitos de acesso.
[in] aSegmentArray
Um ponteiro para uma matriz de FILE_SEGMENT_ELEMENT buffers de estrutura que recebe os dados. Para obter uma descrição dessa união, consulte Comentários.
Cada elemento representa uma página de dados.
Observação
Para determinar o tamanho de uma página do sistema, use GetSystemInfo.
A matriz deve conter elementos suficientes para representar bytes de dados nNumberOfBytesToRead . Por exemplo, se houver 40 KB a serem lidos e o tamanho da página for de 4 KB, a matriz deverá ter 10 elementos.
Cada buffer deve ter pelo menos o tamanho de uma página de memória do sistema e deve ser alinhado em um limite de tamanho de página de memória do sistema. O sistema lê uma página de memória do sistema de dados em cada buffer.
A função armazena os dados nos buffers em ordem sequencial. Por exemplo, ele armazena dados no primeiro buffer, depois no segundo buffer e assim por diante até que cada buffer seja preenchido e todos os dados sejam armazenados ou bytes nNumberOfBytesToRead tenham sido lidos.
[in] nNumberOfBytesToRead
O número total de bytes a serem lidos do arquivo. Cada elemento de aSegmentArray contém uma parte de uma página desse total. Como o arquivo deve ser aberto com FILE_FLAG_NO_BUFFERING, o número de bytes deve ser um múltiplo do tamanho do setor do sistema de arquivos em que o arquivo está localizado.
lpReserved
Esse parâmetro é reservado para uso futuro e deve ser NULL.
[in, out] lpOverlapped
Um ponteiro para uma estrutura de dados OVERLAPPED .
A função ReadFileScatter requer uma estrutura OVERLAPPED válida. O parâmetro lpOverlapped não pode ser NULL.
A função ReadFileScatter começa a ler dados do arquivo em uma posição especificada pelos membros Offset e OffsetHigh da estrutura OVERLAPPED .
A função ReadFileScatter pode retornar antes da conclusão da operação de leitura. Nesse cenário, a função ReadFileScatter retorna o valor 0 (zero) e a função GetLastError retorna o valor ERROR_IO_PENDING. Essa operação assíncrona de ReadFileScatter permite que o processo de chamada continue enquanto a operação de leitura é concluída. Você pode chamar as funções GetOverlappedResult, HasOverlappedIoCompleted ou GetQueuedCompletionStatus para obter informações sobre a conclusão da operação de leitura. Para obter mais informações, consulte E/S síncrona e assíncrona.
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á 0 (zero). Para obter informações de erro estendidas, chame a função GetLastError.
Se ReadFileScatter 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.
Se a função retornar antes da conclusão da operação de leitura, a função retornará zero (0) e GetLastError retornará ERROR_IO_PENDING.
Comentários
Essa função não tem suporte para aplicativos de 32 bits pelo WOW64 em sistemas baseados em Itanium.
A estrutura FILE_SEGMENT_ELEMENT é definida da seguinte maneira:
typedef union _FILE_SEGMENT_ELEMENT {
PVOID64 Buffer;
ULONGLONG Alignment;
}FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;
Atribuir um ponteiro ao membro buffer vai assinar e estender o valor se o código for compilado como 32 bits; isso pode interromper aplicativos com reconhecimento de endereço grande em execução em sistemas configurados com ajuste de 4 Gigabytes ou em execução em em WOW64 no Windows de 64 bits. Portanto, use a macro PtrToPtr64 ao atribuir ponteiros ao Buffer.
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.Requisitos
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | fileapi.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |