Función ReadFileEx (fileapi.h)
Lee los datos del archivo o del dispositivo de entrada/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 lectura y el subproceso de llamada está en estado de espera en alerta.
Para leer datos de un archivo o dispositivo de forma sincrónica, use la función ReadFile .
Sintaxis
BOOL ReadFileEx(
[in] HANDLE hFile,
[out, optional] LPVOID lpBuffer,
[in] DWORD nNumberOfBytesToRead,
[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 .
Este identificador también debe tener el derecho de acceso GENERIC_READ . Para obtener más información sobre los derechos de acceso, vea Derechos de acceso y seguridad de archivos.
[out, optional] lpBuffer
Puntero a un búfer que recibe los datos leídos del archivo o dispositivo.
Este búfer debe permanecer válido durante la operación de lectura. La aplicación no debe usar este búfer hasta que se complete la operación de lectura.
[in] nNumberOfBytesToRead
Número de bytes que se va a leer.
[in, out] lpOverlapped
Puntero a una estructura de datos SUPERPUESTA que proporciona datos que se usarán durante la operación de lectura de archivos asincrónica (superpuesta).
Para los archivos que admiten desplazamientos de bytes, debe especificar un desplazamiento de bytes en el que empezar a leer desde 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.
La función ReadFileEx 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 ReadFileEx . ReadFileEx señala la finalización de su operación de lectura 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 ReadFileEx usa los miembros Internal e InternalHigh de la estructura SUPERPUESTA. Una aplicación no debe establecer estos miembros.
La estructura de datos SUPERPUESTA debe permanecer válida durante la operación de lectura. No debe ser una variable que pueda salir del ámbito mientras la operación de lectura está pendiente de finalización.
[in] lpCompletionRoutine
Puntero a la rutina de finalización a la que se llamará cuando se complete la operación de lectura y el subproceso que realiza la llamada se encuentra en un estado de espera alertable. Para obtener más información sobre la 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 se realiza correctamente, el subproceso que realiza la llamada tiene pendiente una operación de E/S asincrónica: la operación de lectura superpuesta del archivo. Cuando se completa esta operación de E/S y el subproceso de llamada se bloquea en un estado de espera alertable, el sistema llama a la función a la que apunta lpCompletionRoutine y el estado de espera se completa con un código de retorno de WAIT_IO_COMPLETION.
Si la función se realiza correctamente y la operación de lectura de archivos se completa, pero el subproceso que realiza la llamada no está en un estado de espera alertable, el sistema pone en cola la llamada de rutina de finalización, manteniendo la llamada hasta que el subproceso de llamada entra en un estado de espera que se puede alertar. Para obtener información sobre las esperas que se pueden alertar y las operaciones de entrada y salida superpuestas, consulte Acerca de la sincronización.
Si ReadFileEx intenta leer más allá del final del archivo (EOF), la llamada a GetOverlappedResult para esa operación devuelve FALSE y GetLastError devuelve ERROR_HANDLE_EOF.
Comentarios
Al usar ReadFileEx , debe comprobar GetLastError incluso cuando la función devuelve "success" para comprobar las condiciones que son "correctas", pero tiene algún resultado que le interese conocer. Por ejemplo, un desbordamiento de búfer al llamar a ReadFileEx devolverá TRUE, pero GetLastError notificará el desbordamiento con ERROR_MORE_DATA. Si la llamada de función se realiza correctamente y no hay condiciones de advertencia, GetLastError devolverá ERROR_SUCCESS.
La función ReadFileEx puede producir un error si hay demasiadas solicitudes de E/S asincrónica pendientes. En caso de que se produzca este error, 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 que realiza la 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.
Las operaciones de E/S que se cancelan se completan con el error ERROR_OPERATION_ABORTED.
Si otro proceso bloquea parte del archivo especificado por hFile y la operación de lectura especificada en una llamada a ReadFileEx se superpone a la parte bloqueada, se produce un error en la llamada a ReadFileEx .
Al intentar leer datos de un mailslot cuyo búfer es demasiado pequeño, ReadFileEx devuelve FALSE y GetLastError devuelve ERROR_INSUFFICIENT_BUFFER.
El acceso al búfer de entrada mientras una operación de lectura usa el búfer puede provocar daños en los datos leídos en ese búfer. Las aplicaciones no deben leer, escribir en, reasignar ni liberar el búfer de entrada que usa una operación de lectura hasta que se complete la operación de lectura.
Una aplicación usa las funciones MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx, WaitForMultipleObjectsEx y SleepEx para especificar un estado de espera de alerta. Para obtener más información sobre las esperas que se pueden alertar y la entrada o salida superpuestas, consulte Acerca de la sincronización.
Hay requisitos estrictos para trabajar correctamente con archivos abiertos con CreateFile mediante FILE_FLAG_NO_BUFFERING. Para obtener 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, la función devuelve datos de la vista de transacción del archivo. Se garantiza que un identificador de lectura de transacción muestra la misma vista de un archivo mientras dura el identificador. 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 (incluye Windows.h) |
| Library | Kernel32.lib |
| Archivo DLL | Kernel32.dll |