Función WriteFileGather (fileapi.h)

Artículo
01/10/2024

Recupera datos de una matriz de búferes y los escribe en un archivo.

La función comienza a escribir datos en el archivo en una posición especificada por una estructura SUPERPUESTA . La función WriteFileGather funciona de forma asincrónica.

Sintaxis

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

Parámetros

[in] hFile

Identificador del archivo. El identificador de archivo debe crearse con el derecho de acceso GENERIC_WRITE y las marcas de FILE_FLAG_OVERLAPPED y FILE_FLAG_NO_BUFFERING . Para obtener más información, vea Seguridad de archivos y derechos de acceso.

[in] aSegmentArray

Puntero a una matriz de FILE_SEGMENT_ELEMENT búferes de estructura que contienen los datos. Para obtener una descripción de esta unión, vea Comentarios.

Cada elemento representa una página de datos.

Nota

Para determinar el tamaño de una página del sistema, use la función GetSystemInfo .

La matriz debe contener suficientes elementos para representar bytes nNumberOfBytesToWrite de datos. Por ejemplo, si hay 40 KB que se van a escribir y el tamaño de página es de 4 KB, la matriz debe tener 10 elementos.

Cada búfer debe tener al menos el tamaño de una página de memoria del sistema y debe alinearse en un límite de tamaño de página de memoria del sistema. El sistema escribe una página de memoria del sistema de datos de cada búfer.

La función recopila los datos de los búferes en orden secuencial. Por ejemplo, escribe datos en el archivo desde el primer búfer, después el segundo búfer, etc. hasta que se hayan escrito bytes nNumberOfBytesToWrite .

Debido al funcionamiento asincrónico de esta función, se deben tomar precauciones para asegurarse de que este parámetro siempre hace referencia a la memoria válida durante la vigencia de las escrituras asincrónicas. Por ejemplo, un error de programación común es usar el almacenamiento de pila local y, a continuación, permitir que la ejecución se ejecute fuera del ámbito.

[in] nNumberOfBytesToWrite

Número total de bytes que se van a escribir. Cada elemento de aSegmentArray contiene un fragmento de una página de este total. Dado que el archivo debe abrirse con FILE_FLAG_NO_BUFFERING, el número de bytes debe ser un múltiplo del tamaño del sector del sistema de archivos donde se encuentra el archivo.

Si nNumberOfBytesToWrite es cero (0), la función realiza una operación de escritura nula. El comportamiento de una operación de escritura nula depende del sistema de archivos subyacente. Si nNumberOfBytesToWrite no es cero (0) y el desplazamiento y la longitud de los datos del lugar de escritura más allá del final actual del archivo, la función WriteFileGather extiende el archivo.

lpReserved

Este parámetro está reservado para uso futuro y debe ser NULL.

[in, out] lpOverlapped

Puntero a una estructura de datos SUPERPUESTA .

La función WriteFileGather requiere una estructura SUPERPUESTA válida. El parámetro lpOverlapped no puede ser NULL.

La función WriteFileGather comienza a escribir datos en el archivo en una posición especificada por los miembros Offset y OffsetHigh de la estructura SUPERPUESTA .

La función WriteFileGather puede devolverse antes de que se complete la operación de escritura. En ese escenario, la función WriteFileGather devuelve el valor cero (0) y la función GetLastError devuelve el valor ERROR_IO_PENDING. Esta operación asincrónica de la función WriteFileGather permite que el proceso de llamada continúe mientras se completa la operación de escritura.

Puede llamar a la función GetOverlappedResult, HasOverlappedIoCompleted o GetQueuedCompletionStatus para obtener información sobre la finalización de la operación de escritura. Para obtener más información, consulte E /S sincrónica y asincrónica.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero (0). Para obtener información ampliada de los errores, llame a la función GetLastError.

Si la función devuelve antes de que se complete la operación de escritura, la función devuelve cero (0) y la función GetLastError devuelve ERROR_IO_PENDING.

Comentarios

Wow64 no admite esta función para aplicaciones de 32 bits en los sistemas basados en Itanium.

La estructura FILE_SEGMENT_ELEMENT se define de la siguiente manera:

typedef union _FILE_SEGMENT_ELEMENT {
    PVOID64   Buffer;
    ULONGLONG Alignment;
}FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;

Al asignar un puntero al miembro buffer , se ampliará el valor si el código se compila como 32 bits; Esto puede interrumpir las aplicaciones compatibles con direcciones grandes que se ejecutan en sistemas configurados con ajuste de 4 gigabytes o que se ejecutan en WOW64 en Windows de 64 bits. Por lo tanto, use la macro PtrToPtr64 al asignar punteros a Buffer.

Si parte del archivo especificado por hFile está bloqueado por otro proceso y la operación de escritura se superpone a la parte bloqueada, se produce un error en la función WriteFileGather .

En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.

Tecnología	Compatible
Protocolo Bloque de mensajes del servidor (SMB) 3.0	Sí
Conmutación por error transparente (TFO) de SMB 3.0	Sí
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	Sí
Sistema de archivos de Volumen compartido de clúster (CsvFS)	Sí
Sistema de archivos resistente a errores (ReFS)	Sí

Operaciones de transacción

Si hay una transacción enlazada al identificador de archivo, se realiza una transacción.

Requisitos


Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	fileapi.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll