Framework 物件上下文空間

物件內容空間 是驅動程式可以配置並指派給對象的額外、不可分頁記憶體空間。 每個架構型驅動程式都可以為驅動程式接收或建立的每個架構物件建立一或多個物件特定內容空間。

架構型驅動程式應該依據值或指標，將所有物件特定數據儲存在數據所屬的對象內容空間內。

例如，USB 裝置的驅動程式可能會為其架構裝置物件建立內容空間。 在內容空間中，驅動程式可能會儲存這類裝置特定資訊，例如裝置的 USB_DEVICE_DESCRIPTOR 和 USB_CONFIGURATION_DESCRIPTOR 結構，再加上代表裝置介面管道之 集合物件的句柄。

架構不會將架構物件從某個驅動程式傳遞至另一個驅動程式，因此您無法使用物件的內容空間在兩個驅動程式之間傳遞數據。

若要定義物件的內容空間，您必須建立一或多個結構。 每個結構都代表個別的內容空間。 您的驅動程式會使用每個結構成員來儲存一段物件特定資訊。 此外，您的驅動程式必須要求架構為每個結構體產生 存取子方法。 這個存取子方法接受物件句柄做為輸入，並傳回對象內容空間的位址。

每當驅動程式呼叫物件建立方法時，例如 WdfDeviceCreate，方法會選擇性地配置內容空間。 所有物件建立方法都會接受選擇性 WDF_OBJECT_ATTRIBUTES 結構做為輸入。 此結構描述您希望架構配置給對象的內容空間。

若要在驅動程式呼叫物件的建立方法之後，將額外的內容空間新增至 對象，驅動程式可以呼叫 WdfObjectAllocateContext 方法，例如物件建立方法，接受 WDF_OBJECT_ATTRIBUTES 結構做為輸入。

當架構為物件配置內容空間時，也會以零初始化內容空間。

當架構或驅動程式刪除架構物件時，架構會刪除所有物件的內容空間。

如果您的驅動程式使用內容空間來儲存驅動程式在建立物件時配置之緩衝區的指標，驅動程式應該提供 EvtCleanupCallback 函式，以在刪除物件時解除分配緩衝區。

若要為驅動程式所建立的物件定義物件的內容空間結構和存取子方法，驅動程式必須使用下列步驟：

1. 定義結構，描述您想要儲存的數據。 例如，如果您想要為驅動程式的裝置物件建立內容數據，您的驅動程式可能會定義名為 MY_DEVICE_CONTEXT的結構。

2. 使用 的 WDF_DECLARE_CONTEXT_TYPE 巨集或使用 的 WDF_DECLARE_CONTEXT_TYPE_WITH_NAME 巨集。 這兩個巨集都會執行下列動作：

   • 建立和初始化 WDF_OBJECT_CONTEXT_TYPE_INFO 結構。
   • 定義驅動程式稍後將用來存取物件內容空間的存取子方法。 存取子方法的傳回值是對象內容空間的指標。

   WDF_DECLARE_CONTEXT_TYPE巨集會從結構的名稱建立存取子方法的名稱。 例如，如果您的內容結構名稱是MY_DEVICE_CONTEXT，巨集會建立名為 WdfObjectGet_MY_DEVICE_CONTEXT的存取子方法。

   WDF_DECLARE_CONTEXT_TYPE_WITH_NAME 宏可讓您指定取值方法的名稱。 例如，您可以將 GetMyDeviceContext 指定為裝置物件之內容存取子方法的名稱。

3. 呼叫 WDF_OBJECT_ATTRIBUTES_INIT，以初始化物件的 WDF_OBJECT_ATTRIBUTES 結構。

4. 使用 WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE 巨集，將WDF_OBJECT_ATTRIBUTES結構的 ContextTypeInfo 成員設定為WDF_OBJECT_CONTEXT_TYPE_INFO 結構的位址。

5. 呼叫物件建立方法，例如 WdfDeviceCreate。

在驅動程式建立對象之後，驅動程式可以隨時呼叫 WdfObjectAllocateContext，以將額外的內容空間新增至物件。

因為步驟 1 和 2 會定義全域數據結構並建立可呼叫驅動程式的例程，因此您的驅動程式必須在宣告全域數據的驅動程式區域中完成這些步驟，通常是頭檔。 這些步驟不得從驅動程式的例程內完成。

您的驅動程式必須在建立 對象的驅動程式例程內完成步驟 3、4 和 5，例如呼叫 WdfDeviceCreate的 EvtDriverDeviceAdd 回呼函式。

架構可以代表您的驅動程式建立兩種類型的物件 -- 架構要求物件和架構檔案物件 。 您的驅動程式可以分別呼叫 WdfDeviceInitSetRequestAttributes 和 WdfDeviceInitSetFileObjectConfig來註冊這些對象的內容空間。 您的驅動程式也可以呼叫 WdfObjectAllocateContext 來配置這些物件的內容空間。

建立物件之後，驅動程式可以使用下列其中一種技術，取得對象內容空間的指標：

• 使用 WDF_DECLARE_CONTEXT_TYPE 或 WDF_DECLARE_CONTEXT_TYPE_WITH_NAME 巨集，呼叫您在前述步驟 2 中建立的內容存取子方法。

• 呼叫 WdfObjectGetTypedContext，並提供驅動程式定義的內容結構名稱。

如果您的驅動程式具有內容空間指標，則可以呼叫 WdfObjectContextGetObject來尋找內容空間所屬的物件。