CertControlStore

[This is preliminary documentation and subject to change.]

The CertControlStore function allows an application to be notified when there is a difference between the contents of a cached store and the contents of the store that is persisted to storage.

CertControlStore also provides re-synchronization of the cached store if necessary, and provides a means to commit changes made in the cached store to persisted storage. Additional functionality is planned.

#include <wincrypt.h>
BOOL WINAPI CertControlStore(
  HCERTSTORE hCertStore,                 // in
  DWORD dwFlags,                         // in
  DWORD dwCtrlType,                      // in
  void const *pvCtrlPara                 // in
);

Parameters

hCertStore

Handle to the certificate store.

dwFlags

For dwCtrlType CERT_STORE_CTRL_COMMIT, defined dwFlags are:

CERT_STORE_CTRL_COMMIT_FORCE_FLAG(0x1) forces the contents of the cache memory store to be copied to permanent storage even if it has not been changed.

CERT_STORE_CTRL_COMMIT_CLEAR_FLAG(0x2) inhibits the copying the contents of the cache memory store to permanent storage even when the store is closed.

For dwCtrlType CERT_STORE_CTRL_NOTIFY_CHANGE and CERT_STORE_CTRL_RESYNC,.dwflags is not used and must be set to 0.

dwCtrlType

Indicates the control action to be taken by CertControlStore. The interpretations of pvCtrlPara and dwFlags depend on the value of dwCtrlType. Currently, three actions are defined:

CERT_STORE_CTRL_RESYNC: The cached store is re-synchronized and made to match the persisted store.
CERT_STORE_CTRL_NOTIFY_CHANGE: Causes a signal returned in the space pointed to by pvCtrlPara to indicate that the current contents of the cached store differ from the store's persisted state.
CERT_STORE_CTRL_COMMIT: Causes any changes made to the cached store to be copied to persisted storage. If no changes were made since the cached store was opened or since the last commit, the call is ignored. The call is also ignored if the store provider is a provider that automatically persists changes immediately.

pvCtrlPara

If dwCtrlType is CERT_STORE_NOTIFY_CHANGE, pvCtrlPara is set to the address of a HANDLE where the system will write a signal when a change from the persisted state of the store is detected. The HANDLE, itself, must be initialized with a call to the function, CreateEvent.

If dwCtrlType is CERT_STORE_CTRL_RESYNC or CERT_STORE_CTRL_COMMIT, pvCtrlPara is not used and should be set to NULL.

Return Values

If dwCtrlType is CERT_STORE_NOTIFY_CHANGE, the function returns TRUE if a HANDLE for the event signal was successfully set up. FALSE is returned if the event HANDLE was not set up.

If dwCtrlType is CERT_STORE_CTRL_RESYNC, the function returns TRUE if the re-synchronization succeeded and FALSE if the re-synchronization failed.

If dwCtrlType is CERT_STORE_CTRL_COMMIT, the function returns TRUE to indicate the successful completion of the commit to persisted storage and FALSE if the commit failed.

Some providers may not support specific control types. In these cases, CertControlStore returns FALSE and GetLastError is set to ERROR_NOT_SUPPORTED.

Remarks

Re-synchronization of a store may be done at any time. It need not follow a signaled notify change event.

CERT_STORE_CTRL_NOTIFY_CHANGE is supported on registry based store providers via the RegNotifyChangeKeyValue function.

Example

HANDLE     hEvent;
HCERTSTORE hCertStore;
BOOL       fSignal;

// Initalize the event.
hEvent=CreateEvent(
NULL,
     FALSE,          // Manual reset is FALSE.
     FALSE,          // The initial state of the event is FALSE.
NULL);
// Open the MY system store. For details, see CertOpenStore.
if(hCertStore = CertOpenStore(
CERT_STORE_PROV_SYSTEM_A, 0, NULL, 0, "MY"))
printf("The MY store is open.\n");
else
handle_error("The MY store was not opened.");
//  Call CertControlStore the first time with 
//  CERT_CONTROL_STORE_NOTIFY_CHANGE.
if(CertControlStore(
    hCertStore,                    // The store to be controlled
    0,                             // Not used 
CERT_STORE_CTRL_NOTIFY_CHANGE, // Control action type
    &hEvent))                      // Points to the event Handle.
                                   //  When a change is detected,
                                   //  a signal is written to the 
                                   //  space pointed to by
                                   //  hHandle.
printf("Notify change worked \n");
else
handle_error("Notify change failed. \n");
// Wait for the store to change.
If(WAIT_OBJECT_0 == WaitForSingleObjectEx(
hEvent,
INFINITE,               // number of milliseconds to wait
FALSE))
fSignal = TRUE;
else
fSignal = FALSE;
if (fSignal)
// The store has changed.
// Call the function a second time with CERT_STORE_CTRL_RESYNC
if(CertControlStore(
          hCertStore,                // in, The store to be controlled
          0,                         // in, Not used.
          CERT_STORE_CTRL_RESYNC,    // in, Control action type
          NULL))                     // in, Not used with re-sync
printf("Re-sync worked. \n");
else
handle_error("Re-sync failed.");
else
{
printf("The store was not changed \n");
printf("Re-sync not needed. \n");
}

QuickInfo