WriteFile

Escribe datos a un fichero, está diseñada tanto para operaciones síncronas como asíncronas. La función empieza escribiendo datos al fichero en la posición indicada pro el puntero del fichero. Después de que la operación de escritura ha sido completada, el puntero del fichero se ajusta en el número de bytes escritos actualmente, excepto cuando el fichero ha sido abierto con FILE_FLAG_OVERLAPPED. Si el manipulador de fichero fue creado para entrada y salida superpuesta (overlapped I/O), la aplicación debe ajustar la posición del puntero de fichero después de que la operación de escritura haya terminado.

Sintaxis

BOOL WriteFile(
    HANDLE hFile,                    // manipulador del fichero
    LPCVOID lpBuffer,                // dirección de los datos a escribir
    DWORD nNumberOfBytesToWrite,     // número de bytes a escribir
    LPDWORD lpNumberOfBytesWritten,  // dirección del número de bytes escritos
    LPOVERLAPPED lpOverlapped        // dirección de la estructura necesaria para I/O superpuestas
   );

Parámetros:

hFile: identifica el fichero en el que se escribirá. El manipulador debe haber sido creado con acceso GENERIC_WRITE al fichero.

Windows NT: para operaciones de escritura asíncronas, hFile puede ser un manipulador abierto con el flag FILE_FLAG_OVERLAPPED en la función CreateFile, o un manipulador de socket devuelto por las funciones socket o accept.

Windows 95: para operaciones de escritura asíncronas, hFile puede ser un manipulador de un recurso de comunicaciones, un mailslot o de una tubería con nombre (named pipe) abierto con el flag FILE_FLAG_OVERLAPPED por la función CreateFile, o un manipulador de socket devuelto por las funciones socket o accept. Windows 95 no soporta operaciones de escritura asíncronas en ficheros de disco.

lpBuffer: puntero al buffer que contiene los datos a escribir en el fichero.

nNumberOfBytesToWrite: especifica el número de bytes a escribir en el fichero.

Al contrario del sistema operativo MS-DOS, Windows NT interpreta un valor de cero como una especificación de una operación de escritura nula. Una A operación de escritura nula no escribe ningún byte pero produce una actualización del time stamp.

Operaciones de escritura a través de red en tuberías con nombre están limitadas a 65535 bytes.

lpNumberOfBytesWritten: apunta al número de bytes escritos por esta llamada a la función. WriteFile cambia este valor a cero antes de hacer ningún trabajo o comprobación de error.

lpOverlapped: apunta a una estructura OVERLAPPED. Esta estructura se requiere si hFile fue abierto con FILE_FLAG_OVERLAPPED.

Este parámetro no puede ser NULL si hFile fue abierto con FILE_FLAG_OVERLAPPED. Debe apuntar a una estructura OVERLAPPED válida. Si hFile fue creado con FILE_FLAG_OVERLAPPED y lpOverlapped es NULL, la función falla de modo impredecible.

Si hFile no fue creado con FILE_FLAG_OVERLAPPED y lpOverlapped es NULL, la operación de escritura empieza en la posición del fichero actual y WriteFile no regresa hasta que la operación ha sido completada.

Si hFile fue creado con FILE_FLAG_OVERLAPPED y lpOverlapped no es NULL, la operación de escritura comienza con el desplazamiento especificado en la estructura OVERLAPPED y WriteFile puede regresar antes de que la operación de escritura se haya completado. En este caso, WriteFile devuelve FALSE y la función GetLastError devuelve ERROR_IO_PENDING. Esto permite al proceso que llama continuar procesando mientras la operación de escritura está siendo completada. El evento especificado en la estructura OVERLAPPED se cambia al estado "señalizado" hasta que se completa la operación de escritura.

Si hFile o fue creado con FILE_FLAG_OVERLAPPED y lpOverlapped no es NULL, la operación de escritura comienza a partir del desplazamiento indicado en la estructura OVERLAPPED y WriteFile no regresa hasta que se completa la operación de escritura.

Valor de retorno

Si la función tiene éxito, el valor de retorno es TRUE.

Si la función falla, el valor de retorno es FALSE. Para obtener mayor información sobre el error, llamar a GetLastError.

Observaciones

Si parte del fichero está bloqueado por otro proceso y la operación de escritura sobrepasa la porción bloqueada, esta función falla.

Las aplicaciones no deben leer ni escribir en el buffer de entrada que una operación de lectura esté usando mientras la operación de lectura no se complete. Un acceso prematuro al buffer de entrada puede provocar una corrupción de los datos leídos en ese buffer.

Los caracteres pueden ser escritos al buffer de pantalla usando WriteFile con un manipulador de consola de salida. El comportamiento exacto de la función se determina según el modo de consola. Los datos son escritos en la posición actual del cursor. La posición del cursor se actualiza después de la operación de escritura.

Al contrario que en MS-DOS, Windows NT interpreta una escritura de cero bytes como una especificación de operación de escritura nula y WriteFile no trunca o agranda el fichero. Para truncar o agrandar un fichero, usar la función SetEndOfFile.

Cuando se escribe a un dispositivo que no admite bloques, un manipulador de una tubería en modo de byte con un buffer sin espacio suficiente, WriteFile devuelve TRUE con *lpNumberOfBytesWritten < nNumberOfBytesToWrite.

Cuando una aplicación usa WriteFile para escribir en una tubería, la operación de escritura no termina si el buffer de la tubería está lleno. La operación de escritura se completa cuando al operación de lectura (usando ReadFile) deja más espacio disponible en el buffer.

Si el manipulador de tubería anónima de lectura ha sido cerrado y WriteFile intenta escribir usando el manipulador de tubería anónima correspondiente, la función devuelve FALSE y GetLastError devuelve ERROR_BROKEN_PIPE.

La función WriteFile puede fallar con ERROR_INVALID_USER_BUFFER o ERROR_NOT_ENOUGH_MEMORY si existen demasiadas peticiones de I/O asíncronas pendientes.

Si hFile es un manipulador de una tubería con nombre, los miembros Offset y OffsetHigh de la estructura OVERLAPPED apuntada por lpOverlapped deben ser cero, o la función fallará.