Функция 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. В настоящее время определены следующие действия.
| Значение | Значение |
|---|---|
|
Кэшированное хранилище повторно синхронизируется и выполняется в соответствии с сохраненным хранилищем. |
|
Сигнал возвращается в пространстве, на который указывает pvCtrlPara , чтобы указать, что текущее содержимое кэшированного хранилища отличается от сохраненного состояния хранилища. |
|
Все изменения, внесенные в кэшированное хранилище, копируются в сохраненное хранилище. Если с момента открытия кэшированного хранилища или с момента последней фиксации не было внесено никаких изменений, вызов игнорируется. Вызов также игнорируется, если поставщик хранилища является поставщиком, который автоматически сохраняет изменения немедленно. |
|
В начале каждого вызова перечисления или поиска хранилища выполняется проверка, чтобы определить, было ли внесено изменение в хранилище. Если хранилище изменилось, выполняется повторная синхронизация. Это проверка выполняется только при первых вызовах перечисления или поиска, если pPrevContext имеет значение NULL.
Член pvCtrPara не используется и должен иметь значение NULL. |
|
Отменяет отправку уведомлений о событии 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 код.
Комментарии
Повторная синхронизация хранилища может быть выполнена в любое время. Он не должен следовать сигнальным событием изменения уведомления.
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");
}
Требования
| Минимальная версия клиента | Windows XP [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | wincrypt.h |
| Библиотека | Crypt32.lib |
| DLL | Crypt32.dll |