WdfMemoryCreatePreallocated-Funktion (wdfmemory.h)
[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
);
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] Buffer
Ein Zeiger auf einen vom Treiber bereitgestellten Puffer.
[in] BufferSize
Die Nichtzero-Größe des Puffers, auf den Puffer verweist, in Byte.
[out] Memory
Ein Zeiger auf eine Position, die ein Handle für 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 |
|---|---|
|
Ein ungültiger Parameter wurde erkannt. |
|
Nicht genügend Arbeitsspeicher vorhanden. |
Eine Liste mit anderen Rückgabewerten, die von der WdfMemoryCreatePreallocated-Methode möglicherweise zurückgegeben werden, finden Sie unter Framework Object Creation Errors.
Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.
Bemerkungen
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 treiberdefinierte Struktur innerhalb eines Puffers für eine E/A-Anforderung erhalten, 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 WdfMemoryCreatePreallocatedaufgerufen hat, kann der Treiber WdfMemoryAssignBuffer- aufrufen, um dem Speicherobjekt einen anderen Puffer zuzuweisen, der WdfMemoryCreatePreallocated erstellt wurde.
Das übergeordnete Standardobjekt für jedes Speicherobjekt ist das Framework-Treiberobjekt, das den Treiber darstellt, der WdfMemoryCreatePreallocatedaufgerufen 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 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 entlädt.
Ein Treiber kann auch ein Speicherobjekt löschen, indem WdfObjectDeleteaufgerufen wird.
Wenn das Framework-Speicherobjekt, das WdfMemoryCreatePreallocated erstellt wurde, gelöscht wird, führt das Framework keine Zuordnung des bereits vorhandenen Puffers durch. Ebenso führt ein Aufruf von WdfMemoryAssignBuffer keine Zuordnung des zuvor zugewiesenen Puffers durch.
Weitere Informationen zu Framework-Speicherobjekten finden Sie unter Verwenden von Speicherpuffern.
Beispiele
Im folgenden Codebeispiel wird ein Puffer zugewiesen und anschließend 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 |
| Minimale KMDF-Version | 1.0 |
| Mindest-UMDF-Version | 2.0 |
| Kopfzeile | wdfmemory.h (include Wdf.h) |
| Bibliothek | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| DDI-Complianceregeln | BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqComp, DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |