Fonction NtReadFile (ntifs.h)

La routine NtReadFile lit les données d’un fichier ouvert.

Syntaxe

__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
);

Paramètres

[in] FileHandle

Gérez l’objet file. Ce handle est créé par un appel réussi à NtCreateFile ou NtOpenFile.

[in, optional] Event

Si vous le souhaitez, un handle pour un objet d’événement à définir à l’état signalé une fois l’opération de lecture terminée. Les pilotes de périphérique et intermédiaires doivent définir ce paramètre sur NULL.

[in, optional] ApcRoutine

Ce paramètre est réservé. Les pilotes de périphérique et intermédiaires doivent définir ce pointeur sur NULL.

[in, optional] ApcContext

Ce paramètre est réservé. Les pilotes de périphérique et intermédiaires doivent définir ce pointeur sur NULL.

[out] IoStatusBlock

Pointeur vers une structure de IO_STATUS_BLOCK qui reçoit le status d’achèvement final et des informations sur l’opération de lecture demandée. Le membre Information reçoit le nombre d’octets réellement lus à partir du fichier.

[out] Buffer

Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit les données lues à partir du fichier.

[in] Length

Taille, en octets, de la mémoire tampon pointée par Buffer.

[in, optional] ByteOffset

Pointeur vers une variable qui spécifie le décalage d’octet de départ dans le fichier où l’opération de lecture va commencer. Si une tentative de lecture est effectuée au-delà de la fin du fichier, NtReadFile retourne une erreur.

Si l’appel à NtCreateFile définit l’un des indicateurs CreateOptions FILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT, le Gestionnaire d’E/S conserve la position du fichier actuel. Dans ce cas, l’appelant de NtReadFile peut spécifier que le décalage de position de fichier actuel doit être utilisé à la place d’une valeur ByteOffset explicite. Cette spécification peut être effectuée à l’aide de l’une des méthodes suivantes :

• Spécifiez un pointeur vers une valeur LARGE_INTEGER avec le membre HighPart défini sur -1 et le membre LowPart défini sur la valeur définie par le système FILE_USE_FILE_POINTER_POSITION.
• Passez un pointeur NULL pour ByteOffset.

NtReadFile met à jour la position du fichier actuel en ajoutant le nombre d’octets lus lorsqu’il termine l’opération de lecture, s’il utilise la position de fichier actuelle gérée par le Gestionnaire d’E/S.

Même lorsque le gestionnaire d’E/S conserve la position actuelle du fichier, l’appelant peut réinitialiser cette position en passant une valeur ByteOffset explicite à NtReadFile. Cette opération remplace automatiquement la position du fichier actuel par cette valeur ByteOffset , effectue l’opération de lecture, puis met à jour la position en fonction du nombre d’octets réellement lus. Cette technique fournit à l’appelant un service atomique de recherche et de lecture.

[in, optional] Key

Les pilotes de périphérique et intermédiaires doivent définir ce pointeur sur NULL.

Valeur retournée

NtReadFile retourne STATUS_SUCCESS ou le code d’erreur NTSTATUS approprié.

Remarques

Les appelants de NtReadFile doivent déjà avoir appelé NtCreateFile avec la valeur FILE_READ_DATA ou GENERIC_READ définie dans le paramètre DesiredAccess .

Si l’appel précédent à NtCreateFile définit l’indicateur FILE_NO_INTERMEDIATE_BUFFERING dans le paramètre CreateOptions sur NtCreateFile, les paramètres Length et ByteOffset sur NtReadFile doivent être des multiples de la taille du secteur.

NtReadFile commence la lecture à partir du ByteOffset donné ou de la position de fichier actuelle dans la mémoire tampon donnée. Il met fin à l’opération de lecture dans l’une des conditions suivantes :

• La mémoire tampon est pleine, car le nombre d’octets spécifié par le paramètre Length a été lu. Par conséquent, plus aucune donnée ne peut être placée dans la mémoire tampon sans dépassement de capacité.
• La fin du fichier étant atteinte pendant l’opération de lecture, il n’y a plus de données dans le fichier à transférer dans la mémoire tampon.

Si l’appelant a ouvert le fichier avec l’indicateur SYNCHRONIZE défini dans DesiredAccess, le thread appelant peut se synchroniser à la fin de l’opération de lecture en attendant sur le handle de fichier , FileHandle. Le handle est signalé chaque fois qu’une opération d’E/S qui a été émise sur le handle se termine. Toutefois, l’appelant ne doit pas attendre un handle ouvert pour l’accès synchrone aux fichiers (FILE_SYNCHRONOUS_IO_NONALERT ou FILE_SYNCHRONOUS_IO_ALERT). Dans ce cas, NtReadFile attend au nom de l’appelant et ne retourne pas tant que l’opération de lecture n’est pas terminée. L’appelant peut attendre en toute sécurité sur le handle de fichier uniquement si les trois conditions suivantes sont remplies :

• Le handle a été ouvert pour l’accès asynchrone (autrement dit, aucun indicateur FILE_SYNCHRONOUS_IO_XXX n’a été spécifié).
• Le handle est utilisé pour une seule opération d’E/S à la fois.
• NtReadFile a renvoyé STATUS_PENDING.

Un pilote doit appeler NtReadFile dans le contexte du processus système si l’une des conditions suivantes existe :

• Le pilote a créé le handle de fichier qu’il transmet à NtReadFile.
• NtReadFile informe le pilote de l’achèvement des E/S au moyen d’un événement créé par le pilote.
• NtReadFile informera le pilote de l’achèvement des E/S au moyen d’une routine de rappel APC que le pilote transmet à NtReadFile.

Les handles de fichiers et d’événements sont valides uniquement dans le contexte de processus où les handles sont créés. Par conséquent, pour éviter les failles de sécurité, le pilote doit créer n’importe quel handle de fichier ou d’événement qu’il transmet à NtReadFile dans le contexte du processus système plutôt que dans le contexte du processus dans lequel se trouve le pilote.

De même, NtReadFile doit être appelé dans le contexte du processus système s’il avertit le pilote de l’achèvement des E/S au moyen d’un APC, car les API sont toujours déclenchées dans le contexte du thread qui émet la demande d’E/S. Si le pilote appelle NtReadFile dans le contexte d’un processus autre que le système, l’APC peut être retardé indéfiniment ou ne pas se déclencher du tout.

Pour plus d’informations sur l’utilisation des fichiers, consultez Utilisation de fichiers dans un pilote.

Les appelants de NtReadFile doivent s’exécuter sur IRQL = PASSIVE_LEVEL et avec des API de noyau spéciales activées.

Si l’appel à cette fonction se produit en mode utilisateur, vous devez utiliser le nom « NtReadFile » au lieu de « ZwReadFile ».

Pour les appels provenant de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Using Nt and Zw Versions of the Native System Services Routines.

Configuration requise

Voir aussi

KeInitializeEvent

ZwCreateFile

NtQueryInformationFile

NtSetInformationFile

NtWriteFile