WDF_OBJECT_ATTRIBUTES-Struktur (wdfobject.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WDF_OBJECT_ATTRIBUTES-Struktur beschreibt Attribute, die einem beliebigen Frameworkobjekt zugeordnet werden können.

Syntax

typedef struct _WDF_OBJECT_ATTRIBUTES {
  ULONG                          Size;
  PFN_WDF_OBJECT_CONTEXT_CLEANUP EvtCleanupCallback;
  PFN_WDF_OBJECT_CONTEXT_DESTROY EvtDestroyCallback;
  WDF_EXECUTION_LEVEL            ExecutionLevel;
  WDF_SYNCHRONIZATION_SCOPE      SynchronizationScope;
  WDFOBJECT                      ParentObject;
  size_t                         ContextSizeOverride;
  PCWDF_OBJECT_CONTEXT_TYPE_INFO ContextTypeInfo;
} WDF_OBJECT_ATTRIBUTES, *PWDF_OBJECT_ATTRIBUTES;

Member

Size

Die Größe (in Bytes) dieser Struktur.

EvtCleanupCallback

Ein Zeiger auf die EvtCleanupCallback-Rückruffunktion des Treibers ( NULL).

EvtDestroyCallback

Ein Zeiger auf die EvtDestroyCallback-Rückruffunktion des Treibers ( NULL).

ExecutionLevel

Ein WDF_EXECUTION_LEVEL typisierter Wert, der die maximale IRQL angibt, bei der das Framework die Ereignisrückruffunktionen des Objekts aufruft. Eine Liste der Frameworkobjekte, für die der Treiber einen ExecutionLevel-Wert angeben kann, finden Sie unter WDF_EXECUTION_LEVEL.

SynchronizationScope

Ein WDF_SYNCHRONIZATION_SCOPE typisierter Wert, der angibt, wie das Framework die Ausführung der Ereignisrückruffunktionen des Objekts synchronisiert. Eine Liste der Frameworkobjekte, für die der Treiber einen SynchronizationScope-Wert angeben kann, finden Sie unter WDF_SYNCHRONIZATION_SCOPE.

ParentObject

Ein Handle für das übergeordnete Objekt des Objekts oder NULL , wenn das Objekt nicht über ein vom Treiber angegebenes übergeordnetes Objekt verfügt.

Eine Tabelle mit den Objekten, die ein vom Treiber angegebenes übergeordnetes Element zulassen, finden Sie unter Zusammenfassung von Frameworkobjekten . Die Tabelle zeigt auch das übergeordnete Standardelement der einzelnen Objekte an.

ContextSizeOverride

Wenn nicht 0, überschreibt dieser Wert das ContextSize-Element der WDF_OBJECT_CONTEXT_TYPE_INFO-Struktur , auf die das ContextTypeInfo-Element verweist. Dieser Wert ist optional und kann null sein. Wenn der Wert nicht 0 ist, muss er eine Größe in Bytes angeben, die größer als der Wert ist, der für das ContextSize-Element der WDF_OBJECT_CONTEXT_TYPE_INFO-Struktur angegeben ist. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

ContextTypeInfo

Ein Zeiger auf eine WDF_OBJECT_CONTEXT_TYPE_INFO-Struktur . Der WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE Makros legt diesen Zeiger fest.

Hinweise

Die WDF_OBJECT_ATTRIBUTES-Struktur wird als Eingabeargument für mehrere Methoden verwendet, die Frameworkobjekte erstellen.

Um eine WDF_OBJECT_ATTRIBUTES Struktur zu initialisieren, muss der Treiber WDF_OBJECT_ATTRIBUTES_INIT aufrufen.

Wenn Sie objektspezifische Kontextinformationen für ein Objekt definieren, müssen Sie außerdem das makro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE verwenden.

Alternativ können Sie das makro WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE anstelle der makros WDF_OBJECT_ATTRIBUTES_INIT und WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE verwenden.

Weitere Informationen zur Verwendung dieser Makros finden Sie unter Framework-Objektkontextraum.

Verwenden Sie das ContextSizeOverride-Element von WDF_OBJECT_ATTRIBUTES, wenn Sie Objektkontextraum mit variabler Länge erstellen möchten. Sie können beispielsweise eine Kontextraumstruktur definieren, die ein Array enthält, wie folgt:

typedef struct _MY_REQUEST_CONTEXT {
  ULONG  ByteCount;
  BYTE  Bytes[1];
} MY_REQUEST_CONTEXT, *PMY_REQUEST_CONTEXT;

WDF_DECLARE_CONTEXT_TYPE(MY_REQUEST_CONTEXT);

Wenn Ihr Treiber ein Objekt erstellt, das die Kontextraumstruktur verwendet, kann er den ContextSizeOverride-Member verwenden, um die Kontextgröße anzugeben, die für jedes einzelne Objekt erforderlich ist. Ihr Treiber kann beispielsweise die Anzahl der Bytes berechnen, die im Array aus dem vorherigen Beispiel benötigt werden, und dann ContextSizeOverride verwenden, um die zusätzlichen Bytes wie folgt anzugeben:

WDF_OBJECT_ATTRIBUTES MyRequestObjectAttributes;
PMY_REQUEST_CONTEXT pMyContext;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &MyRequestObjectAttributes,
                                        MY_REQUEST_CONTEXT
                                        );
MyRequestObjectAttributes.ContextSizeOverride =
                          sizeof(MY_REQUEST_CONTEXT) + Num_Extra_Bytes - 1;

Der Treiber kann dann ein Objekt mit einer angepassten Kontextgröße erstellen.

status = WdfRequestCreate(
                          &MyRequestObjectAttributes,
                          ioTarget,
                          &newRequest
                          );

Weitere Informationen zu den Bereinigungsregeln für eine Frameworkobjekthierarchie finden Sie unter Framework-Objektlebenszyklus.