CertCloseStore (Compact 2013)

3/28/2014

This function closes a certificate store handle and reduces the reference count on the store. There needs to be a corresponding call to the CertCloseStore function for each successful call to the CertOpenStore or CertDuplicateStore function.

Syntax

BOOL WINAPI CertCloseStore(
  HCERTSTORE hCertStore,
  DWORD dwFlags
);

Parameters

• hCertStore
  [in] Handle to the certificate store to be closed.

• dwFlags
  [in] Bitmask of flags. Typically, this parameter uses the default value zero. The default behavior is to close the store with memory remaining allocated for contexts that have not been freed. In this case, no check is made to determine whether memory for contexts remains allocated.

  Set flags can force the freeing of memory for all of a store's certificate contexts when the store is closed. Flags can also be set that check whether all of the store's certificate contexts have been freed. The following table shows values for this parameter.

  Value	Description
  CERT_CLOSE_STORE_CHECK_FLAG	Checks for certificate context that has not been freed. A returned error code indicates that one or more store elements are still in use. This flag should only be used as a diagnostic tool in the development of applications.
  CERT_CLOSE_STORE_FORCE_FLAG	Forces the freeing of memory for all contexts associated with the store. This flag can be safely used only when the store is opened in a function and neither the store handle nor any of its contexts are passed to any called functions. For details, see the Remarks section.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

For extended error information, call the GetLastError function.

If CERT_CLOSE_STORE_CHECK_FLAG is not set or if it is set and all contexts associated with the store have been freed, the return value is TRUE.

If CERT_CLOSE_STORE_CHECK_FLAG is set and memory for one or more contexts associated with the store remains allocated, the return value is FALSE. The store is always closed even when the function returns FALSE. For details, see the Remarks section.

The GetLastError function is set to CRYPT_E_PENDING_CLOSE if memory for contexts associated with the store remains allocated. Any existing value returned by the GetLastError function is preserved unless CERT_CLOSE_STORE_CHECK_FLAG is set.

Remarks

While a certificate store is open, contexts from that store can be retrieved or duplicated. When a context is retrieved or duplicated, its reference count is incremented. When a context is freed by passing it to a search or enumeration function as a previous context or by using the CertFreeCertificateContext function, its reference count is decremented. When a context's reference count reaches zero, memory allocated for that context is automatically freed. When the memory allocated for a context has been freed, any pointers to that context become invalid.

By default, memory used to store contexts with reference counts greater than zero is not freed when a certificate store is closed. References to those contexts remain valid; however, this can cause memory leaks. Also, any changes made to the properties of a context after the store has been closed are not persisted.

To force the freeing of memory for all contexts associated with a store, set CERT_STORE_CLOSE_FORCE_FLAG. With this flag set, memory for all contexts associated with the store is freed and all pointers to certificate contexts associated with the store become invalid. This flag should only be set when the store is opened in a function and neither the store handle nor any of its contexts were ever passed to any called functions.

The status of reference counts on contexts associated with a store can be checked when the store is closed by using CERT_CLOSE_STORE_CHECK_FLAG. When this flag is set, and all certificate contexts have not been freed, the function returns FALSE and the GetLastError function returns CRYPT_E_PENDING_CLOSE. Note that the store is still closed when FALSE is returned and the memory for any active contexts is not freed.

If CERT_STORE_NO_CRYPT_RELEASE_FLAG was not set when the store was opened, closing a store frees its CSP handle.

Requirements

See Also

Reference

Certificates Functions
CertDuplicateStore
CertFreeCertificateContext
CertOpenStore
CryptReleaseContext