SHRegQueryUSValueW 函式 （shlwapi.h）

擷取與使用者特定子樹中開啟登錄子機碼相關聯之指定名稱的類型和數據（HKEY_CURRENT_USER或HKEY_LOCAL_MACHINE）。

語法

LSTATUS SHRegQueryUSValueW(
  [in]                HUSKEY  hUSKey,
  [in, optional]      LPCWSTR 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 旗標來擷取錯誤的泛型描述。

言論

當 fIgnoreHKCU 設定為 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，並將 dwDefaultDataS ize 設為零。

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

注意

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

要求

要求	價值
最低支援的用戶端	Windows 2000 Professional、Windows XP [僅限傳統型應用程式]
支援的最低伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平臺	窗戶
標頭	shlwapi.h
連結庫	Shlwapi.lib
DLL	Shlwapi.dll （4.71 版或更新版本）