WdfMemoryCreatePreallocated-Funktion (wdfmemory.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WdfMemoryCreatePreallocated-Methode erstellt ein Frameworkspeicherobjekt für einen vom Treiber bereitgestellten Speicherpuffer.

Syntax

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

Parameter

[in, optional] Attributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES-Struktur , die Objektattribute für das neue Speicherobjekt enthält. Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[in] Buffer

Ein Zeiger auf einen vom Treiber bereitgestellten Puffer.

[in] BufferSize

Die nichtzero-Größe des Puffers, auf den Puffer verweist, in Bytes.

[out] Memory

Ein Zeiger auf eine Position, die ein Handle auf das neue Speicherobjekt empfängt.

Rückgabewert

WdfMemoryCreatePreallocated gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde erkannt.
STATUS_INSUFFICIENT_RESOURCES	Es war nicht genügend Arbeitsspeicher vorhanden.

Eine Liste mit anderen Rückgabewerten, die von der WdfMemoryCreatePreallocated-Methode möglicherweise zurückgegeben werden, finden Sie unter Fehler beim Erstellen von Frameworkobjekten.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Hinweise

Die WdfMemoryCreatePreallocated-Methode erstellt ein Frameworkspeicherobjekt für einen Puffer, den der Treiber zuvor zugewiesen oder abgerufen hat.

Ihr Treiber kann WdfMemoryCreatePreallocated aufrufen, wenn Sie Speicherobjekte erstellen müssen, die bereits vorhandene Speicherpuffer darstellen. Beispielsweise kann der Treiber eine vom Treiber definierte Struktur innerhalb eines Puffers für eine E/A-Anforderung empfangen, die einen internen E/A-Steuerungscode enthält. Der Treiber kann WdfMemoryCreatePreallocated aufrufen, um ein Speicherobjekt zu erstellen, damit der Treiber die Struktur an ein E/A-Ziel übergeben kann.

Nachdem ein Treiber WdfMemoryCreatePreallocated aufgerufen hat, kann der Treiber WdfMemoryAssignBuffer aufrufen, um dem von WdfMemoryCreatePreallocated erstellten Speicherobjekt einen anderen Puffer zuzuweisen.

Das übergeordnete Standardobjekt für jedes Speicherobjekt ist das Frameworktreiberobjekt, das den Treiber darstellt, der WdfMemoryCreatePreallocated aufgerufen hat. Wenn Ihr Treiber ein Speicherobjekt erstellt, das er mit einem bestimmten Geräteobjekt, Anforderungsobjekt oder einem anderen Frameworkobjekt verwendet, sollte er das übergeordnete Speicherobjekt entsprechend festlegen. Das Speicherobjekt wird gelöscht, wenn das übergeordnete Objekt gelöscht wird. Wenn Sie das übergeordnete Standardobjekt nicht ändern, bleibt das Speicherobjekt im Arbeitsspeicher, bis der E/A-Manager Den Treiber entladen hat.

Ein Treiber kann auch ein Speicherobjekt löschen, indem er WdfObjectDelete aufruft.

Wenn das von WdfMemoryCreatePreallocated erstellte Frameworkspeicherobjekt gelöscht wird, wird der bereits vorhandene Puffer nicht vom Framework zugeordnet. Ebenso wird bei einem Aufruf von WdfMemoryAssignBuffer die Zuordnung des zuvor zugewiesenen Puffers nicht aufgehoben.

Weitere Informationen zu Frameworkspeicherobjekten finden Sie unter Verwenden von Speicherpuffern.

Beispiele

Im folgenden Codebeispiel wird ein Puffer zugeordnet und dann ein Frameworkspeicherobjekt für den Puffer erstellt.

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
                                     );

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfmemory.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWriteA(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)