Função ReadFileScatter (fileapi.h)

Artigo
01/10/2024

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