Función WriteFileEx (fileapi.h)

  • Artículo

Escribe datos en el archivo o en el dispositivo de entrada y salida (E/S) especificados. Notifica su estado de finalización de forma asincrónica y llama a la rutina de finalización especificada cuando se completa o cancela la escritura y el subproceso de llamada está en estado de espera en alerta.

Para escribir datos en un archivo o dispositivo de forma sincrónica, use la función WriteFile .

Sintaxis

BOOL WriteFileEx(
  [in]           HANDLE                          hFile,
  [in, optional] LPCVOID                         lpBuffer,
  [in]           DWORD                           nNumberOfBytesToWrite,
  [in, out]      LPOVERLAPPED                    lpOverlapped,
  [in]           LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parámetros

[in] hFile

Identificador del archivo o dispositivo de E/S (por ejemplo, un archivo, secuencia de archivos, disco físico, volumen, búfer de consola, unidad de cinta, socket, recurso de comunicaciones, mailslot o canalización).

Este parámetro puede ser cualquier identificador abierto con la marca FILE_FLAG_OVERLAPPED mediante la función CreateFile o un identificador de socket devuelto por el socket o la función accept .

No asocie un puerto de finalización de E/S con este identificador. Para obtener más información, vea la sección Comentarios.

Este identificador también debe tener el derecho de acceso GENERIC_WRITE . Para obtener más información sobre los derechos de acceso, vea Derechos de acceso y seguridad de archivos.

[in, optional] lpBuffer

Puntero al búfer que contiene los datos que se van a escribir en el archivo o dispositivo.

Este búfer debe permanecer válido durante la operación de escritura. El autor de la llamada no debe usar este búfer hasta que se complete la operación de escritura.

[in] nNumberOfBytesToWrite

Número de bytes que se van a escribir en el archivo o dispositivo.

Un valor de cero especifica una operación de escritura nula. El comportamiento de una operación de escritura nula depende del sistema de archivos subyacente.

Las operaciones de escritura de canalización en una red están limitadas a 65 535 bytes por escritura. Para obtener más información sobre las canalizaciones, consulte la sección Comentarios.

[in, out] lpOverlapped

Puntero a una estructura de datos SUPERPUESTA que proporciona datos que se usarán durante la operación de escritura superpuesta (asincrónica).

Para los archivos que admiten desplazamientos de bytes, debe especificar un desplazamiento de bytes en el que empezar a escribir en el archivo. Para especificar este desplazamiento, establezca los miembros Offset y OffsetHigh de la estructura SUPERPUESTA . En el caso de los archivos o dispositivos que no admiten desplazamientos de bytes, se omite OffsetHigh y OffsetHigh.

Para escribir al final del archivo, especifique los miembros Offset y OffsetHigh de la estructura SUPERPUESTA como 0xFFFFFFFF. Esto es funcionalmente equivalente a llamar previamente a la función CreateFile para abrir hFile mediante FILE_APPEND_DATA acceso.

La función WriteFileEx omite el miembro hEvent de la estructura SUPERPUESTA. Una aplicación es libre de usar ese miembro para sus propios fines en el contexto de una llamada WriteFileEx . WriteFileEx señala la finalización de su operación de escritura mediante una llamada a la rutina de finalización a la que apunta lpCompletionRoutine, por lo que no necesita un identificador de eventos.

La función WriteFileEx usa los miembros Internal e InternalHigh de la estructura SUPERPUESTA. No debe cambiar el valor de estos miembros.

La estructura de datos SUPERPUESTA debe permanecer válida durante la operación de escritura. No debe ser una variable que pueda salir del ámbito mientras la operación de escritura está pendiente de finalización.

[in] lpCompletionRoutine

Puntero a una rutina de finalización a la que se llamará cuando se ha completado la operación de escritura y el subproceso de llamada se encuentra en un estado de espera alertable. Para obtener más información sobre esta rutina de finalización, vea FileIOCompletionRoutine.

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. Para obtener información de error extendida, llame a GetLastError.

Si la función WriteFileEx se realiza correctamente, el subproceso de llamada tiene pendiente una operación de E/S asincrónica: la operación de escritura superpuesta en el archivo. Cuando finaliza esta operación de E/S y el subproceso de llamada se bloquea en un estado de espera alertable, el sistema operativo llama a la función a la que apunta lpCompletionRoutine y la espera se completa con un código de retorno de WAIT_IO_COMPLETION.

Si la función se ejecuta correctamente y finaliza la operación de escritura de archivos, pero el subproceso de llamada no está en un estado de espera alertable, el sistema pone en cola la llamada a *lpCompletionRoutine, manteniendo la llamada hasta que el subproceso de llamada entra en un estado de espera alertable. Para obtener más información sobre los estados de espera alertables y las operaciones de entrada y salida superpuestas, vea Acerca de la sincronización.

Comentarios

Al usar WriteFileEx , debe comprobar GetLastError incluso cuando la función devuelva "correcto" para comprobar si las condiciones son correctas , pero tiene algún resultado que desee conocer. Por ejemplo, un desbordamiento de búfer al llamar a WriteFileEx devolverá TRUE, pero GetLastError notificará el desbordamiento con ERROR_MORE_DATA. Si la llamada a la función es correcta y no hay condiciones de advertencia, GetLastError devolverá ERROR_SUCCESS.

Se producirá un error en la función WriteFileEx si el parámetro hFile está asociado a un puerto de finalización de E/S. Para realizar escrituras mediante este tipo de identificador, use la función WriteFile .

La función WriteFileEx puede producir un error si hay demasiadas solicitudes de E/S asincrónica pendientes. En caso de que se produzca un error de este tipo, GetLastError puede devolver ERROR_INVALID_USER_BUFFER o ERROR_NOT_ENOUGH_MEMORY.

Para cancelar todas las operaciones de E/S asincrónicas pendientes, use:

  • CancelIo: esta función solo cancela las operaciones emitidas por el subproceso de llamada para el identificador de archivo especificado.
  • CancelIoEx: esta función cancela todas las operaciones emitidas por los subprocesos para el identificador de archivo especificado.

Use CancelSynchronousIo para cancelar las operaciones de E/S sincrónicas pendientes.

Las operaciones de E/S canceladas se completan con el error ERROR_OPERATION_ABORTED.

Si otra operación de escritura bloquea parte del archivo especificado por hFile y la operación de escritura especificada se superpone a la parte bloqueada, WriteFileEx produce un error.

Al escribir en un archivo, la última hora de escritura no se actualiza completamente hasta que se hayan cerrado todos los identificadores usados para escribir. Por lo tanto, para garantizar una hora de última escritura precisa, cierre el identificador de archivo inmediatamente después de escribir en el archivo.

El acceso al búfer de salida mientras una operación de escritura usa el búfer puede provocar daños en los datos escritos desde ese búfer. Las aplicaciones no deben escribir en, reasignar ni liberar el búfer de salida que usa una operación de escritura hasta que se complete la operación de escritura.

Tenga en cuenta que es posible que las marcas de tiempo no se actualicen correctamente para un archivo remoto. Para garantizar resultados coherentes, use E/S sin búfer.

El sistema interpreta cero bytes para escribir como especificar una operación de escritura nula y WriteFile no trunca ni extiende el archivo. Para truncar o extender un archivo, use la función SetEndOfFile .

Una aplicación usa las funciones WaitForSingleObjectEx, WaitForMultipleObjectsEx, MsgWaitForMultipleObjectsEx, SignalObjectAndWait y SleepEx para especificar un estado de espera de alerta. Para obtener más información sobre los estados de espera alertables y las operaciones de E/S superpuestas, consulte Acerca de la sincronización.

Si escribe directamente en un volumen que tiene un sistema de archivos montado, primero debe obtener acceso exclusivo al volumen. De lo contrario, corre el riesgo de causar daños en los datos o inestabilidad del sistema, ya que las escrituras de la aplicación pueden entrar en conflicto con otros cambios procedentes del sistema de archivos y dejar el contenido del volumen en un estado incoherente. Para evitar estos problemas, se han realizado los siguientes cambios en Windows Vista y versiones posteriores:

  • Una escritura en un identificador de volumen se realizará correctamente si el volumen no tiene un sistema de archivos montado o si se cumple una de las condiciones siguientes:
    • Los sectores en los que se va a escribir son sectores de arranque.
    • Sectores que se van a escribir para residir fuera del espacio del sistema de archivos.
    • Ha bloqueado o desmontado explícitamente el volumen mediante FSCTL_LOCK_VOLUME o FSCTL_DISMOUNT_VOLUME.
    • El volumen no tiene ningún sistema de archivos real. (En otras palabras, tiene un sistema de archivos RAW montado).
  • Una escritura en un identificador de disco se realizará correctamente si se cumple una de las condiciones siguientes:
    • Los sectores en los que se va a escribir no se encuentran dentro de las extensiones de un volumen.
    • Los sectores que se van a escribir se encuentran dentro de un volumen montado, pero se ha bloqueado o desmontado explícitamente el volumen mediante FSCTL_LOCK_VOLUME o FSCTL_DISMOUNT_VOLUME.
    • Los sectores que se van a escribir se encuentran dentro de un volumen que no tiene ningún sistema de archivos montado que no sea RAW.

Hay requisitos estrictos para trabajar correctamente con archivos abiertos con CreateFile mediante FILE_FLAG_NO_BUFFERING. Para más información, consulte Almacenamiento en búfer de archivos.

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 de escritura de archivo. Para obtener más información, vea Acerca de NTFS transaccional.

Ejemplos

Para obtener un ejemplo, vea Servidor de canalización con nombre mediante rutinas de finalización.

Requisitos

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

Vea también