CertAddCTLLinkToStore

[This is preliminary documentation and subject to change.]

The CertAddCTLLinkToStore function adds a link in a store to a CTL context in a different store. Instead of creating and adding a duplicate of a CTL context, this function adds a link to the original CTL context wherever it may be. Since the link provides access to the original CTL context, setting an extended property in the linked CTL context changes that property as seen in the original CTL's location and by any other links to that CTL. .

#include <wincrypt.h>
BOOL WINAPI CertAddCTLLinkToStore(
  HCERTSTORE hCertStore,                   // in
  PCTL_CONTEXT pCTLContext,                // in
  DWORD dwAddDisposition,                  // in
  PCCTL_CONTEXT *ppStoreContext            // out optional
);

Parameters

hCertStore

Handle to the certificate store where the link is to be added.

pCTLContext

Pointer to the CTL context that is to be linked.

dwAddDisposition

Value that specifies the action to take if a matching CTL or a link to a matching CTL already exists in the store. Currently defined disposition values and their uses are:

CERT_STORE_ADD_NEW: If a matching CTL or a link to a matching CTL exists, the operation fails. GetLastError returns CRYPT_E_EXISTS.
CERT_STORE_ADD_USE_EXISTING: If a matching CTL or a link to a matching CTL exists that existing link is used. The function does not fail, but no new link is added. If a matching CTL or link to a CTL does not exist, a new link is added.
CERT_STORE_ADD_REPLACE_EXISTING: If a link to the matching CTL exists, that existing link is deleted and a new link is created and added to the store. If a matching CTL or a link to a matching CTL does not exist, a new link is added.
CERT_STORE_ADD_ALWAYS: Makes no check for an existing matching CTL or link to a matching CTL. A new link is always added to the store. This may lead to duplicates in a store.
CERT_STORE_ADD_NEWER: If a matching CTL or a link to a matching CTL exists, the ThisUpdate times on the CTLs are compared. If the existing CTL has a ThisUpdate time less than the ThisUpdate time on the new CTL, the old link is replaced just as with CERT_STORE_ADD_REPLACE_EXISTING. If the existing CTL has a ThisUpdate time greater than or equal to the ThisUpdate time on the CTL to be added, the function fails with GetLastError returning CRYPT_E_EXISTS.
If a matching CTL or a link to a matching CTL is not found in the store, a new link is added to the store.

ppStoreContext

Pointer to a pointer to a copy of the link created. ppStoreContext can be NULL to indicate that a copy of the link is not needed. If a copy of the link is created, that copy must be freed using CertFreeCTLContext.

Return Values

TRUE if the function succeeded. FALSE if the function failed.

GetLastError returns the code for any failures using the following error codes:

Error code	Description
CRYPT_E_EXISTS	For a dwAddDisposition of CERT_STORE_ADD_NEW, the CTL already exists in the store.
E_INVALIDARG	Invalid add disposition specified by the dwAddDisposition argument.

Remarks

Links cannot be added to a store that is opened as a collection. Stores opened as collections include all stores opened with CertOpenSystemStore or CertOpenStore using CERT_STORE_PROV_SYSTEM or CERT_STORE_PROV_COLLECTION. Also see CertAddStoreToCollection.

When links are used and CertCloseStore is called with CERT_CLOSE_STORE_FORCE_FLAG, the store using links must be closed before the store containing the original contexts is closed. If CERT_CLOSE_STORE_FORCE_FLAG is not used, the two stores may be closed in either order.

Example

See the example with CertAddCertificateLinkToStore. This example will hold for CertAddCTLLinkToStore if all the references to "certificate" are changed to "CTL."

QuickInfo