Fonction ProbeForWrite (wdm.h)

Avertissement

La fonction ProbeForWrite n’est pas recommandée pour une utilisation dans les logiciels actuels et est incluse uniquement pour la compatibilité historique. Utilisez ProbeForRead à la place lors de la validation des mémoires tampons utilisateur. Pour plus d’informations, consultez Remarques.

La routine ProbeForWrite vérifie qu’une mémoire tampon en mode utilisateur réside réellement dans la partie en mode utilisateur de l’espace d’adressage, qu’elle est accessible en écriture et qu’elle est correctement alignée.

Syntaxe

void ProbeForWrite(
  [in, out] volatile VOID *Address,
  [in]      SIZE_T        Length,
  [in]      ULONG         Alignment
);

Paramètres

[in, out] Address

Spécifie le début de la mémoire tampon en mode utilisateur.

[in] Length

Spécifie la longueur, en octets, de la mémoire tampon en mode utilisateur. Consultez des informations supplémentaires dans la section Remarques.

[in] Alignment

Spécifie l’alignement requis, en octets, du début de la mémoire tampon en mode utilisateur.

Valeur de retour

None

Remarques

Cette fonction n’offre généralement aucun avantage substantiel par rapport à ProbeForRead , car un pilote robuste doit toujours être prêt à gérer les modifications de protection dans l’espace d’adressage virtuel du mode utilisateur, y compris les modifications de protection qui suppriment l’autorisation d’écriture sur une mémoire tampon passée à un pilote après l’exécution d’un appel ProbeForWrite . Étant donné que ProbeForWrite accède à chaque page de la mémoire tampon fournie, les performances peuvent être réduites en raison de la surcharge liée à l’accès à chaque page, en particulier si la mémoire tampon fournie décrit une grande région d’espace d’adressage virtuel. En outre, étant donné que ProbeForWrite écrit dans chaque page, la même mémoire tampon peut ne pas être utilisée en toute sécurité avec plusieurs demandes de pilotes simultanées. Pour ces raisons, le nouveau code de pilote doit toujours utiliser ProbeForRead à la place.

Le tableau suivant présente les propriétés de chaque routine d’interrogation de mémoire tampon en mode noyau :

Comportement	ProbeForRead	ProbeForWrite
Confirme que la mémoire tampon décrit une région dans l’espace d’adressage en mode utilisateur, si la longueur est différente de zéro	x	x
Confirme que l’adresse et la longueur de base de la mémoire tampon ne dépassent pas la valeur maximale du pointeur	x	x
Confirme que la mémoire tampon est alignée sur la limite d’alignement demandée, si la longueur est différente de zéro	x	x
Confirme que la mémoire tampon est initialement accessible en écriture (peut changer à tout moment si l’application en mode utilisateur reprotéger son espace d’adressage)		x
Accède à chaque page de la mémoire tampon (surcharge supplémentaire)		x
Modifie chaque page de la mémoire tampon (peut entraîner un comportement inattendu si la même mémoire tampon est utilisée en parallèle avec plusieurs demandes de pilote)		x

Historiquement, sur certains processeurs qui ne respectaient pas les autorisations en lecture seule pour le code en mode noyau, il existait des différences fonctionnelles significatives entre ProbeForWrite et ProbeForRead. Dans ce cas, le système d’exploitation s’appuyait précédemment sur ProbeForWrite pour effectuer une case activée d’écriture de pagination explicite. Cette distinction n’est plus significative pour les processeurs pris en charge par Windows NT 4.0 ou version ultérieure.

Remarques héritées

Les pilotes en mode noyau peuvent utiliser ProbeForWrite pour valider l’accès en écriture aux mémoires tampons allouées dans l’espace utilisateur. Il est le plus couramment utilisé pendant METHOD_NEITHER E/S pour valider la mémoire tampon utilisateur pointée par Irp-UserBuffer>.

Si la plage de mémoire spécifiée n’est pas une plage d’adresses valide en mode utilisateur ou n’est pas accessible en écriture (aucun accès, lecture seule, etc.), ProbeForWrite déclenche l’exception STATUS_ACCESS_VIOLATION. Si le début de la plage d’adresses n’est pas aligné sur la limite d’octet spécifiée par Alignement, ProbeForWrite déclenche l’exception STATUS_DATATYPE_MISALIGNMENT.

Les pilotes doivent appeler ProbeForWrite à l’intérieur d’un bloc try/except . Si la routine déclenche une exception, le pilote doit terminer l’IRP avec l’erreur appropriée. Notez que les accès ultérieurs par le pilote à la mémoire tampon en mode utilisateur doivent également être encapsulés dans un bloc try/except : une application malveillante peut avoir un autre thread supprimant, remplaçant ou modifiant la protection des plages d’adresses utilisateur à tout moment (même après ou pendant un appel à ProbeForRead ou ProbeForWrite). Pour plus d’informations, consultez Gestion des exceptions.

N’utilisez pas cette routine sur les adresses en mode noyau ; une exception est levée.

Si Irp-RequestorMode> = KernelMode, les champs Irp-AssociatedIrp.SystemBuffer> et Irp-UserBuffer> ne contiennent pas d’adresses en mode utilisateur, et un appel à ProbeForWrite pour sonder une mémoire tampon pointée par l’un ou l’autre champ génère une exception.

Si Length = 0, ProbeForWrite ne vérifie pas l’adresse. Dans ce cas, la routine ne génère pas d’exception pour une adresse qui est mal alignée ou qui se trouve en dehors de la plage des adresses utilisateur valides.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 2000.
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport),IrqlExApcLte2(wdm)

Voir aussi

ProbeForRead