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。 可能的錯誤傳回值包括下列專案。

言論

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

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

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

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

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

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

IoRegisterDeviceInterface 的呼叫端必須在系統線程內容中的 IRQL = PASSIVE_LEVEL執行。

要求

另請參閱

IoGetDeviceInterfaces

IoOpenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

RtlFreeUnicodeString