Función CertControlStore (wincrypt.h)
La función CertControlStore permite que se notifique a una aplicación cuando hay una diferencia entre el contenido de un almacén almacenado en caché en uso y el contenido de ese almacén tal como se conserva en el almacenamiento. Las diferencias pueden producirse cuando otro proceso realiza un cambio que afecta al almacén a medida que se conserva.
La función CertControlStore se puede usar para sincronizar un almacén almacenado en caché, si es necesario, y proporciona un medio para confirmar los cambios realizados en el almacén almacenado en caché en el almacenamiento persistente.
Sintaxis
BOOL CertControlStore(
[in] HCERTSTORE hCertStore,
[in] DWORD dwFlags,
[in] DWORD dwCtrlType,
[in] void const *pvCtrlPara
);
Parámetros
[in] hCertStore
Identificador del almacén de certificados.
[in] dwFlags
Si el parámetro dwCtrlType se establece en CERT_STORE_CTRL_COMMIT, este parámetro puede ser uno de los valores siguientes.
Si dwCtrlType se establece en CERT_STORE_CTRL_NOTIFY_CHANGE o CERT_STORE_CTRL_RESYNC, el parámetro dwFlags no se usa y debe establecerse en cero.
[in] dwCtrlType
Control de acciones que debe realizar CertControlStore. Las interpretaciones de pvCtrlPara y dwFlags dependen del valor de dwCtrlType. Actualmente, se definen las siguientes acciones.
| Value | Significado |
|---|---|
|
El almacén almacenado en caché se resincroniza y se realiza para que coincida con el almacén persistente. |
|
Se devuelve una señal en el espacio al que apunta pvCtrlPara para indicar que el contenido actual del almacén almacenado en caché difiere del estado persistente del almacén. |
|
Los cambios realizados en el almacén almacenado en caché se copian en el almacenamiento persistente. Si no se realizaron cambios desde que se abrió el almacén almacenado en caché o desde la última confirmación, se omite la llamada. La llamada también se omite si el proveedor del almacén es un proveedor que conserva automáticamente los cambios inmediatamente. |
|
Al principio de cada enumeración o llamada al almacén de búsqueda, se realiza una comprobación para determinar si se ha realizado un cambio en el almacén. Si el almacén ha cambiado, se realiza una nueva sincronización. Esta comprobación solo se realiza en la primera enumeración o en las llamadas de búsqueda, cuando pPrevContext es NULL.
El miembro pvCtrPara no se usa y debe establecerse en NULL. |
|
Cancela la señalización de notificación del identificador de evento pasado en un CERT_STORE_CTRL_NOTIFY_CHANGE anterior o CERT_STORE_CTRL_RESYNC. El parámetro pvCtrlPara apunta al evento HANDLE que se va a cancelar. |
[in] pvCtrlPara
Si dwCtrlType es CERT_STORE_NOTIFY_CHANGE, pvCtrlPara se establece en la dirección de un identificador en el que el sistema señala el evento de cambio de notificación cuando se detecta un cambio del estado persistente del almacén. El identificador debe inicializarse con una llamada a la función CreateEvent. El parámetro pvCtrlPara se puede establecer en NULL para almacenes basados en el Registro. Si pvCtrlPara es NULL, se crea un evento de cambio de notificación interno y se registra para que se señale. El uso del evento de cambio de notificación interno permite las operaciones de resincronización solo si se cambió el almacén.
Si dwCtrlType es CERT_STORE_CTRL_RESYNC, establezca pvCtrlPara en la dirección del identificador de evento que se indicará en el siguiente cambio en el almacén persistente. Normalmente, esta dirección es la dirección del identificador de evento pasado con CERT_STORE_CTRL_NOTIFY_CHANGE durante la inicialización. El identificador de evento pasado se rediseña. Si pvCtrlPara se establece en NULL, no se rediseña ningún evento.
Si dwCtrlType CERT_STORE_CTRL_COMMIT, no se usa pvCtrlPara y debe establecerse en NULL.
Valor devuelto
Si la función se ejecuta correctamente, la función devuelve un valor distinto de cero.
Si se produce un error en la función, devuelve cero. Para obtener información de error extendida, llame a GetLastError.
Si dwCtrlType es CERT_STORE_NOTIFY_CHANGE, la función devuelve un valor distinto de cero si se configuró correctamente un identificador para la señal de evento. La función devuelve cero si no se configuró el identificador de eventos.
Si dwCtrlType es CERT_STORE_CTRL_RESYNC, la función devuelve un valor distinto de cero si la resincronización se realizó correctamente. La función devuelve cero si se produjo un error en la resincronización.
Si dwCtrlType es CERT_STORE_CTRL_COMMIT, la función devuelve un valor distinto de cero para indicar la finalización correcta de la confirmación en el almacenamiento persistente. La función devuelve cero si se produjo un error en la confirmación.
Es posible que algunos proveedores no admitan tipos de control específicos. En estos casos, CertControlStore devuelve cero y GetLastError se establece en el código ERROR_NOT_SUPPORTED.
Comentarios
La resincronización de un almacén se puede realizar en cualquier momento. No es necesario seguir un evento de cambio de notificación señalado.
CERT_STORE_CTRL_NOTIFY_CHANGE se admite en proveedores de almacenes basados en el Registro mediante la función RegNotifyChangeKeyValue .
CertControlStore mediante CERT_STORE_CTRL_NOTIFY_CHANGE se llama una vez para que cada identificador de evento se pase con CERT_STORE_CTRL_RESYNC. Estas llamadas que usan CERT_STORE_CTRL_NOTIFY_CHANGE deben realizarse después de crear cada evento y no después de que se haya señalado un evento.
Ejemplos
En el ejemplo siguiente se muestra cómo permitir que se notifique a una aplicación cuando hay una diferencia entre el contenido de un almacén almacenado en caché en uso y el contenido de ese almacén, ya que se conserva en el almacenamiento. Para obtener el ejemplo completo, incluido el contexto completo de este ejemplo, vea Ejemplo de programa C: configuración y obtención de propiedades del almacén de certificados.
//--------------------------------------------------------------------
// 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");
}
Requisitos
| Cliente mínimo compatible | Windows XP [aplicaciones de escritorio | aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | wincrypt.h |
| Library | Crypt32.lib |
| Archivo DLL | Crypt32.dll |