SetupDiCreateDeviceInterfaceA 函式 (setupapi.h)

  • 發行項

SetupDiCreateDeviceInterface 函式會在本機系統或遠端系統上註冊裝置介面。

語法

WINSETUPAPI BOOL SetupDiCreateDeviceInterfaceA(
  [in]            HDEVINFO                  DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA          DeviceInfoData,
  [in]            const GUID                *InterfaceClassGuid,
  [in, optional]  PCSTR                     ReferenceString,
  [in]            DWORD                     CreationFlags,
  [out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

參數

[in] DeviceInfoSet

裝置資訊集的句柄。 此集合包含代表要註冊介面之裝置的裝置信息專案。 此句柄通常是 由 SetupDiGetClassDevs 傳回。

[in] DeviceInfoData

SP_DEVINFO_DATA 結構的指標，指定 DeviceInfoSet 中的裝置信息專案。

[in] InterfaceClassGuid

類別 GUID 的指標，指定新介面的介面類別。

[in, optional] ReferenceString

提供參考字串之 NULL 終止字串的指標。 此指標是選擇性的，而且可以是 NULL。 參考字串只能由幾個總線驅動程式使用，這些驅動程式會使用裝置介面做為依需求建立之軟體裝置的佔位元。

[in] CreationFlags

保留的。 必須為零。

[out, optional] DeviceInterfaceData

呼叫端初始化 SP_DEVICE_INTERFACE_DATA 結構的指標，可接收新裝置介面的相關信息。 此指標是選擇性的，而且可以是 NULL。 如果提供 結構，呼叫端必須先將此結構的 cbSize 成員設定為 sizeof (SP_DEVICE_INTERFACE_DATA) ，才能呼叫此函式。 如需詳細資訊，請參閱下列一節。

傳回值

如果函式未發生錯誤，SetupDiCreateDeviceInterface 會傳回 TRUE。 如果函式已完成錯誤，它會傳回 FALSE ，而且呼叫 GetLastError 即可擷取失敗的錯誤碼。

備註

此函式的呼叫端必須是 Administrators 群組的成員。

SetupDiCreateDeviceInterface 會註冊裝置的介面。 如果裝置有多個介面，請針對每個註冊的介面呼叫此函式一次。

如果此函式成功註冊對應至指定裝置資訊元素之裝置的介面，它也會將介面新增至與指定裝置資訊集中裝置資訊元素相關聯的介面清單。

應用程式和其他系統元件必須先由裝置的驅動程式啟用介面，才能使用已註冊的介面。

此函式會建立新裝置介面的登錄機碼。 此函式的呼叫端可以使用 SetupDiOpenDeviceInterfaceRegKey 存取此密鑰下的非卷積記憶體。

如果 SetupDiCreateDeviceInterface 成功建立新的裝置介面，但 DeviceInterfaceData 參數中的呼叫端提供的緩衝區無效，則此函式會傳回 FALSE ，且 後續呼叫 GetLastError 會傳回ERROR_INVALID_USER_BUFFER。 不過，函式會建立並註冊新的裝置介面。

注意

setupapi.h 標頭會將 SetupDiCreateDeviceInterface 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

需求 值
最低支援的用戶端 可在 Microsoft Windows 2000 和更新版本的 Windows 中使用。
目標平台 桌面
標頭 setupapi.h (包括 Setupapi.h)
程式庫 Setupapi.lib

另請參閱

SetupDiOpenDeviceInterfaceRegKey

SetupDiRemoveDeviceInterface