IoGetDeviceInterfaces 函式 (wdm.h)

發行項
02/27/2024

IoGetDeviceInterfaces 例程會傳回特定裝置介面類別的裝置介面實例清單， (例如系統上支援 HID 介面) 的所有裝置。

語法

NTSTATUS IoGetDeviceInterfaces(
  [in]           const GUID     *InterfaceClassGuid,
  [in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
  [in]           ULONG          Flags,
  [out]          PZZWSTR        *SymbolicLinkList
);

參數

[in] InterfaceClassGuid

指定裝置介面類別之類別 GUID 的指標。類別的 GUID 應該位於裝置特定的頭檔中。

[in, optional] PhysicalDeviceObject

選擇性 PDO 的指標，將搜尋範圍縮小為 PDO 所代表之裝置的裝置介面實例。

[in] Flags

指定修改裝置介面搜尋的旗標。目前只有一個旗標已定義，如下表所述。

旗標	意義
DEVICE_INTERFACE_INCLUDE_NONACTIVE	除了啟用的介面實例之外，還傳回停用的裝置介面實例。

搜尋支援特定介面類別的裝置時，呼叫端需要啟用的介面實例，因此不會設定DEVICE_INTERFACE_INCLUDE_NONACTIVE旗標。

驅動程式通常會設定DEVICE_INTERFACE_INCLUDE_NONACTIVE旗標，以找出驅動程式必須啟用的已停用介面實例。例如，裝置的類別安裝程式可能已由 INF 檔案導向，以註冊裝置的一或多個介面實例。介面實例會註冊，但在 (驅動程式使用 IoSetDeviceInterfaceState) 啟用這些實例之前，才能使用它們。若要縮小只傳回給指定裝置所公開的介面實例清單，驅動程式可以指定 PhysicalDeviceObject。

[out] SymbolicLinkList

如果成功，例程所指向之寬字元指標的指標，會寫入包含 Unicode 字串清單之緩衝區的基位址。這些字串是符號連結名稱，可識別符合搜尋準則的裝置介面實例。清單中的每個 Unicode 字串都是以 Null 結尾;整個清單的結尾會以額外的 Null 字元標示。例程會從分頁系統記憶體配置這些字串的緩衝區。呼叫端負責在不再需要時呼叫 ExFreePool 例程) 來釋放緩衝區 (。

如果沒有裝置介面實例符合搜尋準則，此例程會傳回STATUS_SUCCESS，而且字串包含單一 NULL 字元。

傳回值

如果呼叫成功，IoGetDeviceInterfaces 會傳回STATUS_SUCCESS。可能的錯誤傳回值包括下列專案。

傳回碼	Description
STATUS_INVALID_DEVICE_REQUEST	可能表示 PhysicalDeviceObject 不是有效的 PDO 指標。

備註

IoGetDeviceInterfaces 會傳回符合搜尋準則的裝置介面實例清單。核心模式元件通常會呼叫此例程，以取得特定裝置介面類別所有已啟用裝置介面實例的清單。這類元件可以藉由呼叫 IoGetDeviceObjectPointer 或 ZwCreateFile 例程，取得介面的檔案物件和/或裝置物件的指標。 IoGetDeviceObjectPointer 傳回的裝置對象指標會指向裝置的裝置堆疊頂端，而且可用於呼叫 IoCallDriver 例程。

如果要求的裝置介面類別有預設介面，則會先列在 SymbolicLinkList 中。默認介面可由使用者模式設定，但不能由核心模式設定。

符號連結名稱的格式不透明;呼叫端不應該嘗試剖析符號連結名稱。

裝置介面實例的符號連結可以跨系統開機使用。

若要在系統上啟用特定類別的其他裝置介面實例時收到通知，請呼叫 IoRegisterPlugPlayNotification 例程來註冊裝置類別變更通知。

IoGetDeviceInterfaces 的呼叫端必須在 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) 、 MarkPower (wdm ) 、 MarkPowerDown (wdm ) 、 MarkQueryRelations (wdm ) 、 MarkStartDevice (wdm ) 、 PowerIrpDDis (wdm)