WdfMemoryCreatePreallocated, fonction (wdfmemory.h)

[S’applique à KMDF et UMDF]

La méthode WdfMemoryCreatePreallocated crée un objet mémoire d’infrastructure pour une mémoire tampon mémoire 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 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 tampon pointe.

[out] Memory

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

Valeur de retour

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

Pour obtenir la liste des autres valeurs de retour que la méthode WdfMemoryCreatePreallocated peut retourner, consultez Framework Object Creation Errors.

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

Remarques

La méthode WdfMemoryCreatePreallocated crée un objet mémoire d’infrastructure 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 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 requête 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 qui WdfMemoryCreatePreallocated créé.

L’objet parent par défaut pour chaque objet mémoire est l’objet de pilote framework qui représente le pilote appelé WdfMemoryCreatePreallocated. Si votre pilote crée un objet mémoire qu’il utilise avec un objet d’appareil spécifique, un objet de requête ou un autre objet framework, 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 mémoire de l’infrastructure qui WdfMemoryCreatePreallocated créé est supprimé, l’infrastructure ne désalloue pas la mémoire tampon préexistante. De même, un appel à WdfMemoryAssignBuffer ne désalloue pas la mémoire tampon précédemment affectée.

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

Exemples

L’exemple de code suivant alloue une mémoire tampon, puis crée un objet mémoire de 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
                                     );

Spécifications

Voir aussi

ExAllocatePoolWithTag

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT

WdfMemoryAssignBuffer

WdfMemoryCreate

WdfMemoryCreateFromLookaside