Fonction IoBuildPartialMdl (wdm.h)

Article
02/27/2024

La routine IoBuildPartialMdl génère une nouvelle liste de descripteurs de mémoire (MDL) qui représente une partie d’une mémoire tampon décrite par une MDL existante.

Syntaxe

void IoBuildPartialMdl(
  [in]      PMDL  SourceMdl,
  [in, out] PMDL  TargetMdl,
  [in]      PVOID VirtualAddress,
  [in]      ULONG Length
);

Paramètres

[in] SourceMdl

Pointeur vers une MDL qui décrit la mémoire tampon d’origine, dont une sous-plage doit être mappée.

[in, out] TargetMdl

Pointeur vers une MDL allouée par l’appelant. Cette MDL doit être suffisamment grande pour décrire les pages de la sous-plage spécifiées par VirtualAddress et Length.

[in] VirtualAddress

Pointeur vers l’adresse virtuelle de base pour la sous-plage à décrire par TargetMdl.

[in] Length

Spécifie la longueur, en octets, à mapper par TargetMdl. Cette valeur, en combinaison avec VirtualAddress, doit spécifier une mémoire tampon qui est une sous-plage appropriée de la mémoire tampon décrite par SourceMdl. Si Length est égal à zéro, la sous-plage à mapper commence à VirtualAddress et inclut la plage restante décrite par SourceMdl.

Valeur de retour

None

Remarques

Cette routine génère une MDL cible qui décrit une sous-plage de la mémoire tampon décrite par le MDL source. Cette sous-plage est spécifiée par les paramètres VirtualAddress et Length . Les paramètres SourceMdl et TargetMdl pointent vers le MDL source et le MDL cible.

Un pilote peut utiliser IoBuildPartialMdl pour fractionner une demande de transfert volumineuse en demandes de transfert plus petites. Les pages physiques décrites par la MDL source doivent être verrouillées avant que le pilote appelle IoBuildPartialMdl. En règle générale, la MDL source décrit une mémoire tampon dans l’espace d’adressage utilisateur, et le pilote appelle la routine MmProbeAndLockPages pour verrouiller les pages de cette mémoire tampon. Toutefois, le pilote peut générer la MDL source à partir de la mémoire non paginée en appelant la routine MmBuildMdlForNonPagedPool, MmAllocatePagesForMdlEx ou MmAllocatePagesForMdl .

Lors de la création d’une MDL partielle :

Si la MDL d’origine a déjà été mappée dans l’espace système, la MDL partielle partage ce mappage et il n’est pas nécessaire de la mapper à nouveau.
Si la MDL d’origine n’a pas été mappée dans l’espace système, la MDL partielle ne l’est pas non plus. Si vous avez besoin d’une adresse en mode système, appelez MmGetSystemAddressForMdlSafe sur la MDL partielle.
Si vous ne savez pas laquelle des opérations ci-dessus s’applique, il est prudent d’appeler MmGetSystemAddressForMdlSafe . Si une MDL partielle est générée à partir d’un MDL source déjà mappé dans l’espace d’adressage système, MmGetSystemAddressForMdlSafe utilise le mappage de source existant. Sinon, MmGetSystemAddressForMdlSafe crée un mappage.

Pour éviter la fuite de ce nouveau mappage, les pilotes doivent appeler MmPrepareMdlForReuse avant de réutiliser une MDL partielle. En outre, la routine IoFreeMdl libère le mappage d’espace d’adressage système pour une MDL partielle, si un tel mappage existe.

Pour plus d’informations sur les DLL, consultez Utilisation de MDL.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 2000.
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	MdlAfterReqCompletedIntIoctlA(kmdf), MdlAfterReqCompletedIoctlA(kmdf), MdlAfterReqCompletedReadA(kmdf), MdlAfterReqCompletedWriteA(kmdf)