CertAddStoreToCollection

[This is preliminary documentation and subject to change.]

The CertAddStoreToCollection function adds a sibling certificate store to a collection certificate store.

#include <wincrypt.h>
BOOL WINAPI CertAddStoreToCollection(
  HCERTSTORE hCollectionStore,            // in
  HCERTSTORE hSiblingStore,               // in optional
  DWORD dwUpdateFlag,                     // in
  DWORD dwPriority                            // in
);

Parameters

hCollectionStore: Handle to the certificate store.
hSiblingStore: Handle of a sibling store to be added to the collection store. See Remarks.
dwUpdateFlag: Flag to indicate whether certificates, CRLs, and CTLs can be added to the new sibling store member of the collection store . Set dwUpdateFlag to CERT_PHYSICAL_STORE_ADD_ENABLE_FLAG to enable addition or to 0 to disable additions.
dwPriority: DWORD used to set a priority level of the new store in the collection, with zero being the lowest priority. If zero is passed for this parameter, the specified store will be appended as the last store in the collection. The priority levels of the stores in a collection determine the order in which the stores are enumerated, and the search order of the stores when attempting to retrieve a certificate, CRL, or CTL. Priority levels also determine into which store of a collection a new certificate, CRL or CTL will be added. See Remarks for further information.

Return Values

TRUE is returned if a new store was added to the collection of stores. FALSE is returned if the function failed.

Remarks

A collection store has the same HCERTSTORE handle as a single store; thus, almost all functions that apply to any certificate store also apply to any collection store. Enumeration and find processes span all of the stores in a collection store; however, functions that add links to stores such as CertAddCertificateLinkToStore cannot be used with collection stores.

When a certificate, CRL, or CTL is added to a collection store, the list of sibling stores in the collection is searched in priority order to find the first store that allows adding. Adding is enabled if CERT_PHYSICAL_STORE_ADD_ENABLE_FLAG was set in the CertAddStoreToCollection call. With any function that adds elements to a store, if a store that allows adding does not return success, the add function silently continues on to the next store.

When a collection store and its sibling stores are closed with CertCloseStore using the CERT_CLOSE_STORE_FORCE_FLAG, the collection store must be closed before its sibling stores. If the CERT_CLOSE_STORE_FORCE_FLAG is not used, the stores may be closed in any order.

Example

// handle_error() is a function defined in a separate file.
HCERTSTORE hCollectionStore;
HCERTSTORE hSiblingStore;

// Open the collection store. For details, see CertOpenStore.
if(hCollectionStore = CertOpenStore(
CERT_STORE_PROV_COLLECTION, 
     0,        // For CERT_STORE_PROV_COLLECTION,
               // the rest of the parameters
               // must be 0 or NULL.
NULL,
0,
NULL))
// The collection store opened. Continue.
printf("Opened the COLLECTION Store\n");
else
handle_error("Error opening Store from disk.");
// Open a sibling store. For details, see CertOpenStore.
if(hsiblingstore = CertOpenStore(
   CERT_STORE_PROV_MEMORY,   // For the memory provider type,
   0,                        // the rest of the parameters must
   NULL,                     // be 0 or NULL.
0,                        
NULL))
// The memory store to be a sibling store opened. Continue.
printf("Memory store open. \n");
else
handle_error("Memory store not open.");
// Add the sibling store to the collection.
if(CertAddStoreToCollection(
hCollectionStore,
hSiblingStore,
   CERT_PHYSICAL_STORE_ADD_ENABLE_FLAG,     // dwUpdateFlag 
   3                                        // Store priority 
                                            // in the collection.
   ))
// The sibling store was added to the collection. Continue.
printf("A sibling store has been added to the collection.\n");
else
handle_error("The sibling store was not added to the collection.");
//
// Work with certificates in the collection store and close the 
// stores. 
// Note that a find on the collection store will locate 
// contexts in any of its sibling stores.
//

QuickInfo