CertAddCTLLinkToStore 函式 (wincrypt.h)

發行項
03/03/2024

CertAddCTLLinkToStore 函式會將存放區中的連結新增至不同存放區中的憑證信任清單 (CTL) 內容。此函式會新增原始 CTL 內容的連結，而不是建立和新增 CTL 內容的複本。

語法

BOOL CertAddCTLLinkToStore(
  [in]            HCERTSTORE    hCertStore,
  [in]            PCCTL_CONTEXT pCtlContext,
  [in]            DWORD         dwAddDisposition,
  [out, optional] PCCTL_CONTEXT *ppStoreContext
);

參數

[in] hCertStore

要新增連結的證書存儲句柄。

[in] pCtlContext

要連結之CTL_CONTEXT 結構的指標。

[in] dwAddDisposition

指定在存放區中已經存在相符 CTL 或相符 CTL 連結時，要採取的動作。目前定義的處置值及其用途如下。

值	意義
CERT_STORE_ADD_ALWAYS	不檢查現有的相符 CTL 或與相符 CTL 的連結。新的 CTL 一律會新增至存放區。這可能會導致存放區中的重複專案。
CERT_STORE_ADD_NEW	如果相符的 CTL 或相符 CTL 的連結存在，作業就會失敗。 GetLastError 會傳回CRYPT_E_EXISTS程序代碼。
CERT_STORE_ADD_NEWER	如果相符的 CTL 或相符 CTL 的連結存在，則會比較 CTL 上的 ThisUpdate 時間。如果現有的 CTL 的 ThisUpdate 時間小於新 CTL 上的 ThisUpdate 時間，舊的 CTL 或連結會取代為與CERT_STORE_ADD_REPLACE_EXISTING相同。如果現有的 CTL 的 ThisUpdate 時間大於或等於要新增之 CTL 上的 ThisUpdate 時間，則函式會失敗，並傳回CRYPT_E_EXISTS程式代碼的 GetLastError 。如果在存放區中找不到相符 CTL 或相符 CTL 的連結，則會將新的 CTL 新增至存放區。
CERT_STORE_ADD_NEWER_INHERIT_PROPERTIES	動作與CERT_STORE_ADD_NEWER相同，不同之處在於，如果取代較舊的 CTL，則會將較舊 CTL 的屬性併入取代 CTL 中。
CERT_STORE_ADD_REPLACE_EXISTING	如果相符的 CTL 或相符 CTL 的連結存在，則會刪除現有的 CTL 或連結，並建立新的 CTL 並新增至存放區。如果相符的 CTL 或相符 CTL 的連結不存在，則會新增一個。
CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES	如果存放區中有相符的 CTL，則會先刪除現有的內容，再建立和新增內容。新增的內容會繼承現有 CTL 的屬性。
CERT_STORE_ADD_USE_EXISTING	如果有相符的 CTL 或相符 CTL 的連結存在，則會使用現有的 CTL，並新增來自新 CTL 的屬性。函式不會失敗，但不會新增任何新的 CTL。如果 ppCertContext 不是 NULL，則會複製現有的內容。如果相符的 CTL 或相符 CTL 的連結不存在，則會新增新的 CTL。

[out, optional] ppStoreContext

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

傳回值

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

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

傳回碼	Description
CRYPT_E_EXISTS	對於 CERT_STORE_ADD_NEW的 dwAddDisposition，CTL 已存在於存放區中。
E_INVALIDARG	dwAddDisposition 參數指定的新增配置無效。

備註

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

無法將連結新增至以集合方式開啟的存放區。以集合方式開啟的存放區包括使用 CertOpenSystemStore 或 CertOpenStore 開啟的所有存放區，使用 CERT_STORE_PROV_SYSTEM 或 CERT_STORE_PROV_COLLECTION。另請參閱 CertAddStoreToCollection。

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

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

規格需求

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