Функция CertControlStore (wincrypt.h)

Функция CertControlStore позволяет приложению получать уведомления о различиях между содержимым используемого кэшированного хранилища и содержимым этого хранилища по мере его сохранения в хранилище. Различия могут возникать, когда другой процесс вносит изменения, влияющие на хранилище по мере его сохранения.

При необходимости функция CertControlStore может использоваться для синхронизации кэшированного хранилища и предоставляет средства для фиксации изменений, внесенных в кэшированном хранилище, в сохраненное хранилище.

Синтаксис

BOOL CertControlStore(
  [in] HCERTSTORE hCertStore,
  [in] DWORD      dwFlags,
  [in] DWORD      dwCtrlType,
  [in] void const *pvCtrlPara
);

Параметры

[in] hCertStore

Дескриптор хранилища сертификатов.

[in] dwFlags

Если параметру dwCtrlType присвоено значение CERT_STORE_CTRL_COMMIT, этот параметр может иметь одно из следующих значений.

Если параметру dwCtrlType присвоено значение CERT_STORE_CTRL_NOTIFY_CHANGE или CERT_STORE_CTRL_RESYNC, параметр dwFlags не используется и должен быть равен нулю.

[in] dwCtrlType

Действие управления, выполняемое CertControlStore. Интерпретации pvCtrlPara и dwFlags зависят от значения dwCtrlType. В настоящее время определены следующие действия.

[in] pvCtrlPara

Если параметр dwCtrlType CERT_STORE_NOTIFY_CHANGE, параметру pvCtrlPara присваивается адрес дескриптора, по которому система сигнализирует о событии изменения уведомления при обнаружении изменения сохраненного состояния хранилища. Дескриптор должен быть инициализирован с помощью вызова функции CreateEvent. Параметру pvCtrlPara можно задать значение NULL для хранилищ на основе реестра. Если параметр pvCtrlPara имеет значение NULL, создается и регистрируется событие изменения внутреннего уведомления для передачи сигнала. Использование события изменения внутреннего уведомления позволяет выполнять операции повторной синхронизации только в том случае, если хранилище было изменено.

Если параметр dwCtrlType CERT_STORE_CTRL_RESYNC, задайте для параметра pvCtrlPara адрес дескриптора события, который будет указан при следующем изменении в сохраненном хранилище. Как правило, это адрес дескриптора события, передаваемого с CERT_STORE_CTRL_NOTIFY_CHANGE во время инициализации. Переданный дескриптор события перенаправлен. Если параметру pvCtrlPara присвоенозначение NULL, событие не перенаправляется.

Если dwCtrlType CERT_STORE_CTRL_COMMIT, параметр pvCtrlPara не используется и должен иметь значение NULL.

Возвращаемое значение

Если функция выполнена успешно, функция возвращает ненулевое значение.

Если функция завершается сбоем, она возвращает ноль. Чтобы получить дополнительные сведения об ошибке, вызовите Метод GetLastError.

Если параметр dwCtrlType CERT_STORE_NOTIFY_CHANGE, функция возвращает ненулевое значение, если дескриптор для сигнала события был успешно настроен. Функция возвращает ноль, если дескриптор события не был настроен.

Если параметр dwCtrlType имеет CERT_STORE_CTRL_RESYNC, функция возвращает ненулевое значение, если повторная синхронизация выполнена успешно. Функция возвращает ноль, если повторная синхронизация завершилась сбоем.

Если параметр dwCtrlType CERT_STORE_CTRL_COMMIT, функция возвращает ненулевое значение, указывающее на успешное завершение фиксации в сохраненное хранилище. Функция возвращает ноль, если фиксация завершилась сбоем.

Некоторые поставщики могут не поддерживать определенные типы элементов управления. В таких случаях CertControlStore возвращает ноль, а getLastError имеет ERROR_NOT_SUPPORTED код.

Комментарии

Повторная синхронизация хранилища может быть выполнена в любое время. Он не должен следовать сигнальным событием изменения уведомления.

CERT_STORE_CTRL_NOTIFY_CHANGE поддерживается поставщиками хранилищ на основе реестра с помощью функции RegNotifyChangeKeyValue .

CertControlStore с помощью CERT_STORE_CTRL_NOTIFY_CHANGE вызывается один раз для каждого дескриптора события, передаваемого с CERT_STORE_CTRL_RESYNC. Эти вызовы с использованием CERT_STORE_CTRL_NOTIFY_CHANGE должны выполняться после создания каждого события, а не после передачи сигнала о событии.

Примеры

В следующем примере показано, как разрешить приложению получать уведомления при наличии различий между содержимым кэшированного хранилища и содержимым этого хранилища по мере его сохранения в хранилище. Полный пример, включая полный контекст для этого примера, см. в разделе Пример программы C: настройка и получение свойств хранилища сертификатов.

//--------------------------------------------------------------------
// Declare and initialize variables.

HCERTSTORE hCertStore;     // Original certificate store
HANDLE     hEvent;
BOOL       fSignal;

//--------------------------------------------------------------------
// Initialize an event.

if(hEvent = CreateEvent(
    NULL,
    FALSE,          // Manual reset is FALSE
    FALSE,          // The initial state of the event is FALSE
    NULL))
{
     printf("An event has been created. \n");
}
else
{
     printf("The event was not created. \n");
     exit(1);
}

//--------------------------------------------------------------------
// Open the MY certificate store. 

if ( hCertStore = CertOpenStore(
    CERT_STORE_PROV_SYSTEM,
    0,
    NULL,
    CERT_SYSTEM_STORE_CURRENT_USER,
    L"MY"))
{
    printf("The MY store is open. \n");
}
else
{
    printf("The MY store did not open. \n");
    exit(1);
}

//--------------------------------------------------------------------
//  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 
                    //  memory location pointed to by
                    //  hHandle.
{
    printf("Notify change worked. \n");
}
else
{
    printf("Notify change failed. \n");
    exit(1);
}

//--------------------------------------------------------------------
// Wait for the store to change.

fSignal = (WAIT_OBJECT_0 == WaitForSingleObjectEx(
    hEvent,
    1000,        // Number of milliseconds to wait;
            // Use INFINITE to wait indefinitely for
            // a change
    FALSE));

if (fSignal)
{

//--------------------------------------------------------------------
// The store has changed.
// Call the function a second time with CERT_STORE_CTRL_RESYNC.

    if(CertControlStore(
        hCertStore,             // The store to be controlled
        0,                      // Not used
        CERT_STORE_CTRL_RESYNC, // Control action type
        &hEvent))               // The handle of the event 
                                // to be rearmed

    printf("Resynchronization worked. \n");
    
    else
    {
        printf("Resynchronization failed. \n");
        exit(1);
    }
}
else
{
      printf("The store was not changed. \n");
      printf("Resynchronization was not needed. \n");
}

// Release the handle to the store.

if(CertCloseStore(hCertStore,
                   0))
{
        printf("The MY store was closed. \n");
}
else
{
        printf("An error occurred. The MY store was not closed. \n");
}

Требования

См. также раздел

Функции хранилища сертификатов

CreateEvent

WaitForSingleObjectEx