SetupDiCreateDevRegKeyA 函式 (setupapi.h)

發行項
03/01/2024

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