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 |