WdfMemoryCreatePreallocated, fonction (wdfmemory.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfMemoryCreatePreallocated crée un objet de mémoire framework pour une mémoire tampon fournie par le pilote.

Syntaxe

NTSTATUS WdfMemoryCreatePreallocated(
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [in]           __drv_aliasesMem PVOID Buffer,
  [in]           size_t                 BufferSize,
  [out]          WDFMEMORY              *Memory
);

Paramètres

[in, optional] Attributes

Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES qui contient des attributs d’objet pour le nouvel objet mémoire. Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[in] Buffer

Pointeur vers une mémoire tampon fournie par le pilote.

[in] BufferSize

Taille différente de zéro, en octets, de la mémoire tampon vers laquelle la mémoire tampon pointe.

[out] Memory

Pointeur vers un emplacement qui reçoit un handle vers le nouvel objet de mémoire.

Valeur retournée

WdfMemoryCreatePreallocated retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INSUFFICIENT_RESOURCES	La mémoire était insuffisante.

Pour obtenir la liste des autres valeurs de retour que la méthode WdfMemoryCreatePreallocated peut retourner, consultez Erreurs de création d’objets framework.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

Remarques

La méthode WdfMemoryCreatePreallocated crée un objet de mémoire framework pour une mémoire tampon que le pilote a précédemment allouée ou obtenue.

Votre pilote peut appeler WdfMemoryCreatePreallocated si vous devez créer des objets de mémoire qui représentent des mémoires tampons préexistantes. Par exemple, le pilote peut recevoir une structure définie par le pilote dans une mémoire tampon pour une demande d’E/S qui contient un code de contrôle d’E/S interne. Le pilote peut appeler WdfMemoryCreatePreallocated pour créer un objet mémoire afin que le pilote puisse passer la structure à une cible d’E/S.

Une fois qu’un pilote a appelé WdfMemoryCreatePreallocated, le pilote peut appeler WdfMemoryAssignBuffer pour affecter une mémoire tampon différente à l’objet mémoire créé par WdfMemoryCreatePreallocated .

L’objet parent par défaut pour chaque objet mémoire est l’objet pilote d’infrastructure qui représente le pilote qui a appelé WdfMemoryCreatePreallocated. Si votre pilote crée un objet de mémoire qu’il utilise avec un objet d’appareil, un objet de requête ou un autre objet framework spécifique, il doit définir le parent de l’objet mémoire de manière appropriée. L’objet mémoire est supprimé lorsque l’objet parent est supprimé. Si vous ne modifiez pas l’objet parent par défaut, l’objet mémoire reste en mémoire jusqu’à ce que le gestionnaire d’E/S décharge votre pilote.

Un pilote peut également supprimer un objet mémoire en appelant WdfObjectDelete.

Lorsque l’objet de mémoire framework créé par WdfMemoryCreatePreallocated est supprimé, l’infrastructure ne libère pas la mémoire tampon préexistante. De même, un appel à WdfMemoryAssignBuffer ne libère pas la mémoire tampon précédemment affectée.

Pour plus d’informations sur les objets de mémoire framework, consultez Utilisation de mémoire tampons.

Exemples

L’exemple de code suivant alloue une mémoire tampon, puis crée un objet de mémoire framework pour la mémoire tampon.

PVOID  pBuffer = NULL;
WDF_OBJECT_ATTRIBUTES  attributes;
WDFMEMORY  memHandle;

pBuffer = ExAllocatePoolWithTag(
                                NonPagedPool,
                                MY_BUFFER_SIZE,
                                MY_DRIVER_TAG
                                );
if (pBuffer == NULL){
    goto Error;
}
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = requestHandle;

status = WdfMemoryCreatePreallocated(
                                     &attributes,
                                     pBuffer,
                                     MY_BUFFER_SIZE,
                                     &memHandle
                                     );

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfmemory.h (include Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWriteA(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)