Partager via


Fonction CertControlStore (wincrypt.h)

La fonction CertControlStore permet à une application d’être avertie lorsqu’il existe une différence entre le contenu d’un magasin mis en cache en cours d’utilisation et le contenu de ce magasin à mesure qu’il est conservé dans le stockage. Des différences peuvent se produire quand un autre processus apporte une modification qui affecte le magasin à mesure qu’il est persistant.

La fonction CertControlStore peut être utilisée pour synchroniser un magasin mis en cache, si nécessaire, et fournit un moyen de valider les modifications apportées dans le magasin mis en cache dans le stockage persistant.

Syntaxe

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

Paramètres

[in] hCertStore

Handle du magasin de certificats.

[in] dwFlags

Si le paramètre dwCtrlType est défini sur CERT_STORE_CTRL_COMMIT, il peut s’agir de l’une des valeurs suivantes.

Valeur Signification
CERT_STORE_CTRL_COMMIT_FORCE_FLAG
Force le contenu du magasin de mémoire du cache à être copié dans un stockage permanent même si le cache n’a pas été modifié.
CERT_STORE_CTRL_COMMIT_CLEAR_FLAG
Empêche la copie du contenu du magasin de mémoire du cache vers un stockage permanent, même lorsque le magasin est fermé.
CERT_STORE_CTRL_INHIBIT_DUPLICATE_HANDLE_FLAG
Empêche un handle dupliqué de l’événement HANDLE. Si cet indicateur est défini, CertControlStore avec CERT_STORE_CTRL_CANCEL_NOTIFY passé doit être appelé pour ce HANDLE d’événement avant de fermer le handle hCertStore .
 

Si dwCtrlType est défini sur CERT_STORE_CTRL_NOTIFY_CHANGE ou CERT_STORE_CTRL_RESYNC, le paramètre dwFlags n’est pas utilisé et doit être défini sur zéro.

[in] dwCtrlType

Action de contrôle à effectuer par CertControlStore. Les interprétations de pvCtrlPara et dwFlags dépendent de la valeur de dwCtrlType. Actuellement, les actions suivantes sont définies.

Valeur Signification
CERT_STORE_CTRL_RESYNC
Le magasin mis en cache est resynchronisé et fait correspondre au magasin persistant.
CERT_STORE_CTRL_NOTIFY_CHANGE
Un signal est retourné dans l’espace vers lequel pointe pvCtrlPara pour indiquer que le contenu actuel du magasin mis en cache diffère de l’état persistant du magasin.
CERT_STORE_CTRL_COMMIT
Toutes les modifications apportées au magasin mis en cache sont copiées dans le stockage persistant. Si aucune modification n’a été apportée depuis l’ouverture du magasin mis en cache ou depuis la dernière validation, l’appel est ignoré. L’appel est également ignoré si le fournisseur de magasins est un fournisseur qui conserve automatiquement les modifications immédiatement.
CERT_STORE_CTRL_AUTO_RESYNC
Au début de chaque appel d’énumération ou de magasin de recherche, une case activée est effectuée pour déterminer si une modification a été apportée dans le magasin. Si le magasin a changé, une resynchronisation est effectuée. Cette case activée est effectuée uniquement lors de la première énumération ou des appels de recherche, lorsque pPrevContext a la valeur NULL.

Le membre pvCtrPara n’est pas utilisé et doit être défini sur NULL.

CERT_STORE_CTRL_CANCEL_NOTIFY
Annule la signalisation de notification du HANDLE d’événement passé dans un CERT_STORE_CTRL_NOTIFY_CHANGE ou un CERT_STORE_CTRL_RESYNC précédent. Le paramètre pvCtrlPara pointe vers l’événement HANDLE à annuler.

[in] pvCtrlPara

Si dwCtrlType est CERT_STORE_NOTIFY_CHANGE, pvCtrlPara est défini sur l’adresse d’un handle où le système signale l’événement de modification de notification lorsqu’une modification de l’état persistant du magasin est détectée. Le handle doit être initialisé avec un appel à la fonction CreateEvent. Le paramètre pvCtrlPara peut être défini sur NULL pour les magasins basés sur le Registre. Si pvCtrlPara a la valeur NULL, un événement de modification de notification interne est créé et inscrit pour être signalé. L’utilisation de l’événement de modification de notification interne autorise les opérations de resynchronisation uniquement si le magasin a été modifié.

Si dwCtrlType est CERT_STORE_CTRL_RESYNC, définissez pvCtrlPara sur l’adresse du handle d’événement à signaler lors de la modification suivante dans le magasin persistant. En règle générale, cette adresse est l’adresse du handle d’événement passé avec CERT_STORE_CTRL_NOTIFY_CHANGE lors de l’initialisation. La poignée d’événement passée est réarmée. Si pvCtrlPara est défini sur NULL, aucun événement n’est réarmé.

Si dwCtrlType CERT_STORE_CTRL_COMMIT, pvCtrlPara n’est pas utilisé et doit être défini sur NULL.

Valeur retournée

Si la fonction réussit, la fonction retourne une valeur différente de zéro.

Si la fonction échoue, elle retourne zéro. Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Si dwCtrlType est CERT_STORE_NOTIFY_CHANGE, la fonction retourne une valeur différente de zéro si un handle pour le signal d’événement a été correctement configuré. La fonction retourne zéro si le handle d’événement n’a pas été configuré.

Si dwCtrlType est CERT_STORE_CTRL_RESYNC, la fonction retourne une valeur différente de zéro si la resynchronisation a réussi. La fonction retourne zéro si la resynchronisation a échoué.

Si dwCtrlType est CERT_STORE_CTRL_COMMIT, la fonction retourne une valeur différente de zéro pour indiquer la réussite de la validation dans le stockage persistant. La fonction retourne zéro si la validation a échoué.

Certains fournisseurs peuvent ne pas prendre en charge des types de contrôle spécifiques. Dans ce cas, CertControlStore retourne zéro et GetLastError est défini sur le code ERROR_NOT_SUPPORTED.

Remarques

La resynchronisation d’un magasin peut être effectuée à tout moment. Il n’a pas besoin de suivre un événement de changement de notification signalé.

CERT_STORE_CTRL_NOTIFY_CHANGE est pris en charge sur les fournisseurs de magasins basés sur le Registre à l’aide de la fonction RegNotifyChangeKeyValue .

CertControlStore à l’aide de CERT_STORE_CTRL_NOTIFY_CHANGE est appelé une fois pour chaque descripteur d’événement à passer avec CERT_STORE_CTRL_RESYNC. Ces appels utilisant CERT_STORE_CTRL_NOTIFY_CHANGE doivent être effectués après chaque événement créé et non après qu’un événement a été signalé.

Exemples

L’exemple suivant montre comment autoriser une application à être avertie lorsqu’il existe une différence entre le contenu d’un magasin mis en cache en cours d’utilisation et le contenu de ce magasin à mesure qu’il est conservé dans le stockage. Pour obtenir l’exemple complet incluant le contexte complet de cet exemple, consultez Exemple de programme C : Définition et obtention des propriétés du magasin de certificats.


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

Configuration requise

   
Client minimal pris en charge Windows XP [applications de bureau | applications UWP]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau | applications UWP]
Plateforme cible Windows
En-tête wincrypt.h
Bibliothèque Crypt32.lib
DLL Crypt32.dll

Voir aussi

Fonctions du magasin de certificats

CreateEvent

WaitForSingleObjectEx