WDF_OBJECT_ATTRIBUTES 結構 (wdfobject.h)

發行項
02/27/2024

[適用於 KMDF 和 UMDF]

WDF_OBJECT_ATTRIBUTES結構描述可與任何架構對象相關聯的屬性。

語法

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;

成員

Size

這個結構的大小，以位元組為單位。

EvtCleanupCallback

驅動程式 EvtCleanupCallback 回呼函式或 NULL 的指標。

EvtDestroyCallback

驅動程式 EvtDestroyCallback 回呼函式或 NULL 的指標。

ExecutionLevel

WDF_EXECUTION_LEVEL型別值，指定架構將呼叫物件之事件回呼函式的最大 IRQL。如需驅動程式可以指定 ExecutionLevel 值的架構物件清單，請參閱 WDF_EXECUTION_LEVEL。

SynchronizationScope

WDF_SYNCHRONIZATION_SCOPE型別值，指定架構如何同步處理物件之事件回呼函式的執行。如需驅動程式可以指定 SynchronizationScope 值的架構物件清單，請參閱 WDF_SYNCHRONIZATION_SCOPE。

ParentObject

物件的父物件句柄，如果對象沒有指定驅動程式的父物件，則為 NULL 。

如需顯示允許驅動程式指定父代之對象的數據表，請參閱 Framework 物件的摘要。數據表也會顯示每個物件的預設父代。

ContextSizeOverride

如果不是零，這個值會覆寫 ContextTypeInfo 成員所參考之WDF_OBJECT_CONTEXT_TYPE_INFO結構的 ContextSize 成員。這個值是選擇性的，而且可以是零。如果值不是零，則必須指定大小，以位元組為單位，其大於為WDF_OBJECT_CONTEXT_TYPE_INFO 結構 之ContextSize 成員所指定的值。如需詳細資訊，請參閱接下來的＜備註＞一節。

ContextTypeInfo

WDF_OBJECT_CONTEXT_TYPE_INFO 結構的指標。 WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE宏會設定此指標。

備註

WDF_OBJECT_ATTRIBUTES 結構會當做數個建立架構物件的方法的輸入自變數使用。

若要初始化WDF_OBJECT_ATTRIBUTES結構，驅動程式必須呼叫 WDF_OBJECT_ATTRIBUTES_INIT。

此外，如果您要定義物件的特定對象內容資訊，則必須使用 WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE 宏。

或者，您可以使用 WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE 宏，而不是WDF_OBJECT_ATTRIBUTES_INIT和WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE宏。

如需使用這些宏的詳細資訊，請參閱 Framework 對象內容空間。

如果您想要建立長度可變的對象內容空間，請使用 WDF_OBJECT_ATTRIBUTES 的ContextSizeOverride成員。例如，您可以定義包含數位的內容空間結構，如下所示：

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

WDF_DECLARE_CONTEXT_TYPE(MY_REQUEST_CONTEXT);

當您的驅動程式建立使用內容空間結構的物件時，可以使用 ContextSizeOverride 成員來指定每個個別物件所需的內容大小。例如，您的驅動程式可能會計算上述範例數位中所需的位元元組數目，然後使用 ContextSizeOverride 指定額外的位元組，如下所示：

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;

驅動程式接著可以建立具有自定義內容大小的物件。

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

如需架構物件階層清除規則的詳細資訊，請參閱 Framework 物件生命週期。