Compartilhar via


Função WriteFileGather (fileapi.h)

Recupera dados de uma matriz de buffers e grava os dados em um arquivo.

A função começa a gravar dados no arquivo em uma posição especificada por uma estrutura OVERLAPPED . A função WriteFileGather opera de forma assíncrona.

Sintaxe

BOOL WriteFileGather(
  [in]      HANDLE                  hFile,
  [in]      FILE_SEGMENT_ELEMENT [] aSegmentArray,
  [in]      DWORD                   nNumberOfBytesToWrite,
            LPDWORD                 lpReserved,
  [in, out] LPOVERLAPPED            lpOverlapped
);

Parâmetros

[in] hFile

Um manipulador para o arquivo. O identificador de arquivo deve ser criado com o direito de acesso GENERIC_WRITE 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 contêm 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 a função GetSystemInfo .

A matriz deve conter elementos suficientes para representar bytes de dados nNumberOfBytesToWrite . Por exemplo, se houver 40 KB a serem gravados 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 grava uma página de memória do sistema de dados de cada buffer.

A função coleta os dados dos buffers em ordem sequencial. Por exemplo, ele grava dados no arquivo do primeiro buffer, depois no segundo buffer e assim por diante até que nNumberOfBytesToWrite bytes tenham sido gravados.

Devido à operação assíncrona dessa função, devem ser tomadas precauções para garantir que esse parâmetro sempre faça referência à memória válida durante o tempo de vida das gravações assíncronas. Por exemplo, um erro de programação comum é usar o armazenamento de pilha local e, em seguida, permitir que a execução seja executada fora do escopo.

[in] nNumberOfBytesToWrite

O número total de bytes a serem gravados. 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.

Se nNumberOfBytesToWrite for zero (0), a função executará uma operação de gravação nula. O comportamento de uma operação de gravação nula depende do sistema de arquivos subjacente. Se nNumberOfBytesToWrite não for zero (0) e o deslocamento e o comprimento dos dados do local de gravação além do final atual do arquivo, a função WriteFileGather estenderá o arquivo.

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 WriteFileGather requer uma estrutura OVERLAPPED válida. O parâmetro lpOverlapped não pode ser NULL.

A função WriteFileGather começa a gravar dados no arquivo em uma posição especificada pelos membros Offset e OffsetHigh da estrutura OVERLAPPED .

A função WriteFileGather pode retornar antes da conclusão da operação de gravação. Nesse cenário, a função WriteFileGather retorna o valor zero (0) e a função GetLastError retorna o valor ERROR_IO_PENDING. Essa operação assíncrona da função WriteFileGather permite que o processo de chamada continue enquanto a operação de gravação é concluída.

Você pode chamar a função GetOverlappedResult, HasOverlappedIoCompleted ou GetQueuedCompletionStatus para obter informações sobre a conclusão da operação de gravação. 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 a função retornar antes da conclusão da operação de gravação, a função retornará zero (0) e a função GetLastError retornará ERROR_IO_PENDING.

Comentários

Essa função não tem suporte para aplicativos de 32 bits da WOW64 nos 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 WOW64 no Windows de 64 bits. Portanto, use a macro PtrToPtr64 ao atribuir ponteiros ao Buffer.

Se parte do arquivo especificado por hFile for bloqueada por outro processo e a operação de gravação sobrepor a parte bloqueada, a função WriteFileGather falhará.

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 operação será transacionada.

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

Confira também

CreateFile

FILE_SEGMENT_ELEMENT

Funções de gerenciamento de arquivos

GetOverlappedResult

GetQueuedCompletionStatus

HasOverlappedIoCompleted

OVERLAPPED

ReadFile

ReadFileEx

ReadFileScatter

E/S síncrona e assíncrona