共用方式為

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

INF DDInstall 區段中由 InfHandle所指定的 INF 檔案名稱。 這個區段會針對新建立的金鑰執行。 這個參數是選擇性的，而且可以 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。

對於使用版面配置檔案的安裝，在呼叫 SetupDiCreateDevRegKey 之前，必須先呼叫 SetupOpenAppendInfFile Microsoft ，才能呼叫 INF Version 區段中的 LayoutFile 專案。

如果提供的裝置資訊集包含遠端系統的裝置資訊元素，而且 InfHandle 和 InfSectionName 也會指定，則建立要求將會失敗，且 後續呼叫 getLastError 會傳回ERROR_REMOTE_REQUEST_UNSUPPORTED。

注意

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

要求

要求 價值
最低支援的用戶端 Microsoft Windows 2000 和更新版本的 Windows 中提供。
目標平臺 桌面
標頭 setupapi.h （包括 Setupapi.h）
連結庫 Setupapi.lib

另請參閱

SetupDiCreateDeviceInfo

SetupDiGetHwProfileList

SetupDiOpenDevRegKey

SetupDiRegisterDeviceInfo