WdfObjectAllocateContext-Funktion (wdfobject.h)
[Gilt für KMDF und UMDF]
Die WdfObjectAllocateContext-Methode weist einen Kontextraum für ein angegebenes Frameworkobjekt zu.
Syntax
NTSTATUS WdfObjectAllocateContext(
[in] WDFOBJECT Handle,
[in] PWDF_OBJECT_ATTRIBUTES ContextAttributes,
[out] PVOID *Context
);
Parameter
[in] Handle
Ein Handle für ein Frameworkobjekt.
[in] ContextAttributes
Ein Zeiger auf eine vom Aufrufer bereitgestellte WDF_OBJECT_ATTRIBUTES Struktur, die den Kontextraum beschreibt.
[out] Context
Ein Zeiger auf eine Position, die einen Zeiger auf den zugeordneten Kontextraum empfängt.
Rückgabewert
WdfObjectAllocateContext 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. |
|
Das ContextTypeInfo-Element der WDF_OBJECT_ATTRIBUTES Struktur, die der angegebene ContextAttributes-Parameter angegeben hat, war ungültig. |
|
Der Kontextbereich konnte nicht zugeordnet werden. |
|
Der Treiber hat bereits einen Kontextraum zugewiesen, der dem ContextTypeInfo-Member der WDF_OBJECT_ATTRIBUTES Struktur entspricht, die ContextAttributes angibt. In dieser Situation empfängt der Zeiger im Parameter Context einen Zeiger auf den vorhandenen Kontextraum und weist keinen doppelten Kontextraum zu. |
|
Das Objekt, das der Handle-Parameter angibt, wird gelöscht. In dieser Situation weist das Framework keinen Kontextraum zu. |
Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.
Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.
Hinweise
In der Regel erstellen Treiber Objektkontextraum, indem sie eine WDF_OBJECT_ATTRIBUTES-Struktur angeben, wenn sie die Erstellungsmethode eines Frameworkobjekts aufrufen, z. B. WdfDeviceCreate.
Wenn Ihr Treiber mehreren Typ von Kontextraum zu einigen seiner Objekte zuordnen soll, kann der Treiber WdfObjectAllocateContext mehrmals aufrufen, nachdem er die Erstellungsmethode eines Objekts aufgerufen hat. Jeder Aufruf von WdfObjectAllocateContext muss einen anderen Kontexttyp angeben. (Das ContextTypeInfo-Element der WDF_OBJECT_ATTRIBUTES-Struktur identifiziert den Kontexttyp.)
Wenn Ihr Treiber WdfObjectAllocateContext für ein bestimmtes Objekt mehrmals aufruft, können Sie für jeden Kontext separate Rückruffunktionen evtCleanupCallback und EvtDestroyCallback bereitstellen.
Geben Sie beim Aufrufen von WdfObjectAllocateContext kein ParentObject in der WDF_OBJECT_ATTRIBUTES-Struktur an.
Wenn das Framework einen Kontextraum für ein Objekt zuweist, wird auch der Kontextraum null initialisiert.
Weitere Informationen zum Objektkontextbereich finden Sie unter Framework-Objektkontextraum.
Weitere Informationen zu den Bereinigungsregeln für eine Frameworkobjekthierarchie finden Sie unter Framework-Objektlebenszyklus.
Beispiele
Im folgenden Codebeispiel wird Kontextraum für ein Anforderungsobjekt erstellt. Der Kontextbereich basiert auf der REQUEST_CONTEXT Struktur des Beispiels.
typedef struct _REQUEST_CONTEXT {
WDFMEMORY InputMemoryBuffer;
WDFMEMORY OutputMemoryBuffer;
} REQUEST_CONTEXT, *PREQUEST_CONTEXT;
PREQUEST_CONTEXT reqContext = NULL;
WDF_OBJECT_ATTRIBUTES attributes;
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
&attributes,
REQUEST_CONTEXT
);
status = WdfObjectAllocateContext(
Request,
&attributes,
&reqContext
);
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Universell |
| KMDF-Mindestversion | 1.0 |
| UMDF-Mindestversion | 2.0 |
| Kopfzeile | wdfobject.h (einschließen von Wdf.h) |
| Bibliothek | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| DDI-Complianceregeln | DriverCreate(kmdf) |