Fonction NtReadFile
Lit les données d’un fichier ouvert.
Cette fonction est l’équivalent en mode utilisateur de la fonction ZwReadFile documentée dans le Kit de pilotes Windows (WDK).
Syntaxe
NTSTATUS NtReadFile(
_In_ HANDLE FileHandle,
_In_opt_ HANDLE Event,
_In_opt_ PIO_APC_ROUTINE ApcRoutine,
_In_opt_ PVOID ApcContext,
_Out_ PIO_STATUS_BLOCK IoStatusBlock,
_Out_ PVOID Buffer,
_In_ ULONG Length,
_In_opt_ PLARGE_INTEGER ByteOffset,
_In_opt_ PULONG Key
);
Paramètres
-
FileHandle [in]
-
Gérez l’objet de fichier. Ce handle est créé par un appel réussi à NtCreateFile ou NtOpenFile.
-
Événement [in, facultatif]
-
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.
-
ApcRoutine [in, facultatif]
-
Ce paramètre est réservé. Les pilotes d’appareil et intermédiaires doivent définir ce pointeur sur NULL.
-
ApcContext [in, facultatif]
-
Ce paramètre est réservé. Les pilotes d’appareil et intermédiaires doivent définir ce pointeur sur NULL.
-
IoStatusBlock [out]
-
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.
-
Mémoire tampon [out]
-
Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit les données lues à partir du fichier.
-
Longueur [in]
-
Taille, en octets, de la mémoire tampon pointée vers la mémoire tampon.
-
ByteOffset [in, facultatif]
-
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, 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 actuelle du fichier. Si c’est le cas, l’appelant de NtReadFile peut spécifier que le décalage de position de fichier actuel 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.
NtReadFile 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 à NtReadFile. 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.
-
Clé [in, facultatif]
-
Les pilotes d’appareil et intermédiaires doivent définir ce pointeur sur NULL.
Valeur retournée
NtReadFile retourne STATUS_SUCCESS ou le code d’erreur NTSTATUS approprié.
Notes
Les appelants de NtReadFile doivent avoir déjà 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 plusieurs de la taille du secteur. Pour plus d’informations, consultez NtCreateFile.
NtReadFile 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, 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 retourné 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 avertit le pilote de l’achèvement des E/S au moyen d’un événement créé par le pilote.
NtReadFile informe 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 fichier ou handle 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 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 NtReadFile doivent être en cours d’exécution dans IRQL = PASSIVE_LEVEL et avec des API de noyau spéciales activées.
Spécifications
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge |
Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge |
Windows 2000 Server [applications de bureau uniquement] |
| Plateforme cible |
|
| En-tête |
|
| Bibliothèque |
|
| DLL |
|
Voir aussi