IoSetDeviceInterfaceState 函式 (wdm.h)

發行項
02/29/2024

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
STATUS_OBJECT_NAME_NOT_FOUND	呼叫端嘗試停用未啟用的裝置介面。

備註

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)