Función NtReadFile (ntifs.h)

La rutina NtReadFile lee datos de un archivo abierto.

Sintaxis

__kernel_entry NTSYSCALLAPI NTSTATUS NtReadFile(
  [in]           HANDLE           FileHandle,
  [in, optional] HANDLE           Event,
  [in, optional] PIO_APC_ROUTINE  ApcRoutine,
  [in, optional] PVOID            ApcContext,
  [out]          PIO_STATUS_BLOCK IoStatusBlock,
  [out]          PVOID            Buffer,
  [in]           ULONG            Length,
  [in, optional] PLARGE_INTEGER   ByteOffset,
  [in, optional] PULONG           Key
);

Parámetros

[in] FileHandle

Identificador del objeto de archivo. Este identificador se crea mediante una llamada correcta a NtCreateFile o NtOpenFile.

[in, optional] Event

Opcionalmente, un identificador de un objeto de evento para establecer en el estado señalado una vez completada la operación de lectura. Los controladores intermedios y de dispositivo deben establecer este parámetro en NULL.

[in, optional] ApcRoutine

Este parámetro está reservado. Los controladores intermedios y de dispositivo deben establecer este puntero en NULL.

[in, optional] ApcContext

Este parámetro está reservado. Los controladores intermedios y de dispositivo deben establecer este puntero en NULL.

[out] IoStatusBlock

Puntero a una estructura de IO_STATUS_BLOCK que recibe el estado de finalización final e información sobre la operación de lectura solicitada. El miembro Information recibe el número de bytes leídos realmente del archivo.

[out] Buffer

Puntero a un búfer asignado por el autor de la llamada que recibe los datos leídos del archivo.

[in] Length

Tamaño, en bytes, del búfer al que apunta Buffer.

[in, optional] ByteOffset

Puntero a una variable que especifica el desplazamiento de bytes inicial en el archivo donde se iniciará la operación de lectura. Si se intenta leer más allá del final del archivo, NtReadFile devuelve un error.

Si la llamada a NtCreateFile establece cualquiera de las marcas CreateOptions FILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT, el Administrador de E/S mantiene la posición del archivo actual. Si es así, el autor de la llamada de NtReadFile puede especificar que se use el desplazamiento de posición del archivo actual en lugar de un valor ByteOffset explícito. Esta especificación se puede realizar mediante uno de los métodos siguientes:

• Especifique un puntero a un valor de LARGE_INTEGER con el miembro HighPart establecido en -1 y el miembro LowPart establecido en el valor definido por el sistema FILE_USE_FILE_POINTER_POSITION.
• Pase un puntero NULL para ByteOffset.

NtReadFile actualiza la posición actual del archivo agregando el número de bytes leídos cuando completa la operación de lectura, si usa la posición del archivo actual mantenida por el Administrador de E/S.

Incluso cuando el Administrador de E/S mantiene la posición actual del archivo, el autor de la llamada puede restablecer esta posición pasando un valor ByteOffset explícito a NtReadFile. Esto cambia automáticamente la posición del archivo actual a ese valor ByteOffset , realiza la operación de lectura y, a continuación, actualiza la posición según el número de bytes leídos realmente. Esta técnica proporciona al autor de la llamada servicio atomic seek-and-read.

[in, optional] Key

Los controladores intermedios y de dispositivo deben establecer este puntero en NULL.

Valor devuelto

NtReadFile devuelve STATUS_SUCCESS o el código de error NTSTATUS adecuado.

Comentarios

Los autores de llamadas de NtReadFile ya deben haber llamado a NtCreateFile con el valor FILE_READ_DATA o GENERIC_READ establecido en el parámetro DesiredAccess .

Si la llamada anterior a NtCreateFile establece la marca FILE_NO_INTERMEDIATE_BUFFERING en el parámetro CreateOptions en NtCreateFile, los parámetros Length y ByteOffset en NtReadFile deben ser múltiplo del tamaño del sector.

NtReadFile comienza a leer desde el byteOffset especificado o la posición del archivo actual en el búfer especificado. Finaliza la operación de lectura en una de las condiciones siguientes:

• El búfer está lleno porque se ha leído el número de bytes especificados por el parámetro Length . Por lo tanto, no se pueden colocar más datos en el búfer sin desbordamiento.
• Se alcanza el final del archivo durante la operación de lectura, por lo que no hay más datos en el archivo que se van a transferir al búfer.

Si el autor de la llamada abrió el archivo con la marca SYNCHRONIZE establecida en DesiredAccess, el subproceso que realiza la llamada puede sincronizarse con la finalización de la operación de lectura esperando el identificador de archivo, FileHandle. El identificador se señala cada vez que se completa una operación de E/S que se emitió en el identificador. Sin embargo, el autor de la llamada no debe esperar a un identificador que se abrió para el acceso sincrónico a archivos (FILE_SYNCHRONOUS_IO_NONALERT o FILE_SYNCHRONOUS_IO_ALERT). En este caso, NtReadFile espera en nombre del autor de la llamada y no vuelve hasta que se complete la operación de lectura. El autor de la llamada puede esperar de forma segura en el identificador de archivo solo si se cumplen las tres condiciones siguientes:

• El identificador se abrió para el acceso asincrónico (es decir, no se especificó ninguna marca FILE_SYNCHRONOUS_IO_XXX ).
• El identificador se usa solo para una operación de E/S a la vez.
• NtReadFile devolvió STATUS_PENDING.

Un controlador debe llamar a NtReadFile en el contexto del proceso del sistema si existe alguna de las condiciones siguientes:

• El controlador creó el identificador de archivo que pasa a NtReadFile.
• NtReadFile notificará al controlador la finalización de E/S mediante un evento que el controlador creó.
• NtReadFile notificará al controlador la finalización de E/S mediante una rutina de devolución de llamada de APC que el controlador pasa a NtReadFile.

Los identificadores de archivos y eventos solo son válidos en el contexto de proceso donde se crean los identificadores. Por lo tanto, para evitar agujeros de seguridad, el controlador debe crear cualquier archivo o identificador de eventos que pase a NtReadFile en el contexto del proceso del sistema en lugar del contexto del proceso en el que se encuentra el controlador.

Del mismo modo, se debe llamar a NtReadFile en el contexto del proceso del sistema si notifica al controlador de finalización de E/S mediante un APC, ya que las API siempre se activan en el contexto del subproceso que emite la solicitud de E/S. Si el controlador llama a NtReadFile en el contexto de un proceso distinto del del sistema, el APC podría retrasarse indefinidamente o podría no activarse en absoluto.

Para obtener más información sobre cómo trabajar con archivos, vea Uso de archivos en un controlador.

Los autores de llamadas de NtReadFile deben ejecutarse en IRQL = PASSIVE_LEVEL y con las API de kernel especiales habilitadas.

Si la llamada a esta función se produce en modo de usuario, debe usar el nombre "NtReadFile" en lugar de "ZwReadFile".

En el caso de las llamadas desde controladores en modo kernel, las versiones NtXxx y ZwXxx de una rutina de Windows Native System Services pueden comportarse de forma diferente en la forma en que controlan e interpretan los parámetros de entrada. Para obtener más información sobre la relación entre las versiones NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000
Plataforma de destino	Universal
Encabezado	ntifs.h (incluye Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte la sección Comentarios)
Reglas de cumplimiento de DDI	BufAfterReqCompletedIntIoctlA, BufAfterReqCompletedIoctlA, BufAfterReqCompletedReadA, BufAfterReqCompletedWriteA, HwStorPortProhibitedDDIs, PowerIrpDDis

Consulte también

KeInitializeEvent

ZwCreateFile

NtQueryInformationFile

NtSetInformationFile

NtWriteFile