CryptGetHashParam 函式 (wincrypt.h)

發行項
03/15/2023

重要此 API 已被取代。新的和現有的軟體應該開始使用密碼編譯新一代 API。 Microsoft 可能會在未來的版本中移除此 API。

CryptGetHashParam 函式會擷取控雜湊物件作業的資料。您可以使用這個函式來擷取實際的雜湊值。

語法

BOOL CryptGetHashParam(
  [in]      HCRYPTHASH hHash,
  [in]      DWORD      dwParam,
  [out]     BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen,
  [in]      DWORD      dwFlags
);

參數

[in] hHash

要查詢之雜湊物件的控制碼。

[in] dwParam

查詢類型。此參數可以設定為下列其中一個查詢。

值	意義
HP_ALGID 雜湊演算法	ALG_ID，指出建立雜湊物件時所指定的演算法。如需雜湊演算法的清單，請參閱 CryptCreateHash。
HP_HASHSIZE 雜湊值大小	DWORD 值，指出雜湊值中的位元組數目。此值會根據雜湊演算法而有所不同。應用程式必須在HP_HASHVAL值之前擷取此值，才能配置正確的記憶體數量。
HP_HASHVAL 雜湊值	hHash所指定雜湊物件的雜湊值或訊息雜湊。此值會根據稍早透過 CryptHashData 和 CryptHashSessionKey 函式提供給雜湊物件的資料產生。 CryptGetHashParam函式會完成雜湊。呼叫 CryptGetHashParam 之後，就無法再將資料新增至雜湊。對 CryptHashData或CryptHashSessionKey的其他呼叫失敗。使用雜湊完成應用程式之後，應該呼叫 CryptDestroyHash 來終結雜湊物件。

注意 CSP 可以新增更多可查詢此函式的值。

[out] pbData

接收指定值資料的緩衝區指標。此資料的形式會根據數值數位而有所不同。

此參數可以是 Null ，以判斷所需的記憶體大小。

[in, out] pdwDataLen

DWORD值的指標，指定pbData緩衝區的大小，以位元組為單位。當函式傳回時， DWORD 值會包含儲存在緩衝區中的位元組數目。

如果 pbData 為 Null，請將 pdwDataLen 的值設定為零。

注意處理緩衝區中傳回的資料時，應用程式必須使用傳回的資料實際大小。實際大小可能會稍微小於輸入中指定的緩衝區大小。 (輸入時，通常會指定足夠的緩衝區大小，以確保最大的可能輸出資料符合 buffer。) On 輸出中，此參數所指向的變數會更新，以反映複製到緩衝區的實際資料大小。

[in] dwFlags

保留供日後使用，且必須為零。

傳回值

如果函式成功，則傳回值為 TRUE。

如果函式失敗，傳回值為 FALSE。如需擴充的錯誤資訊，請呼叫 GetLastError。

「NTE」開頭的錯誤碼是由您使用的特定 CSP 所產生。接下來有一些可能的錯誤碼。

傳回碼	描述
ERROR_INVALID_HANDLE	其中一個參數指定不正確控制碼。
ERROR_INVALID_PARAMETER	其中一個參數包含不正確值。這通常是不正確指標。
ERROR_MORE_DATA	如果 pbData 參數指定的緩衝區不夠大，無法保存傳回的資料，函式會設定ERROR_MORE_DATA程式碼，並將所需的緩衝區大小以位元組為單位儲存在 pdwDataLen指向的變數中。
NTE_BAD_FLAGS	dwFlags參數為非零。
NTE_BAD_HASH	hHash參數指定的雜湊物件無效。
NTE_BAD_TYPE	dwParam參數會指定未知的值編號。
NTE_BAD_UID	找不到建立雜湊時所指定的 CSP 內容。

規格需求


最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	wincrypt.h
程式庫	Advapi32.lib
Dll	Advapi32.dll