Fonction ZwReadFile (wdm.h)

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

Syntaxe

NTSYSAPI NTSTATUS ZwReadFile(
  [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 de fichier. Ce handle est créé par un appel réussi à ZwCreateFile ou ZwOpenFile.

[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 d’appareil et intermédiaires doivent définir ce paramètre sur NULL.

[in, optional] ApcRoutine

Ce paramètre est réservé. Les pilotes d’appareil et intermédiaires doivent définir ce pointeur sur NULL.

[in, optional] ApcContext

Ce paramètre est réservé. Les pilotes d’appareil 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 effectivement 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 vers la mémoire tampon.

[in, optional] ByteOffset

Pointeur vers une variable qui spécifie le décalage d’octet de début 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, ZwReadFile retourne une erreur.

Si l’appel à ZwCreateFile définit l’un des indicateurs CreateOptions FILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT, le Gestionnaire d’E/S conserve la position actuelle du fichier. Si c’est le cas, l’appelant de ZwReadFile peut spécifier que le décalage de position de fichier actif doit être utilisé au lieu 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.

ZwReadFile met à jour la position actuelle du fichier 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 à ZwReadFile. Cela modifie automatiquement la position actuelle du fichier en cette valeur ByteOffset , effectue l’opération de lecture, puis met à jour la position en fonction du nombre d’octets effectivement lus. Cette technique fournit le service de recherche et de lecture atomique de l’appelant.

[in, optional] Key

Les pilotes d’appareil et intermédiaires doivent définir ce pointeur sur NULL.

Valeur retournée

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

Remarques

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

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

ZwReadFile commence à lire à partir de l’objet ByteOffset donné ou de la position actuelle du fichier 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, aucune autre 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 avec la fin de l’opération de lecture en attendant le handle de fichier, FileHandle. Le handle est signalé chaque fois qu’une opération d’E/S é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, ZwReadFile 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.

• ZwReadFile a retourné STATUS_PENDING.

Un pilote doit appeler ZwReadFile 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 à ZwReadFile.

• ZwReadFile informe le pilote de l’achèvement des E/S au moyen d’un événement créé par le pilote.

• ZwReadFile avertit le pilote de l’achèvement des E/S au moyen d’une routine de rappel APC que le pilote transmet à ZwReadFile.

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 fichier ou handle d’événement qu’il transmet à ZwReadFile dans le contexte du processus système plutôt que dans le contexte du processus dans lequel se trouve le pilote.

De même, ZwReadFile 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 ZwReadFile dans le contexte d’un processus autre que celui du 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 ZwReadFile doivent être en cours d’exécution à 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 ».

Configuration requise

Voir aussi

KeInitializeEvent

ZwCreateFile

ZwQueryInformationFile

ZwSetInformationFile

ZwWriteFile