Compartir a través de


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.

Value Significado
CERT_STORE_CTRL_COMMIT_FORCE_FLAG
Obliga a que el contenido del almacén de memoria caché se copie en almacenamiento permanente, incluso si no se ha cambiado la memoria caché.
CERT_STORE_CTRL_COMMIT_CLEAR_FLAG
Impide la copia del contenido del almacén de memoria caché en el almacenamiento permanente incluso cuando se cierra el almacén.
CERT_STORE_CTRL_INHIBIT_DUPLICATE_HANDLE_FLAG
Impide un identificador duplicado del identificador del evento HANDLE. Si se establece esta marca, se debe llamar a CertControlStore con CERT_STORE_CTRL_CANCEL_NOTIFY pasado para este evento HANDLE antes de cerrar el identificador hCertStore .
 

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
CERT_STORE_CTRL_RESYNC
El almacén almacenado en caché se resincroniza y se realiza para que coincida con el almacén persistente.
CERT_STORE_CTRL_NOTIFY_CHANGE
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.
CERT_STORE_CTRL_COMMIT
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.
CERT_STORE_CTRL_AUTO_RESYNC
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.

CERT_STORE_CTRL_CANCEL_NOTIFY
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

Consulte también

Funciones del almacén de certificados

CreateEvent

WaitForSingleObjectEx