SHRegQueryUSValueA 函式 (shlwapi.h)

擷取與使用者特定子樹 (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 更有效率，因為密鑰只會開啟一次。

規格需求