SetupDiCreateDevRegKeyA 函式 (setupapi.h)
SetupDiCreateDevRegKey 函式會建立裝置特定組態資訊的登錄機碼,並傳回密鑰的句柄。
語法
WINSETUPAPI HKEY SetupDiCreateDevRegKeyA(
[in] HDEVINFO DeviceInfoSet,
[in] PSP_DEVINFO_DATA DeviceInfoData,
[in] DWORD Scope,
[in] DWORD HwProfile,
[in] DWORD KeyType,
[in, optional] HINF InfHandle,
[in, optional] PCSTR InfSectionName
);
參數
[in] DeviceInfoSet
裝置資訊集的句柄,其中包含代表要建立登錄機碼之裝置的裝置信息專案。
[in] DeviceInfoData
SP_DEVINFO_DATA 結構的指標,指定 DeviceInfoSet 中的裝置信息專案。
[in] Scope
要建立的登錄機碼範圍。 範圍會決定資訊儲存的位置。 建立的金鑰可以是全域或硬體設定檔特定的金鑰。 可以是下列值之一:
DICS_FLAG_GLOBAL
建立金鑰以儲存全域組態資訊。 此資訊不是特定硬體配置檔特有的。 在 NT 型作業系統上,這會建立以 HKEY_LOCAL_MACHINE 為根目錄的密鑰。 開啟的確切索引鍵取決於 KeyType 參數的值。
DICS_FLAG_CONFIGSPECIFIC
建立金鑰以儲存硬體設定檔特定的組態資訊。 此金鑰是以其中一個硬體配置檔特定分支為根目錄,而不是 HKEY_LOCAL_MACHINE。
[in] HwProfile
如果 HwProfileFlags 設定為 SPDICS_FLAG_CONFIGSPECIFIC,則會為其建立密鑰的硬體配置檔。 如果 HwProfile 為 0,則會建立目前硬體配置檔的密鑰。 如果 HwProfileFlags 是SPDICS_FLAG_GLOBAL, 則會忽略 HwProfile 。
[in] KeyType
要建立的登錄記憶體機碼類型。 可以是下列值之一:
DIREG_DEV
建立裝置 的硬體金鑰 。
DIREG_DRV
建立裝置 的軟體金鑰 。
[in, optional] InfHandle
開啟之 INF 檔案的句柄,其中包含要針對新建立的索引鍵執行的 INF DDInstall 區段 。 這個參數是選擇性的,而且可以是 NULL。 如果指定此參數,也必須指定 InfSectionName 。
[in, optional] InfSectionName
InfHandle 所指定 INF 檔案中的 INF DDInstall 區段名稱。 這個區段會針對新建立的金鑰執行。 這個參數是選擇性的,而且可以是 NULL。 如果指定此參數,也必須指定 InfHandle 。
傳回值
如果 SetupDiCreateDevRegKey 成功,此函式會傳回指定登錄機碼的句柄,其中可儲存和擷取裝置特定的設定數據。 如果 SetupDiCreateDevRegKey 失敗,函式會傳回INVALID_HANDLE_VALUE。 呼叫 GetLastError 以取得擴充的錯誤資訊。
備註
SetupDiCreateDevRegKey 的呼叫端必須是 Administrators 群組的成員。
呼叫 RegCloseKey,以關閉從 SetupDiCreateDevRegKey 傳回的句柄。
如果指定的索引鍵已經存在, SetupDiCreateDevRegKey 會傳回該機碼的句柄。 否則, SetupDiCreateDevRegKey 會建立指定的索引鍵,並傳回新密鑰的句柄。 對於 Windows Server 2003 和更新版本的 Windows,金鑰句柄只有KEY_READ和KEY_WRITE存取權。 對於舊版 Windows,此句柄具有KEY_ALL_ACCESS存取權。
在呼叫 SetupDiCreateDevRegKey 之前,必須先註冊指定的裝置實例。 不過請注意,操作系統會自動註冊 PnP 裝置實例。 如需如何註冊非 PnP 裝置實例的資訊,請參閱 SetupDiRegisterDeviceInfo。
對於使用版面配置檔案 (INF 版本區段中LayoutFile 專案所指定的安裝) ,必須先呼叫 SetupOpenAppendInfFile (所 Microsoft Windows SDK 描述的 setupOpenAppendInfFile) (,才能呼叫 SetupDiCreateDevRegKey。
如果提供的裝置資訊集包含遠端系統的裝置資訊元素,而且也指定 了 InfHandle 和 InfSectionName ,則建立要求將會失敗,且 後續呼叫 GetLastError 會傳回ERROR_REMOTE_REQUEST_UNSUPPORTED。
注意
setupapi.h 標頭會將 SetupDiCreateDevRegKey 定義為別名,根據 UNICODE 預處理器常數的定義,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼,可能會導致編譯或運行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | 可在 Microsoft Windows 2000 和更新版本的 Windows 中使用。 |
目標平台 | 桌面 |
標頭 | setupapi.h (包括 Setupapi.h) |
程式庫 | Setupapi.lib |