Fonction ZwWriteFile (wdm.h)
La routine ZwWriteFile écrit des données dans un fichier ouvert.
Syntaxe
NTSYSAPI NTSTATUS ZwWriteFile(
[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 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 d’écriture 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 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 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 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, ZwWriteFile étend automatiquement le fichier et met à jour la marque de fin de fichier ; tous les octets qui ne sont pas écrits explicitement entre ces marques de fin de fichier anciennes et nouvelles sont définis comme étant zéro.
Si l’appel à ZwCreateFile 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 à 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 ZwWriteFile peut spécifier que le décalage de position du 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.
ZwWriteFile met à jour la position actuelle du fichier 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 à ZwWriteFile. Cela modifie automatiquement la position du fichier actuelle en 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 au 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 d’appareil et intermédiaires doivent définir ce pointeur sur NULL.
Valeur retournée
ZwWriteFile retourne STATUS_SUCCESS en cas de réussite ou le code d’erreur NTSTATUS approprié en cas d’échec.
Remarques
Les appelants de ZwWriteFile doivent avoir déjà appelé ZwCreateFile 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 dans ou au-delà de la fin d’un fichier.
Si l’appel précédent à ZwCreateFile définit l’indicateur CreateOptions FILE_NO_INTERMEDIATE_BUFFERING, les paramètres Length et ByteOffset sur ZwWriteFile doivent faire partie intégrante de la taille du secteur. Pour plus d’informations, consultez ZwCreateFile.
ZwWriteFile commence l’opération d’écriture dans le fichier à l’emplacement ByteOffset, à la position actuelle du fichier ou à la marque de fin de fichier. Il met fin à l’opération d’écriture lorsqu’il a écrit des octets de longueur dans La mémoire tampon. 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 ZwWriteFile dans le contexte du processus système dans trois cas :
Le pilote crée le handle de fichier qu’il transmet à ZwWriteFile.
ZwWriteFile avertit le pilote de l’achèvement des E/S au moyen d’un événement créé par le pilote.
ZwWriteFile avertit le pilote de l’achèvement des E/S au moyen d’une routine de rappel APC que le pilote transmet à ZwWriteFile.
Les handles de fichiers et d’événements ne sont valides que 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 à ZwWriteFile dans le contexte du processus système au lieu du contexte de processus dans lequel se trouve le pilote.
De même, ZwWriteFile 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 ZwWriteFile dans le contexte d’un processus autre que le processus système, l’APC peut être retardé indéfiniment, ou il peut 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 ZwWriteFile 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 « NtWriteFile » au lieu de « ZwWriteFile ».
Pour les appels à partir 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 Utilisation des versions Nt et Zw des routines des services système natifs.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Universal |
| En-tête | wdm.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(storport),PowerIrpDDis(wdm) |