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

Статья
08/27/2023

Функция 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, этот параметр может иметь одно из следующих значений.

Значение	Значение
CERT_STORE_CTRL_COMMIT_FORCE_FLAG	Принудительное копирование содержимого хранилища памяти кэша в постоянное хранилище, даже если кэш не был изменен.
CERT_STORE_CTRL_COMMIT_CLEAR_FLAG	Блокирует копирование содержимого хранилища кэша в постоянное хранилище, даже если хранилище закрыто.
CERT_STORE_CTRL_INHIBIT_DUPLICATE_HANDLE_FLAG	Блокирует повторяющийся дескриптор события HANDLE. Если этот флаг установлен, перед закрытием дескриптора hCertCertStore необходимо вызвать CertControlStore с передачей CERT_STORE_CTRL_CANCEL_NOTIFY.

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

[in] dwCtrlType

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

Значение	Значение
CERT_STORE_CTRL_RESYNC	Кэшированное хранилище повторно синхронизируется и выполняется в соответствии с сохраненным хранилищем.
CERT_STORE_CTRL_NOTIFY_CHANGE	Сигнал возвращается в пространстве, на который указывает pvCtrlPara , чтобы указать, что текущее содержимое кэшированного хранилища отличается от сохраненного состояния хранилища.
CERT_STORE_CTRL_COMMIT	Все изменения, внесенные в кэшированное хранилище, копируются в сохраненное хранилище. Если с момента открытия кэшированного хранилища или с момента последней фиксации не было внесено никаких изменений, вызов игнорируется. Вызов также игнорируется, если поставщик хранилища является поставщиком, который автоматически сохраняет изменения немедленно.
CERT_STORE_CTRL_AUTO_RESYNC	В начале каждого вызова перечисления или поиска хранилища выполняется проверка, чтобы определить, было ли внесено изменение в хранилище. Если хранилище изменилось, выполняется повторная синхронизация. Это проверка выполняется только при первых вызовах перечисления или поиска, если pPrevContext имеет значение NULL. Член pvCtrPara не используется и должен иметь значение NULL.
CERT_STORE_CTRL_CANCEL_NOTIFY	Отменяет отправку уведомлений о событии HANDLE, переданном в предыдущем CERT_STORE_CTRL_NOTIFY_CHANGE или CERT_STORE_CTRL_RESYNC. Параметр pvCtrlPara указывает на событие HANDLE, которое требуется отменить.

[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 код.

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");
}

Требования


Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	wincrypt.h
Библиотека	Crypt32.lib
DLL	Crypt32.dll

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

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

CreateEvent

WaitForSingleObjectEx