WdfMemoryCreate-Funktion (wdfmemory.h)
[Gilt für KMDF und UMDF]
Die WdfMemoryCreate-Methode erstellt ein Frameworkspeicherobjekt und weist einen Speicherpuffer einer angegebenen Größe zu.
Syntax
NTSTATUS WdfMemoryCreate(
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[in] POOL_TYPE PoolType,
[in, optional] ULONG PoolTag,
[in] size_t BufferSize,
[out] WDFMEMORY *Memory,
[out, optional] PVOID *Buffer
);
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] PoolType
Ein POOL_TYPE typisierter Wert, der den Typ des zuzuweisenden Arbeitsspeichers angibt.
[in, optional] PoolTag
Ein vom Treiber definiertes Pooltag für den zugeordneten Arbeitsspeicher. Debugger zeigen dieses Tag an. Treiber geben in der Regel eine Zeichenfolge von bis zu vier Zeichen an, die durch einfache Anführungszeichen getrennt ist, in umgekehrter Reihenfolge (z. B. "dcba"). Der ASCII-Wert jedes Zeichens im Tag muss zwischen 0 und 127 sein. Das Debuggen Ihres Treibers ist einfacher, wenn jedes Pooltag eindeutig ist.
Wenn PoolTag null ist, stellt das Framework ein Standardpooltag bereit, das die ersten vier Zeichen des Kernelmodusdienstnamens Ihres Treibers verwendet. Wenn der Dienstname mit "WDF" beginnt (der Name beachtet die Groß-/Kleinschreibung nicht und enthält keine Anführungszeichen), werden die nächsten vier Zeichen verwendet. Wenn weniger als vier Zeichen verfügbar sind, wird "FxDr" verwendet.
Für KMDF-Versionen 1.5 und höher kann Ihr Treiber das DriverPoolTag-Element der WDF_DRIVER_CONFIG-Struktur verwenden, um ein Standardpooltag anzugeben.
[in] BufferSize
Die angegebene Größe des Puffers ungleich 0 (in Byte).
[out] Memory
Ein Zeiger auf einen Speicherort, der ein Handle für das neue Speicherobjekt empfängt.
[out, optional] Buffer
Ein Zeiger auf eine Position, die einen Zeiger auf den Puffer empfängt, der dem neuen Speicherobjekt zugeordnet ist. Dieser Parameter ist optional und kann NULL sein.
Rückgabewert
WdfMemoryCreate 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 |
|---|---|
|
Ein ungültiger Parameter wurde erkannt. |
|
Es war nicht genügend Arbeitsspeicher vorhanden. |
Eine Liste mit anderen Rückgabewerten, die von der WdfMemoryCreate-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 WdfMemoryCreate-Methode ordnet einen Puffer der Größe zu, die der BufferSize-Parameter angibt, und erstellt ein Frameworkspeicherobjekt, das den Puffer darstellt.
Um die Adresse des Puffers abzurufen, kann Der Treiber einen Wert ungleich NULL für den Buffer-Parameter der WdfMemoryCreate-Funktion angeben, oder der Treiber kann WdfMemoryGetBuffer aufrufen.
Es empfiehlt sich, arbeitsspeicherfrei für die Speicherbelegung zu verwenden, insbesondere für Zuordnungen, die an einen nicht vertrauenswürdigen Speicherort (Benutzermodus, Netzwerk usw.) kopiert werden, um die Offenlegung vertraulicher Informationen zu vermeiden. WdfMemoryCreate initialisiert den zugeordneten Arbeitsspeicher nicht standardmäßig 0.
Basierend auf dem Nutzungsmuster des zugeordneten Arbeitsspeichers des Treibers empfiehlt es sich für Treiberautoren, Folgendes zu berücksichtigen:
- RtlZeroMemory unmittelbar nach dem Aufruf von WdfMemoryCreate
- Oder verwenden Sie eine Nullzuordnungs-API (ExAllocatePool2, ExAllocatePoolZero für den Kernelmodus; HeapAlloc mit dem HEAP_ZERO_MEMORY Flag für den Benutzermodus), gefolgt von WdfMemoryCreatePreallocated. Da der vorab zugewiesene Puffer nicht automatisch als Teil von WDFMEMORY oder dem übergeordneten Löschen gelöscht wird, ist dies nicht der beste Ansatz.
Das übergeordnete Standardobjekt für jedes Speicherobjekt ist das Frameworktreiberobjekt, das den Treiber darstellt, der WdfMemoryCreate 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 und sein Puffer werden gelöscht, wenn das übergeordnete Objekt gelöscht wird. Wenn Sie das übergeordnete Standardobjekt nicht ändern, bleiben das Speicherobjekt und sein Puffer erhalten, bis der E/A-Manager Den Treiber entladen hat.
Ein Treiber kann auch ein Speicherobjekt und seinen Puffer löschen, indem er WdfObjectDelete aufruft.
Wenn BufferSize kleiner als PAGE_SIZE ist, gibt das Betriebssystem dem Aufrufer genau die Anzahl der angeforderten Bytes an Arbeitsspeicher. Der Puffer ist nicht notwendigerweise seitenbündig ausgerichtet, aber er wird durch die Anzahl der Bytes ausgerichtet, die die MEMORY_ALLOCATION_ALIGNMENT Konstante in Ntdef.h angibt.
Wenn BufferSize PAGE_SIZE oder höher ist, weist das System für KMDF nur einen seitenbündigen Puffer zu. Wenn der PoolType-ParameterNonPagedPool ist, ordnet das System die Anzahl der Seiten zu, die erforderlich sind, um alle Bytes zu enthalten. Alle nicht verwendeten Bytes auf der zuletzt zugeordneten Seite werden im Wesentlichen verschwendet.
Weitere Informationen zu Frameworkspeicherobjekten finden Sie unter Verwenden von Speicherpuffern.
Wenn Ihr Treiber PagedPool für PoolType angibt, muss die WdfMemoryCreate-Methode unter IRQL <= APC_LEVEL aufgerufen werden. Andernfalls kann die -Methode unter IRQL <= DISPATCH_LEVEL aufgerufen werden.
Beispiele
Im folgenden Codebeispiel wird ein Frameworkspeicherobjekt erstellt und ein Puffer zugeordnet, dessen Größe WRITE_BUFFER_SIZE ist. Das übergeordnete Speicherobjekt ist ein Anforderungsobjekt.
NTSTATUS status;
WDF_OBJECT_ATTRIBUTES attributes;
WDFMEMORY writeBufferMemHandle;
PVOID writeBufferPointer;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = requestHandle;
status = WdfMemoryCreate(
&attributes,
NonPagedPool,
0,
WRITE_BUFFER_SIZE,
&writeBufferMemHandle,
&writeBufferPointer
);
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 | Weitere Informationen finden Sie im Abschnitt mit den Hinweisen. |
| DDI-Complianceregeln | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ParentObjectCheck(kmdf) |