使用控制裝置物件

控制裝置物件 是不支援隨插即用或電源管理作業的架構裝置物件。 驅動程式可以使用控制裝置物件來代表僅限軟體的虛擬設備或 舊版硬體裝置（也就是未提供 PnP 或電源管理功能的裝置）。

建立控制裝置物件的驅動程式通常也會建立裝置物件的符號連結。 應用程式可以將符號連結名稱傳遞至 API 元素，例如 Microsoft Win32 CreateFile 函式，將 I/O 要求傳送至控制裝置物件。

架構不會將控制裝置物件附加至 裝置堆疊。 因此，當應用程式將 I/O 要求傳送至控制裝置物件時，I/O 管理員會將要求直接傳遞給建立控制裝置物件的驅動程式，而不是傳送至堆疊頂端的驅動程式。 不過，額外的驅動程式可以呼叫 IoAttachDevice，將裝置物件附加在控制裝置物件上方。在此情況下，其他驅動程式會先接收 I/O 要求。

控制裝置物件的使用

控制裝置的兩個一般用途如下：

1. 如果驅動程式支援一組自定義 I/O 控制碼供應用程式使用，則為 PnP 裝置的篩選驅動程式。

   如果應用程式嘗試將自定義 I/O 控件代碼傳送至驅動程式堆疊頂端（例如，使用 裝置介面的符號連結名稱），則如果驅動程式無法辨識自定義 I/O 控制碼，則篩選驅動程式上方的驅動程式可能會失敗 I/O 要求。 若要避免這個問題，篩選驅動程式可以建立控制裝置物件。 應用程式可以使用控制項裝置物件的符號連結名稱，將 I/O 控制件代碼直接傳送至篩選驅動程式。

   （請注意，篩選驅動程式避免問題的最佳方式是作為總線驅動程式，並 列舉以原始模式運作的 子裝置。 換句話說，針對篩選驅動程序支援的每個裝置，驅動程式可以建立不需要函式驅動程式的實體裝置物件 （PDO）。 驅動程式會針對每個裝置呼叫 WdfPdoInitAssignRawDevice 和 WdfDeviceInitAssignName，而且應用程式可以在傳送自定義 I/O 控件程式代碼時依名稱識別裝置。

2. 不支援 PnP 之裝置的驅動程式。

   這類驅動程式必須使用控制裝置對象，因為這類裝置的裝置物件不在裝置堆疊中，而且不提供 PnP 功能。 如需支援非PnP裝置的詳細資訊，請參閱 使用非PnP驅動程式的Kernel-Mode 驅動框架。

建立控制裝置物件

若要建立控制裝置物件，驅動程式必須：

1. 呼叫 WdfControlDeviceInitAllocate 以取得 WDFDEVICE_INIT 結構。

2. 視需要呼叫物件初始化方法，以初始化WDFDEVICE_INIT結構。 驅動程式只能呼叫下列初始化方法：

   • WdfControlDeviceInitSetShutdownNotification
   • WdfDeviceInitAssignName
   • WdfDeviceInitAssignSDDLString
   • WdfDeviceInitAssignWdmIrpPreprocessCallback
   • WdfDeviceInitSetCharacteristics
   • WdfDeviceInitSetDeviceClass
   • WdfDeviceInitSetExclusive
   • WdfDeviceInitSetFileObjectConfig
   • WdfDeviceInitSetIoInCallerContextCallback
   • WdfDeviceInitSetIoType
   • WdfDeviceInitSetRequestAttributes

3. 呼叫 WdfDeviceCreate，它會使用 WDFDEVICE_INIT 結構的內容來建立架構裝置物件。

4. 完成下列初始化作業：

   • 視需要建立裝置的預設 I/O 佇列。
   • 需要時呼叫 WdfDeviceConfigureRequestDispatching。
   • 呼叫 WdfDeviceCreateSymbolicLink，以建立應用程式可用來存取控制裝置的符號連結名稱。

5. 呼叫 WdfControlFinishInitializing。

使用控制裝置對象的規則

建立控制裝置物件的驅動程式必須遵守下列規則：

• 驅動程式無法將控制裝置物件的句柄傳遞至架構方法，列舉子裝置。

• 驅動程式無法將控制裝置物件的控制代碼傳遞至支援 裝置介面的框架方法，。

• 驅動程式可以建立 I/O 佇列，並註冊佇列的要求處理程式，但架構不允許將佇列 電源管理。

• 驅動程式可以針對控制裝置物件 建立 檔案物件。

命名控制裝置物件

所有控制裝置對象都必須命名。 一般而言，您的驅動程式會呼叫 WdfDeviceInitAssignName 來指派裝置名稱，然後呼叫 WdfDeviceCreateSymbolicLink，以建立應用程式可用來存取物件的符號連結名稱。

如果您的驅動程式未呼叫 WdfDeviceInitAssignName 來指派裝置名稱，架構會自動產生控件裝置的名稱，但您的驅動程式無法呼叫 WdfDeviceCreateSymbolicLink。

您的驅動程式可以呼叫 WdfDeviceInitSetDeviceClass 來指定控件裝置的 裝置設定類別。 裝置設定類別會識別登錄檔中的區段，其中包含屬於設定類別的裝置相關且由系統管理員提供的資訊。 如需呼叫 WdfDeviceInitSetDeviceClass的詳細資訊，請參閱 Framework-Based Drivers中控制裝置存取。

接收系統關機通知

因為控制裝置物件不支援 PnP，所以您的驅動程式無法註冊回呼函式，以在裝置電源狀態變更時通知驅動程式。 不過，驅動程式可以呼叫 WdfControlDeviceInitSetShutdownNotification 來註冊 EvtDeviceShutdownNotification 回呼函式。 當系統即將失去電源時，此回呼函式會通知驅動程式。

刪除控制件裝置物件

某些驅動程式必須先在驅動程式卸載之前刪除其控制裝置物件，如下所示：

• 如果您的驅動程式建立控制裝置物件（不支援 PnP 或電源管理），而且如果驅動程式也建立支援 PnP 和電源管理的架構裝置對象，驅動程式最終必須在 IRQL = PASSIVE_LEVEL呼叫 WdfObjectDelete，以刪除控制裝置物件。

  如果驅動程式建立這兩種類型的裝置物件，在驅動程式刪除控制裝置物件之前，作系統無法卸除您的驅動程式。

  不過，在架構刪除其他裝置物件之前，驅動程式不得刪除控制裝置物件。 若要判斷架構何時刪除其他裝置物件，您的驅動程式應該為這些物件提供 EvtCleanupCallback 函式。

• 如果您的驅動程式建立控制裝置物件，但不建立支援 PnP 和電源管理的架構裝置對象，驅動程式就不需要刪除控制裝置物件。

  在此情況下，架構會在驅動程式的 EvtDriverUnload 回呼函式傳回之後，刪除控制裝置物件。