CertAddCertificateLinkToStore 函式 (wincrypt.h)

發行項
03/13/2024

CertAddCertificateLinkToStore 函式會將證書存儲中的連結新增至不同存放區中的憑證內容。此函式不會建立和新增憑證內容的重複專案，而是將連結新增至原始憑證。

語法

BOOL CertAddCertificateLinkToStore(
  [in]            HCERTSTORE     hCertStore,
  [in]            PCCERT_CONTEXT pCertContext,
  [in]            DWORD          dwAddDisposition,
  [out, optional] PCCERT_CONTEXT *ppStoreContext
);

參數

[in] hCertStore

要在其中新增連結之證書存儲的句柄。

[in] pCertContext

要連結之CERT_CONTEXT 結構的指標。

[in] dwAddDisposition

如果相符的憑證或相符憑證的連結已存在於存放區中，則指定動作。目前定義的處置值及其用途如下。

值	意義
CERT_STORE_ADD_ALWAYS	函式不會檢查現有的相符憑證，或連結至相符的憑證。新的憑證一律會新增至存放區。這可能會導致存放區中的重複專案。
CERT_STORE_ADD_NEW	如果相符的憑證或相符憑證的連結存在，作業就會失敗。 GetLastError 會傳回CRYPT_E_EXISTS程序代碼。
CERT_STORE_ADD_REPLACE_EXISTING	如果相符憑證的連結存在，就會刪除該現有連結，並建立新的連結並新增至存放區。如果沒有相符的憑證或相符憑證的連結存在，就會新增一個憑證。
CERT_STORE_ADD_USE_EXISTING	如果相符的憑證或相符憑證的連結存在，則會使用現有的憑證。函式不會失敗，但不會新增任何新連結。如果沒有相符的憑證或相符憑證的連結存在，就會新增新的連結。

[out, optional] ppStoreContext

所建立連結複本之指標的指標。 ppStoreContext 參數可以是 NULL，表示不需要連結的複本。如果建立連結的複本，則必須使用 CertFreeCertificateContext 函式釋放該複本。

傳回值

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

如果函式失敗，則傳回值為 FALSE。如需擴充錯誤資訊，請呼叫 GetLastError。以下是一些可能的錯誤碼。

傳回碼	Description
CRYPT_E_EXISTS	對於 CERT_STORE_ADD_NEW 的 dwAddDisposition 參數，憑證已存在於存放區中。
E_INVALIDARG	dwAddDisposition 參數中指定了無效的處置值。

備註

因為連結提供原始憑證內容的存取權，所以在連結的憑證內容中設定擴充屬性會變更憑證原始位置中的擴充屬性，以及該憑證的任何其他連結。

鏈接無法新增至開啟為集合的存放區。以集合形式開啟的存放區包括使用 CERT_STORE_PROV_SYSTEM 或 CERT_STORE_PROV_COLLECTION 以 CertOpenSystemStore 或 CertOpenStore 開啟的所有存放區。如需詳細資訊，請參閱 CertAddStoreToCollection。

如果使用連結，且使用 CERT_CLOSE_STORE_FORCE_FLAG呼叫 CertCloseStore ，則必須先關閉使用連結的存放區，才能關閉包含原始內容的存放區。如果未使用CERT_CLOSE_STORE_FORCE_FLAG，則可以依任一順序關閉這兩個商店。

若要從證書存儲移除憑證內容連結，請使用 CertDeleteCertificateFromStore 函式。

範例

如需使用此函式的範例，請參閱範例 C 程式：證書存儲作業。如需使用此函式的其他程式碼，請參閱範例 C 程式：集合和同層級證書存儲作業。

規格需求

需求	值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	wincrypt.h
程式庫	Crypt32.lib
Dll	Crypt32.dll