Freigeben über


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
STATUS_INVALID_PARAMETER
Ein ungültiger Parameter wurde erkannt.
STATUS_OBJECT_NAME_INVALID
Das ContextTypeInfo-Element der WDF_OBJECT_ATTRIBUTES Struktur, die der angegebene ContextAttributes-Parameter angegeben hat, war ungültig.
STATUS_INSUFFICIENT_RESOURCES
Der Kontextbereich konnte nicht zugeordnet werden.
STATUS_OBJECT_NAME_EXISTS
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.
STATUS_DELETE_PENDING
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)

Weitere Informationen

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WdfDeviceCreate