WdfMemoryCreate-Funktion (wdfmemory.h)

[Gilt für KMDF und UMDF]

Die WdfMemoryCreate-Methode erstellt ein Framework-Speicherobjekt 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 sein.

[in] PoolType

Ein POOL_TYPE-typisierter Wert, der den Speichertyp angibt, der zugewiesen werden soll.

[in, optional] PoolTag

Ein treiberdefiniertes Pooltag für den zugewiesenen Speicher. Debugger zeigen dieses Tag an. Treiber geben in der Regel eine Zeichenzeichenfolge von bis zu vier Zeichen an, durch einzelne Anführungszeichen getrennt, 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 des Treibers verwendet. Wenn der Dienstname mit "WDF" beginnt (der Name ist nicht groß 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 Nichtzero-Werts in Bytes des Puffers.

[out] Memory

Ein Zeiger auf einen Speicherort, der einen Handle an das neue Speicherobjekt empfängt.

[out, optional] Buffer

Ein Zeiger auf einen Speicherort, der 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
STATUS_INVALID_PARAMETER
Ein ungültiger Parameter wurde erkannt.
STATUS_INSUFFICIENT_RESOURCES
Es gab nicht genügend Arbeitsspeicher.
 

Eine Liste anderer Rückgabewerte, die die WdfMemoryCreate-Methode zurückgeben kann, finden Sie unter Framework-Objekterstellungsfehler.

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

Bemerkungen

Die WdfMemoryCreate-Methode weist einen Puffer der Größe zu, die der Parameter BufferSize angibt und ein Framework-Speicherobjekt erstellt, das den Puffer darstellt.

Um die Adresse des Puffers abzurufen, kann Der Treiber einen Nicht-NULL-Wert für den Parameter "Puffer" der WdfMemoryCreate-Funktion angeben, oder der Treiber kann WdfMemoryGetBuffer aufrufen.

Es empfiehlt sich, keinen Arbeitsspeicher für die Speicherzuweisung zu verwenden, insbesondere für Zuordnungen, die an einen nicht vertrauenswürdigen Speicherort (Benutzermodus, über das Netzwerk usw.) kopiert werden, um vertrauliche Informationen zu vermeiden. WdfMemoryCreate initialisiert standardmäßig keinen zugewiesenen Arbeitsspeicher.

Basierend auf dem Nutzungsmuster des zugewiesenen Arbeitsspeichers ist die Empfehlung für Treiberautoren zu berücksichtigen:

  • RtlZeroMemory unmittelbar nach dem Aufrufen von WdfMemoryCreate
  • Verwenden Sie auch 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 der übergeordneten Löschung gelöscht wird, ist dies nicht der beste Ansatz.

Das standard übergeordnete Objekt für jedes Speicherobjekt ist das Frameworktreiberobjekt, das den Treiber darstellt, der den Treiber darstellt, der WdfMemoryCreate genannt hat. Wenn Ihr Treiber ein Speicherobjekt erstellt, das er mit einem bestimmten Geräteobjekt, einem Anforderungsobjekt oder einem anderen Frameworkobjekt verwendet, sollte das übergeordnete Speicherobjekt entsprechend festgelegt werden. Das Speicherobjekt und sein Puffer werden gelöscht, wenn das übergeordnete Objekt gelöscht wird. Wenn Sie das standard übergeordnete Objekt nicht ändern, bleibt das Speicherobjekt und sein Puffer erhalten, bis der I/O-Manager den Treiber deaktiviert.

Ein Treiber kann auch ein Speicherobjekt und seinen Puffer löschen, indem WdfObjectDelete aufgerufen wird.

Wenn PufferSize kleiner als PAGE_SIZE ist, gibt das Betriebssystem dem Aufrufer genau die Anzahl der angeforderten Bytes des Arbeitsspeichers. Der Puffer ist nicht unbedingt seitenbündig, aber es wird durch die Anzahl von Bytes ausgerichtet, die die MEMORY_ALLOCATION_ALIGNMENT Konstante in Ntdef.h angibt.

Wenn PufferSize PAGE_SIZE oder höher ist, weist das System nur einen Seitenausrichtungspuffer zu. Wenn der PoolType-ParameterNichtPagedPool ist, weist das System die Anzahl der Seiten zu, die erforderlich sind, um alle Bytes zu halten. Alle nicht verwendeten Bytes auf der letzten zugewiesenen Seite werden im Wesentlichen verschwendet.

Weitere Informationen zu Framework-Speicherobjekten finden Sie unter Verwenden von Speicherpuffern.

Wenn Ihr Treiber PagedPool für PoolType angibt, muss die WdfMemoryCreate-Methode bei IRQL <= APC_LEVEL aufgerufen werden. Andernfalls kann die Methode bei IRQL <= DISPATCH_LEVEL aufgerufen werden.

Beispiele

Im folgenden Codebeispiel wird ein Framework-Speicherobjekt erstellt und ein Puffer zugewiesen, 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
                         );

Requirements (Anforderungen)

   
Zielplattform Universell
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Header wdfmemory.h (enthalten Wdf.h)
Bibliothek Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL Siehe Abschnitt "Hinweise".
DDI-Complianceregeln DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ParentObjectCheck(kmdf)

Weitere Informationen

POOL_TYPE

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT

WdfMemoryCreateFromLookaside

WdfMemoryCreatePreallocated

WdfMemoryGetBuffer

WdfObjectDelete