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來尋找內容空間所屬的物件。