CertFindCTLInStore 函式（wincrypt.h）

發行項
07/16/2024

CertFindCTLInStore 函式會尋找第一個或下一個憑證信任清單（CTL）內容，其符合 dwFindType 及其相關聯 pvFindPara所建立的搜尋準則。此函式可在迴圈中使用，在符合指定尋找準則的證書存儲中尋找所有 CTL 內容。

語法

PCCTL_CONTEXT CertFindCTLInStore(
  [in] HCERTSTORE    hCertStore,
  [in] DWORD         dwMsgAndCertEncodingType,
  [in] DWORD         dwFindFlags,
  [in] DWORD         dwFindType,
  [in] const void    *pvFindPara,
  [in] PCCTL_CONTEXT pPrevCtlContext
);

參數

[in] hCertStore

要搜尋的證書存儲句柄。

[in] dwMsgAndCertEncodingType

指定 CTL 上使用的編碼類型。一律可以接受藉由將憑證和訊息編碼類型與位OR 作業結合在一起，以指定訊息編碼類型，如下列範例所示：

X509_ASN_ENCODING |PKCS_7_ASN_ENCODING目前定義的編碼類型如下：

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

只有當 dwFindType 參數設定為 CTL_FIND_USAGE時，才會使用此參數。

[in] dwFindFlags

當 dwFindType 設定為 CTL_FIND_USAGE 時，可以設定。如需詳細資訊，請參閱下列CTL_FIND_USAGE下的批注。

[in] dwFindType

指定要進行的搜尋類型。搜尋類型會決定資料類型、內容，以及使用 pvFindPara。此參數可以是下列其中一個值。

價值	意義
CTL_FIND_ANY	pvFindPara的數據類型：NULL。任何 CTL 都是相符專案。
CTL_FIND_SHA1_HASH	pvFindPara資料類型：CRYPT_HASH_BLOB。找到與 CRYPT_HASH_BLOB 結構中哈希相符的 CTL。
CTL_FIND_MD5_HASH	pvFindPara資料類型：CRYPT_HASH_BLOB。找到與 CRYPT_HASH_BLOB 結構中哈希相符的 CTL。
CTL_FIND_USAGE	pvFindPara的數據類型：CTL_FIND_USAGE_PARA。找到任何 CTL，其使用方式識別碼、清單標識碼或簽署者符合 CTL_FIND_USAGE_PARA 結構中的使用標識碼、清單標識碼或登入者。如果 cUsageIdentifier 成員是 SubjectUsage 大小，則任何 CTL 都是相符的。如果 ListIdentifier 成員的 cbData 成員為零，則任何清單標識碼都是相符的。如果 ListIdentifier 的 cbData 成員是CTL_FIND_NO_LIST_ID_CBDATA，則只有沒有清單標識碼的 CTL 是相符的。如果 CTL_FIND_USAGE_PARA 結構中的 pSigner 成員 NULL，則任何 CTL 簽署者都是相符的，而且只會使用 pSignerCERT_INFO 結構中的 Issuer 和 SerialNumber 成員。如果 pSigner 是CTL_FIND_NO_SIGNER_PTR，則只有沒有簽署者的 CTL 是相符專案。
CTL_FIND_SAME_USAGE_FLAG	pvFindPara的數據類型：CTL_FIND_USAGE_PARA。只會比對具有相同使用標識碼的 CTL。具有其他使用標識碼的 CTL 不相符。例如，如果在 CTL_FIND_USAGE_PARA 結構中只指定「1.2.3」，則 CTL 必須只包含「1.2.3」，而且沒有額外的使用標識碼。
CTL_FIND_EXISTING	pvFindPara的資料類型：PCCTL_CONTEXT。搜尋與 CTL_CONTEXT完全相符的下一個CRL。
CTL_FIND_SUBJECT	pvFindPara的數據類型：CTL_FIND_SUBJECT_PARA。找到具有指定主體的 CTL。 CertFindSubjectInCTL，以取得 CTL 中主旨專案的指標。 CTL_FIND_SUBJECT_PARA 中的 pUsagePara 成員可以選擇性地設定為啟用CTL_FIND_USAGE中所述的比對。

[in] pvFindPara

與 dwFindType 參數相關聯的搜尋值指標。

[in] pPrevCtlContext

此函式所傳回之最後一個 CTL_CONTEXT 的指標。它必須 NULL，才能取得存放區中的第一個 CTL。後續 CTL 的擷取方式是將 pPrevCtlContext 設定為先前函數調用所傳回之 CTL_CONTEXT 指標。略過任何不符合搜尋準則或先前由 CertDeleteCTLFromStore 刪除的憑證。此函式會釋放此參數非NULL 值所參考的 CTL_CONTEXT。

傳回值

如果函式成功，傳回值是只讀 CTL 內容的指標。

如需擴充錯誤資訊，請呼叫 getLastError。以下是一些可能的錯誤碼。

傳回碼	描述
CRYPT_E_NOT_FOUND	在市集中找不到 CTL、找不到符合搜尋準則的 CTL，或函式到達商店清單的結尾。
E_INVALIDARG	hCertStore 參數中的句柄與 pPrevCtlContext 參數所指向的 CTL 內容中的句柄不同，或 dwFindType 參數中指定的值。

言論

在後續呼叫函式時，會釋出傳回的指標作為 pPrevCtlContext pPrevCtlContext。否則，必須呼叫 CertFreeCTLContext釋放指標。傳遞至函式的非NULLpPrevCtlContext 一律會釋出呼叫 CertFreeCTLContext，即使函式產生錯誤也一樣。

可呼叫 CertDuplicateCTLContext，以複製傳回的內容。傳回的 CTL 內容可以使用 CertAddCTLContextToStore新增至不同的證書存儲，或使用 CertAddCTLLinkToStore新增至該 CTL 內容的連結。如果找不到符合搜尋準則的 CTL，則會傳回 NULL 。

要求

要求	價值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
支援的最低伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平臺	窗戶
標頭	wincrypt.h
連結庫	Crypt32.lib
DLL	Crypt32.dll