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.
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 |
|---|---|
|
Le magasin mis en cache est resynchronisé et fait correspondre au magasin persistant. |
|
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. |
|
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. |
|
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. |
|
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 |