Función ReadFile (fileapi.h)
Lee los datos del archivo especificado o del dispositivo de entrada/salida (E/S). Las lecturas se producen en la posición especificada por el puntero de archivo si es compatible con el dispositivo.
Esta función está diseñada para operaciones sincrónicas y asincrónicas. Para obtener una función similar diseñada únicamente para la operación asincrónica, consulte ReadFileEx.
Sintaxis
BOOL ReadFile(
[in] HANDLE hFile,
[out] LPVOID lpBuffer,
[in] DWORD nNumberOfBytesToRead,
[out, optional] LPDWORD lpNumberOfBytesRead,
[in, out, optional] LPOVERLAPPED lpOverlapped
);
Parámetros
[in] hFile
Identificador del dispositivo (por ejemplo, un archivo, flujo de archivos, disco físico, volumen, búfer de consola, unidad de cinta, socket, recurso de comunicaciones, mailslot o canalización).
El parámetro hFile debe haberse creado con acceso de lectura. Para obtener más información, vea de derechos de acceso genéricos y derechos de acceso y seguridad de archivos de .
En el caso de las operaciones de lectura asincrónicas,
[out] lpBuffer
Puntero al búfer que recibe los datos leídos de un archivo o dispositivo.
Este búfer debe permanecer válido durante la operación de lectura. El autor de la llamada no debe usar este búfer hasta que se complete la operación de lectura.
[in] nNumberOfBytesToRead
Número máximo de bytes que se van a leer.
[out, optional] lpNumberOfBytesRead
Puntero a la variable que recibe el número de bytes leídos al usar un parámetro de hFile sincrónico. ReadFile establece este valor en cero antes de realizar cualquier comprobación de errores o trabajo. Use NULL para este parámetro si se trata de una operación asincrónica para evitar resultados potencialmente erróneos.
Este parámetro solo se puede NULL cuando el parámetro de lpOverlapped no es NULL.
Windows 7: Este parámetro no se puede NULL.
Para obtener más información, vea la sección Comentarios.
[in, out, optional] lpOverlapped
Se requiere un puntero a una estructura superpuesta
Si
Para un hFile que admita desplazamientos de bytes, si usa este parámetro, debe especificar un desplazamiento de bytes en el que empezar a leer desde el archivo o dispositivo. Este desplazamiento se especifica estableciendo los de desplazamiento
Para obtener más información sobre las diferentes combinaciones de
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es distinto de cero (TRUE).
Si se produce un error en la función o se completa de forma asincrónica, el valor devuelto es cero (FALSE). Para obtener información de error extendida, llame a la función
Nota
La
Observaciones
La función ReadFile devuelve cuando se produce una de las condiciones siguientes:
- Se lee el número de bytes solicitados.
- Una operación de escritura se completa en el extremo de escritura de la canalización.
- Se usa un identificador asincrónico y la lectura se está produciendo de forma asincrónica.
- Se produce un error.
La función readFile puede producir un error con ERROR_INVALID_USER_BUFFER o ERROR_NOT_ENOUGH_MEMORY siempre que haya demasiadas solicitudes de E/S asincrónicas pendientes.
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 que se cancelan se completan con el error ERROR_OPERATION_ABORTED.
La función readFile
Si otra operación de lectura bloquea parte de un archivo y la operación de lectura se superpone a la parte bloqueada, se produce un error en esta función.
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. Esto puede ser especialmente problemático cuando se usa un identificador de archivo asincrónico. Puede encontrar información adicional sobre los identificadores de archivos sincrónicos frente a asincrónicos en la sección sincronización y posición de archivo y en el tema de referencia de CreateFile.
Los caracteres se pueden leer desde el búfer de entrada de la consola mediante ReadFile con un identificador para la entrada de la consola. El modo de consola determina el comportamiento exacto de la función ReadFile. De forma predeterminada, el modo de consola es ENABLE_LINE_INPUT, que indica que ReadFile debe leerse hasta que llegue a un retorno de carro. Si presiona Ctrl+C, la llamada se realiza correctamente, pero GetLastError devuelve ERROR_OPERATION_ABORTED. Para obtener más información, vea CreateFile.
Al leer desde un dispositivo de comunicaciones, el comportamiento de ReadFile viene determinado por el tiempo de espera de comunicación actual establecido y recuperado mediante las funciones de SetCommTimeouts y GetCommTimeouts. Los resultados imprevisibles pueden producirse si no se pueden establecer los valores de tiempo de espera. Para obtener más información sobre los tiempos de espera de comunicación, vea COMMTIMEOUTS.
Si readFile intenta leer desde un mailslot que tiene un búfer demasiado pequeño, la función devuelve FALSE y GetLastError devuelve ERROR_INSUFFICIENT_BUFFER.
Hay requisitos estrictos para trabajar correctamente con archivos abiertos con CreateFile mediante la marca FILE_FLAG_NO_BUFFERING. Para obtener más información, consulte de almacenamiento en búfer de archivos .
Si hFile se abrió con FILE_FLAG_OVERLAPPED, se aplican las condiciones siguientes:
- El parámetro lpOverlapped debe apuntar a una estructura de superpuesta válida y única, de lo contrario, la función puede notificar incorrectamente que la operación de lectura está completa.
- El parámetro lpNumberOfBytesRead debe establecerse en NULL. Use la función
GetOverlappedResult para obtener el número real de bytes leídos. Si el parámetro hFileestá asociado a un puerto de finalización de E/S, también puede obtener el número de bytes leídos llamando a la función GetQueuedCompletionStatus .
Sincronización y posición de archivo
Si hFile se abre con FILE_FLAG_OVERLAPPED, es un identificador de archivo asincrónico; de lo contrario, es sincrónico. Las reglas para usar la estructura de SUPERPUESTAs son ligeramente diferentes para cada una, como se indicó anteriormente.
Nota
Si se abre un archivo o dispositivo para E/S asincrónica, las llamadas posteriores a funciones como ReadFile con ese identificador suelen devolverse inmediatamente, pero también se pueden comportar de forma sincrónica con respecto a la ejecución bloqueada. Para obtener más información, vea E/S de disco asincrónico aparece como sincrónico en Windows.
Consideraciones para trabajar con identificadores de archivos asincrónicos:
-
ReadFile puede devolver antes de que se complete la operación de lectura. En este escenario,
readFile devuelveFALSE y la función getLastErrordevuelve ERROR_IO_PENDING , lo que permite que el proceso de llamada continúe mientras el sistema completa la operación de lectura. - El parámetro
lpOverlapped no debe ser NULL y debe usarse teniendo en cuenta los siguientes hechos: - Aunque el sistema establece y restablece automáticamente el evento especificado en el
estructura SUPERPUESTA, el desplazamiento especificado en la estructura SUPERPUESTA no se actualiza automáticamente. - ReadFile restablece el evento a un estado no asignado cuando comienza la operación de E/S.
- El evento especificado en la estructura SUPERPUESTA se establece en un estado señalado cuando se completa la operación de lectura; hasta ese momento, la operación de lectura se considera pendiente.
- Dado que la operación de lectura se inicia en el desplazamiento especificado en la estructura superpuesta
y ReadFile puede devolver antes de que se complete la operación de lectura a nivel del sistema (lectura pendiente), ni el desplazamiento ni ninguna otra parte de la estructura se deben modificar, liberar o reutilizar mediante la aplicación hasta que se indique el evento (es decir, se completa la lectura). - Si se detecta un final de archivo (EOF) durante las operaciones asincrónicas, la llamada a getOverlappedResult para esa operación devuelve FALSE y GetLastError devuelve ERROR_HANDLE_EOF.
- Aunque el sistema establece y restablece automáticamente el evento especificado en el
Consideraciones para trabajar con identificadores de archivo sincrónicos:
- Si lpOverlapped es NULL, la operación de lectura se inicia en la posición del archivo actual y ReadFile no devuelve hasta que se complete la operación y el sistema actualiza el puntero de archivo antes de ReadFile.
- Si
lpOverlapped no es null , la operación de lectura se inicia en el desplazamiento especificado en la estructura superpuestay ReadFile no devuelve hasta que se complete la operación de lectura. El sistema actualiza el desplazamiento SUPERPUESTO y el puntero de archivo antes de ReadFile. - Si lpOverlapped es NULL, cuando una operación de lectura sincrónica llega al final de un archivo, ReadFile devuelve TRUE y establece
*lpNumberOfBytesRead
en cero. - Si lpOverlapped no es NULL , cuando una operación de lectura sincrónica llega al final de un archivo, readFile devuelve FALSE y GetLastError devuelve ERROR_HANDLE_EOF.
Para obtener más información, consulte CreateFile y de E/S sincrónica y asincrónica.
Tubería
Si se usa una canalización anónima y se cierra el identificador de escritura, cuando readFile intenta leer mediante el identificador de lectura correspondiente de la canalización, la función devuelve FALSE y GetLastError devuelve ERROR_BROKEN_PIPE.
Si se lee una canalización con nombre en modo de mensaje y el siguiente mensaje es mayor que el parámetro nNumberOfBytesToRead de
Si el parámetro
Para obtener más información sobre las canalizaciones, consulte Canalizaciones.
Operaciones de transacción
Si hay una transacción enlazada al identificador de archivo, la función devuelve datos de la vista transaccionada del archivo. Se garantiza que un identificador de lectura de transacciones muestre la misma vista de un archivo mientras dure el identificador. Para obtener más información, vea About Transactional NTFS.
En Windows 8 y Windows Server 2012, esta función es compatible con las siguientes tecnologías.
Tecnología | Soportado |
---|---|
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 (ReFS) | Sí |
Ejemplos
Para obtener un ejemplo de código que muestra cómo probar para el final del archivo, vea Testing for the End of a File. Para obtener otros ejemplos, vea Crear y usar un de archivos temporales y Abrir un archivo para leer o escribir.
Requisitos
Requisito | Valor |
---|---|
cliente mínimo admitido | Windows XP [aplicaciones de escritorio | Aplicaciones para UWP] |
servidor mínimo admitido | Windows Server 2003 [aplicaciones de escritorio | Aplicaciones para UWP] |
de la plataforma de destino de |
Windows |
encabezado de |
fileapi.h (incluya Windows.h) |
biblioteca de |
Kernel32.lib |
DLL de |
Kernel32.dll |