Fonction NtWriteFile (ntifs.h)

  • Article

La routine ZwWriteFile écrit des données dans un fichier ouvert.

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtWriteFile(
  [in]           HANDLE           FileHandle,
  [in, optional] HANDLE           Event,
  [in, optional] PIO_APC_ROUTINE  ApcRoutine,
  [in, optional] PVOID            ApcContext,
  [out]          PIO_STATUS_BLOCK IoStatusBlock,
  [in]           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 sur l’état signalé une fois l’opération d’écriture 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 d’écriture demandée. Le membre Information reçoit le nombre d’octets réellement écrits dans le fichier.

[in] Buffer

Pointeur vers une mémoire tampon allouée à l’appelant qui contient les données à écrire dans le 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’octets de début dans le fichier pour le début de l’opération d’écriture. Si Length et ByteOffset spécifient une opération d’écriture au-delà de la marque de fin de fichier actuelle, NtWriteFile étend automatiquement le fichier et met à jour la marque de fin de fichier ; Tous les octets qui ne sont pas explicitement écrits entre ces anciennes et nouvelles marques de fin de fichier sont définis comme étant zéro.

Si l’appel à NtCreateFile définit uniquement l’indicateur DesiredAccess FILE_APPEND_DATA, ByteOffset est ignoré. Les données de la mémoire tampon donnée, pour Les octets de longueur , sont écrites à partir de la fin actuelle du fichier.

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 NtWriteFile 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.

NtWriteFile met à jour la position du fichier actuel en ajoutant le nombre d’octets écrits lorsqu’il termine l’opération d’écriture, 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 à NtWriteFile. Cela remplace automatiquement la position du fichier actuel par cette valeur ByteOffset, effectue l’opération d’écriture, puis met à jour la position en fonction du nombre d’octets réellement écrits. Cette technique fournit le service de recherche et d’écriture atomique de l’appelant.

Il est également possible de faire démarrer une opération d’écriture à la fin actuelle du fichier en spécifiant pour ByteOffset un pointeur vers une valeur LARGE_INTEGER avec HighPart défini sur -1 et LowPart défini sur FILE_WRITE_TO_END_OF_FILE. Cela fonctionne que le Gestionnaire d’E/S conserve ou non la position actuelle du fichier.

[in, optional] Key

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

Valeur retournée

NtWriteFile retourne STATUS_SUCCESS en cas de réussite ou le code d’erreur NTSTATUS approprié en cas d’échec.

Remarques

Les appelants de NtWriteFile doivent avoir déjà appelé NtCreateFile avec l’indicateur FILE_WRITE_DATA, FILE_APPEND_DATA ou GENERIC_WRITE défini dans le paramètre DesiredAccess . Notez que le fait d’avoir uniquement FILE_APPEND_DATA accès à un fichier ne permet pas à l’appelant d’écrire n’importe où dans le fichier, sauf à la marque de fin de fichier actuelle, tandis que le fait d’avoir FILE_WRITE_DATA accès à un fichier n’empêche pas l’appelant d’écrire à la fin d’un fichier ou au-delà.

Si l’appel précédent à NtCreateFile définit l’indicateur CreateOptions FILE_NO_INTERMEDIATE_BUFFERING, les paramètres Length et ByteOffset sur NtWriteFile doivent faire partie intégrante de la taille de secteur. Pour plus d’informations, consultez NtCreateFile.

NtWriteFile commence l’opération d’écriture dans le fichier à l’emplacement ByteOffset, à la position actuelle du fichier ou à la marque de fin du fichier. Il met fin à l’opération d’écriture lorsqu’il a écrit des octets de longueur à partir de Buffer. Si nécessaire, il étend la longueur du fichier et réinitialise la marque de fin de fichier.

Si l’appelant a ouvert le fichier avec l’indicateur DesiredAccess SYNCHRONIZE défini, l’appelant peut attendre que cette routine définisse le FileHandle donné à l’état signalé.

Les pilotes doivent appeler NtWriteFile dans le contexte du processus système dans trois cas :

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

Les handles de fichiers et d’événements ne sont valides que dans le contexte de processus dans lequel les handles sont créés. Par conséquent, pour éviter les failles de sécurité, le pilote doit créer tout fichier ou handle d’événement qu’il transmet à NtWriteFile dans le contexte du processus système au lieu du contexte de processus dans lequel se trouve le pilote.

De même, NtWriteFile 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 NtWriteFile dans le contexte d’un processus autre que le processus système, l’APC peut être retardé indéfiniment ou ne pas se déclencher du tout, car le thread d’origine peut ne jamais entrer dans un état d’attente pouvant être alerté.

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

Les appelants de NtWriteFile 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 « NtWriteFile » au lieu de « ZwWriteFile ».

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

Condition requise Valeur
Client minimal pris en charge Windows 2000
Plateforme cible Universal
En-tête ntifs.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (voir la section Remarques)
Règles de conformité DDI HwStorPortProhibitedDDIs, PowerIrpDDis

Voir aussi

KeInitializeEvent

NtCreateFile

NtQueryInformationFile

NtReadFile

NtSetInformationFile