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
);
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 |
|---|---|
|
Ein ungültiger Parameter wurde erkannt. |
|
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) |