ioRegisterDeviceInterface 函式 (wdm.h)

  • 發行項

IoRegisterDeviceInterface 例程會註冊裝置介面類別，如果先前尚未註冊，並建立介面類別的新實例，驅動程式後續可以啟用供應用程式或其他系統元件使用。

語法

NTSTATUS IoRegisterDeviceInterface(
  [in]           PDEVICE_OBJECT  PhysicalDeviceObject,
  [in]           const GUID      *InterfaceClassGuid,
  [in, optional] PUNICODE_STRING ReferenceString,
  [out]          PUNICODE_STRING SymbolicLinkName
);

參數

[in] PhysicalDeviceObject

裝置 PDO 的指標。

[in] InterfaceClassGuid

類別 GUID 的指標，識別 (裝置介面類別) 註冊的功能。

[in, optional] ReferenceString

選擇性地指向 UNICODE_STRING。 字串不得包含任何路徑分隔符， (“/” 或 “\”) 。 函式驅動程式通常會為此參數指定 NULL 。 篩選驅動程序必須指定 NULL。

參考字串只能由幾個總線驅動程式使用，例如 swenum，這是使用裝置介面實例作為依需求建立之軟體裝置佔位符的總線驅動程式。 開啟介面的實例時，I/O 管理員會將實例的參考字串傳遞至驅動程式。 字串會成為介面實例名稱的一部分， (做為附加路徑元件) 。 然後，驅動程式可以使用參考字串來區分單一裝置相同類別的兩個介面實例。

在 Microsoft Windows 98/Me 系統上， ReferenceString 值不能超過MAX_PATH個字元。 Windows 2000 和更新版本的 Windows 沒有長度限制。

[out] SymbolicLinkName

呼叫端所配置之 Unicode 字串結構的指標。 如果這個例程成功，它會初始化 Unicode 字串，並配置包含指定裝置介面類別實例之符號連結核心模式路徑的字串緩衝區。

呼叫端必須將 SymbolicLinkName 視為不透明，且不得將其反組譯。

呼叫端負責在不再需要時，使用 RtlFreeUnicodeString 釋放 SymbolicLinkName。

傳回值

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

傳回碼 Description
STATUS_INVALID_DEVICE_REQUEST
 參數無效。 可能性包括 PhysicalDeviceObject 未指向有效的 PDO，或 ReferenceString 字串包含無效字元。

備註

如果先前尚未註冊裝置介面類別，IoRegisterDeviceInterface 會註冊裝置介面類別，並建立介面類別的新實例。 驅動程式可以針對指定的裝置呼叫此例程數次，以註冊數個介面類別，並建立類別的實例。 函式或篩選驅動程式通常會在其 AddDevice 例程中註冊裝置介面。 例如，容錯磁碟區驅動程式可能會註冊容錯磁碟區介面的實例，以及特定磁碟區的磁碟區介面實例。

如果先前尚未註冊裝置介面類別，I/O 管理員會為其建立登錄機碼，以及機碼下實例特定的永續性記憶體。 驅動程式可以使用 IoOpenDeviceInterfaceRegistryKey來存取此永續性記憶體。

驅動程式會註冊介面實例一次，然後呼叫 IoSetDeviceInterfaceState 來啟用和停用介面。

已註冊的介面會在操作系統重新啟動時持續存在。 如果指定的介面已註冊，I/O 管理員會在 SymbolicLinkName 中傳遞其名稱，並傳回參考成功狀態STATUS_OBJECT_NAME_EXISTS。

大部分的驅動程式會針對裝置介面實例使用 NULL 參考字串。 如果驅動程式使用非 NULL 參考字串，它必須執行額外的工作，包括可能管理自己的命名空間和安全性。 公開裝置介面的篩選驅動程序必須使用 NULLReferenceString ，以避免與裝置堆疊中的其他驅動程式發生衝突。

當不再需要裝置介面時，不需要呼叫此例程的呼叫端即可移除裝置介面的註冊。 如有需要，可以從使用者模式中移除裝置介面註冊。

IoRegisterDeviceInterface 的呼叫端必須在 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) 、 IrqlIoPassive3 (wdm) 、 PowerIrpDDis (wdm)

另請參閱

IoGetDeviceInterfaces

IoOpenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

RtlFreeUnicodeString