IoSetDeviceInterfaceState 函式 (wdm.h)
IoSetDeviceInterfaceState 例程會啟用或停用先前註冊裝置介面類別的實例。
語法
NTSTATUS IoSetDeviceInterfaceState(
[in] PUNICODE_STRING SymbolicLinkName,
[in] BOOLEAN Enable
);
參數
[in] SymbolicLinkName
字串的指標，識別正在啟用或停用的裝置介面實例。 此字串是從先前呼叫 IoRegisterDeviceInterface 或 IoGetDeviceInterfaces 取得。
[in] Enable
TRUE 表示正在啟用裝置介面。 FALSE 表示正在停用裝置介面。
傳回值
如果呼叫成功，IoSetDeviceInterfaceState 會傳回STATUS_SUCCESS。 如果呼叫端要求啟用已啟用裝置介面，此例程會傳回STATUS_OBJECT_NAME_EXISTS的信息狀態。 可能的錯誤傳回值如下所述。
| 傳回碼 | Description |
|---|---|
|
呼叫端嘗試停用未啟用的裝置介面。 |
備註
IoSetDeviceInterfaceState 可讓應用程式和其他系統元件使用已註冊裝置介面的實例。 介面類別之前必須已向 IoRegisterDeviceInterface 或使用者模式註冊。
應用程式和其他系統元件只能開啟已啟用的介面。
函式或篩選驅動程式通常會在成功啟動裝置以回應 IRP_MN_START_DEVICE IRP 之後，將 [啟用] 設定為 TRUE 來呼叫此例程。 這類驅動程式應該停用裝置介面實例 (，也就是呼叫 IoSetDeviceInterfaceState，並在移除裝置以回應IRP_MN_REMOVE_DEVICE IRP 或IRP_MN_SURPRISE_REMOVAL IRP 時將 [啟用] 設定為 FALSE) 。 如果驅動程式在處理這些移除 IRP 時未停用裝置介面，則驅動程式不應該後續嘗試這樣做，因為 PnP 管理員會在 PnP 管理員移除裝置時停用介面。
例如，如果裝置突然移除 (，因為意外移除) 但仍有有效的裝置介面實例，如果裝置重新附加，就會發生問題。 當 PnP 管理員列舉新連接的裝置並啟用裝置介面實例時，就會發生此問題，該實例會存在於與現有裝置介面實例相同的登錄路徑上。
請注意，如果驅動程式呼叫 IoSetDeviceInterfaceState 來停用裝置介面實例以回應 IRP_MN_SURPRISE_REMOVAL IRP，驅動程式不得嘗試停用相同的裝置介面實例，以回應 IRP_MN_REMOVE_DEVICE IRP。
如果呼叫 IoSetDeviceInterfaceState 成功公開裝置介面實例，系統會通知任何註冊裝置類別 PnP 通知的元件變更。 同樣地，如果呼叫此例程會停用現有的裝置介面實例，則系統會傳送適當的通知。
在 IRP_MN_START_DEVICE IRP 完成之前，PnP 管理員不會傳送介面實例抵達的通知，表示裝置的所有驅動程式都已完成其啟動作業。 此外，PnP 管理員會失敗建立裝置的要求，直到 IRP_MN_START_DEVICE IRP 完成為止。
IoSetDeviceInterfaceState 的呼叫端必須在 IRQL = PASSIVE_LEVEL系統線程的內容中執行。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | 從 Windows 2000 開始提供。 |
| 目標平台 | Universal |
| 標頭 | wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h) |
| 程式庫 | NtosKrnl.lib |
| Dll | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (请参阅一节) |
| DDI 合規性規則 | HwStorPortProhibitedDDIs (storport) 、 IrqlIoPassive1 (wdm ) 、 LowerDriverReturn (wdm) 、 PowerIrpDDis (wdm) |