WDF_OBJECT_ATTRIBUTES struttura (wdfobject.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

La struttura WDF_OBJECT_ATTRIBUTES descrive gli attributi che possono essere associati a qualsiasi oggetto framework.

Sintassi

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;

Members

Size

Dimensione, in byte, della struttura.

EvtCleanupCallback

Puntatore alla funzione di callback EvtCleanupCallback del driver o NULL.

EvtDestroyCallback

Puntatore alla funzione di callback EvtDestroyCallback del driver o NULL.

ExecutionLevel

Valore WDF_EXECUTION_LEVEL tipizzato che specifica il valore di IRQL massimo in cui il framework chiamerà le funzioni di callback degli eventi dell'oggetto. Per un elenco di oggetti framework per i quali il driver può specificare un valore ExecutionLevel , vedere WDF_EXECUTION_LEVEL.

SynchronizationScope

Valore WDF_SYNCHRONIZATION_SCOPE tipizzato che specifica come il framework sincronizza l'esecuzione delle funzioni di callback dell'evento dell'oggetto. Per un elenco di oggetti framework per i quali il driver può specificare un valore SyncScope , vedere WDF_SYNCHRONIZATION_SCOPE.

ParentObject

Handle per l'oggetto padre dell'oggetto o NULL se l'oggetto non ha un elemento padre specificato dal driver.

Vedere Riepilogo degli oggetti Framework per una tabella che mostra gli oggetti che consentono un elemento padre specificato dal driver. La tabella mostra anche l'elemento padre predefinito di ogni oggetto.

ContextSizeOverride

Se non zero, questo valore esegue l'override del membro ContextSize della struttura WDF_OBJECT_CONTEXT_TYPE_INFO a cui fa riferimento il membro ContextTypeInfo . Questo valore è facoltativo e può essere zero. Se il valore non è zero, deve specificare una dimensione, in byte, maggiore del valore specificato per il membro ContextSize della struttura WDF_OBJECT_CONTEXT_TYPE_INFO. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

ContextTypeInfo

Puntatore a una struttura di WDF_OBJECT_CONTEXT_TYPE_INFO . La macro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE imposta questo puntatore.

Commenti

La struttura WDF_OBJECT_ATTRIBUTES viene usata come argomento di input per diversi metodi che creano oggetti framework.

Per inizializzare una struttura WDF_OBJECT_ATTRIBUTES, il driver deve chiamare WDF_OBJECT_ATTRIBUTES_INIT.

Inoltre, se si definiscono informazioni di contesto specifiche dell'oggetto per un oggetto, è necessario usare la macro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE .

In alternativa, è possibile usare la macro WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE anziché le macro WDF_OBJECT_ATTRIBUTES_INIT e WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE.

Per altre informazioni sull'uso di queste macro, vedere Framework Object Context Space.

Usare il membro ContextSizeOverride di WDF_OBJECT_ATTRIBUTES se si vuole creare lo spazio di contesto dell'oggetto con lunghezza variabile. Ad esempio, è possibile definire una struttura dello spazio di contesto che contiene una matrice, come indicato di seguito:

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

WDF_DECLARE_CONTEXT_TYPE(MY_REQUEST_CONTEXT);

Quando il driver crea un oggetto che usa la struttura dello spazio di contesto, può usare il membro ContextSizeOverride per specificare le dimensioni del contesto necessarie per ogni singolo oggetto. Ad esempio, il driver potrebbe calcolare il numero di byte necessari nella matrice dall'esempio precedente e quindi usare ContextSizeOverride per specificare i byte aggiuntivi, come indicato di seguito:

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;

Il driver può quindi creare un oggetto con dimensioni personalizzate del contesto.

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

Per altre informazioni sulle regole di pulizia per una gerarchia di oggetti framework, vedere Ciclo di vita dell'oggetto Framework.