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

Die 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-typed-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 Zeichenfolge von bis zu vier Zeichen an, getrennt durch einfache Anführungszeichen, in umgekehrter Reihenfolge (z. B. "dcba"). Der ASCII-Wert jedes Zeichens im Tag muss zwischen 0 und 127 stehen. 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 (bei dem Namen wird die Groß-/Kleinschreibung nicht beachtet und die Anführungszeichen nicht eingeschlossen), 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 in Bytes.

[out] Memory

Ein Zeiger auf eine Position, die 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-werden.

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:

Eine Liste mit anderen Rückgabewerten, die von der WdfMemoryCreate Methode möglicherweise zurückgegeben werden, finden Sie unter Framework Object Creation Errors.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Bemerkungen

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

Um die Adresse des Puffers abzurufen, kann der Treiber einen Wert ohneNULL- für den WdfMemoryCreate Parameter der Funktion Buffer angeben, oder der Treiber kann WdfMemoryGetBufferaufrufen.

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

Basierend auf dem Verwendungsmuster des zugewiesenen Speichers des Treibers empfiehlt es sich, Folgendes zu berücksichtigen:

• RtlZeroMemory unmittelbar nach dem Aufruf 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 vorab zugewiesener 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 WdfMemoryCreateaufgerufen wird. Wenn Ihr Treiber ein Speicherobjekt erstellt, das es mit einem bestimmten Geräteobjekt, Anforderungsobjekt oder einem anderen Frameworkobjekt verwendet, sollte das übergeordnete Objekt des Speicherobjekts entsprechend festgelegt werden. Das Speicherobjekt und dessen Puffer werden gelöscht, wenn das übergeordnete Objekt gelöscht wird. Wenn Sie das übergeordnete Standardobjekt nicht ändern, bleibt das Speicherobjekt und dessen Puffer erhalten, bis der E/A-Manager den Treiber entladen hat.

Ein Treiber kann auch ein Speicherobjekt und dessen Puffer löschen, indem WdfObjectDeleteaufgerufen wird.

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, wird jedoch von der Anzahl der Bytes ausgerichtet, die die MEMORY_ALLOCATION_ALIGNMENT Konstante in Ntdef.hangibt.

Wenn BufferSize- PAGE_SIZE oder höher ist, weist kmDF nur dem System einen seitenbündigen Puffer zu. Wenn der parameter PoolTypeNonPagedPoolist, weist das System die Anzahl der Seiten zu, die erforderlich sind, um alle Bytes zu enthalten. Nicht verwendete Bytes auf der letzten zugeordneten 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 Frameworkspeicherobjekt erstellt und ein Puffer zugewiesen, dessen Größe WRITE_BUFFER_SIZE ist. Das übergeordnete Objekt des Speicherobjekts 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

Siehe auch

POOL_TYPE

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT

WdfMemoryCreateFromLookaside

WdfMemoryCreatePreallocated

WdfMemoryGetBuffer-

WdfObjectDelete-