SHRegQueryUSValueA 函式 (shlwapi.h)

發行項
03/05/2024

擷取與使用者特定子樹 (HKEY_CURRENT_USER 或HKEY_LOCAL_MACHINE) 中开启登录子机码相关联之指定名称的类型和数据。

語法

LSTATUS SHRegQueryUSValueA(
  [in]                HUSKEY hUSKey,
  [in, optional]      LPCSTR pszValue,
  [in, out, optional] DWORD  *pdwType,
  [out, optional]     void   *pvData,
  [in, out]           DWORD  *pcbData,
  [in]                BOOL   fIgnoreHKCU,
  [in, optional]      void   *pvDefaultData,
  [in, optional]      DWORD  dwDefaultDataSize
);

參數

[in] hUSKey

類型： HUSKEY

目前開啟登錄子機碼的句柄，或下列其中一個預先定義的值。子機碼必須已以KEY_SET_VALUE訪問許可權開啟。如需詳細資訊，請參閱登錄機碼安全性和訪問許可權。

此句柄可透過 SHRegOpenUSKey函式取得。

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in, optional] pszValue

類型： LPCTSTR

Null 終止字串的指標，其中包含要查詢之值的名稱。

[in, out, optional] pdwType

類型： LPDWORD*

設定或接收索引鍵實值型別之變數的指標。如需詳細資訊，請參閱登錄數據類型。此參數可以是 Null。

[out, optional] pvData

類型： LPVOID*

接收值數據之緩衝區的指標。如果不需要數據，這個參數可以是 NULL 。

[in, out] pcbData

類型： LPDWORD*

變數的指標，指定 pvData 參數所指向緩衝區的大小，以位元組為單位。當函式傳回時，此變數會包含複製到 pvData 的數據大小。

[in] fIgnoreHKCU

類型： BOOL

變數，指定要查看的索引鍵。當設定為 TRUE 時， SHRegQueryUSValue 會忽略 HKEY_CURRENT_USER ，並從 HKEY_LOCAL_MACHINE下的機碼傳回值。

[in, optional] pvDefaultData

類型： LPVOID*

默認數據的指標。

[in, optional] dwDefaultDataSize

類型： DWORD

默認數據的長度，以位元組為單位。

傳回值

類型： LSTATUS

如果成功，則傳回ERROR_SUCCESS，否則會傳回 Winerror.h 中定義的非零錯誤碼。您可以使用 FormatMessage 函式搭配 FORMAT_MESSAGE_FROM_SYSTEM 旗標來擷取錯誤的一般描述。

備註

當 fIgnore HKCU 設定為 TRUE 時， SHRegQueryUSValue 會從 HKEY_LOCAL_MACHINE下的機碼傳回值。當設定為 FALSE 時， SHRegQueryUSValue 會先嘗試從索引鍵傳回 HKEY_CURRENT_USER下的值。不過，如果在 HKEY_CURRENT_USER 底下找不到索引鍵，則值會從 HKEY_LOCAL_MACHINE底下的索引鍵傳回。如果索引鍵不存在，或發生錯誤且 dwDefaultDataSize 為非零值，則會將預設數據複製到 pvData 並傳回ERROR_SUCCESS。 ERROR_SUCCESS會針對預設和非預設數據傳回，而且無法區分哪些值複製到 pvData。若要防止使用預設數據，請將 pvDefaultData 設定為 NULL ，並將 dwDefaultDataSize 設定為零。

如果您只需要讀取單一值， SHRegGetUSValue 會同時開啟機碼並傳回值。若要使用 SHRegQueryUSValue，您必須先使用 SHRegOpenUSKey 開啟密鑰。不過，一旦開啟密鑰，您就可以視需要使用 SHRegQueryUSValue 。如果您需要從相同的索引鍵擷取一個以上的值，使用對 SHRegQueryUSValue 的多個呼叫通常比 SHRegGetUSValue 更有效率，因為密鑰只會開啟一次。

注意

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

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional、Windows XP [僅限桌面應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	shlwapi.h
程式庫	Shlwapi.lib
Dll	Shlwapi.dll (4.71 版或更新版本)

共用方式為