Funzione CertControlStore (wincrypt.h)
La funzione CertControlStore consente a un'applicazione di ricevere una notifica quando esiste una differenza tra il contenuto di un archivio memorizzato nella cache in uso e il contenuto di tale archivio perché è persistente nell'archiviazione. Le differenze possono verificarsi quando un altro processo apporta una modifica che influisce sull'archivio perché è persistente.
La funzione CertControlStore può essere usata per sincronizzare un archivio memorizzato nella cache, se necessario, e fornisce un modo per eseguire il commit delle modifiche apportate nell'archivio memorizzato nella cache in una risorsa di archiviazione persistente.
Sintassi
BOOL CertControlStore(
[in] HCERTSTORE hCertStore,
[in] DWORD dwFlags,
[in] DWORD dwCtrlType,
[in] void const *pvCtrlPara
);
Parametri
[in] hCertStore
Handle dell'archivio certificati.
[in] dwFlags
Se il parametro dwCtrlType è impostato su CERT_STORE_CTRL_COMMIT, questo parametro può essere uno dei valori seguenti.
Se dwCtrlType è impostato su CERT_STORE_CTRL_NOTIFY_CHANGE o CERT_STORE_CTRL_RESYNC, il parametro dwFlags non viene usato e deve essere impostato su zero.
[in] dwCtrlType
Azione di controllo da eseguire da CertControlStore. Le interpretazioni di pvCtrlPara e dwFlags dipendono dal valore di dwCtrlType. Attualmente vengono definite le azioni seguenti.
| Valore | Significato |
|---|---|
|
L'archivio memorizzato nella cache viene risincronizzato e creato in modo che corrisponda all'archivio persistente. |
|
Viene restituito un segnale nello spazio a cui punta pvCtrlPara per indicare che il contenuto corrente dell'archivio memorizzato nella cache differisce dallo stato persistente dell'archivio. |
|
Tutte le modifiche apportate all'archivio memorizzato nella cache vengono copiate nella risorsa di archiviazione persistente. Se non sono state apportate modifiche dall'apertura dell'archivio memorizzato nella cache o dall'ultimo commit, la chiamata viene ignorata. La chiamata viene ignorata anche se il provider di archiviazione è un provider che mantiene automaticamente le modifiche immediatamente. |
|
All'inizio di ogni enumerazione o chiamata all'archivio di ricerca, viene effettuato un controllo per determinare se è stata apportata una modifica nell'archivio. Se l'archivio è stato modificato, viene eseguita una sincronizzazione di nuovo. Questo controllo viene eseguito solo alla prima enumerazione o alle chiamate di ricerca, quando pPrevContext è NULL.
Il membro pvCtrPara non viene utilizzato e deve essere impostato su NULL. |
|
Annulla la segnalazione di notifica dell'handle dell'evento passato in un CERT_STORE_CTRL_NOTIFY_CHANGE o CERT_STORE_CTRL_RESYNC precedente. Il parametro pvCtrlPara punta all'handle dell'evento da annullare. |
[in] pvCtrlPara
Se dwCtrlType è CERT_STORE_NOTIFY_CHANGE, pvCtrlPara viene impostato sull'indirizzo di un handle in cui il sistema segnala l'evento di modifica della notifica quando viene rilevata una modifica dallo stato persistente dell'archivio. L'handle deve essere inizializzato con una chiamata alla funzione CreateEvent. Il parametro pvCtrlPara può essere impostato su NULL per gli archivi basati sul Registro di sistema. Se pvCtrlPara è NULL, viene creato e registrato un evento di modifica della notifica interna da segnalare. L'uso dell'evento di modifica della notifica interna consente operazioni di risincronizzazione solo se l'archivio è stato modificato.
Se dwCtrlType è CERT_STORE_CTRL_RESYNC, impostare pvCtrlPara sull'indirizzo dell'handle di eventi da segnalare alla modifica successiva nell'archivio persistente. In genere, questo indirizzo è l'indirizzo dell'handle di eventi passato con CERT_STORE_CTRL_NOTIFY_CHANGE durante l'inizializzazione. L'handle di evento passato viene ridiscato. Se pvCtrlPara è impostato su NULL, non viene ridiscato alcun evento.
Se dwCtrlType CERT_STORE_CTRL_COMMIT, pvCtrlPara non viene usato e deve essere impostato su NULL.
Valore restituito
Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero.
Se la funzione ha esito negativo, restituisce zero. Per informazioni sugli errori estesi, chiamare GetLastError.
Se dwCtrlType è CERT_STORE_NOTIFY_CHANGE, la funzione restituisce un valore diverso da zero se è stato configurato correttamente un handle per il segnale di evento. La funzione restituisce zero se l'handle eventi non è stato configurato.
Se dwCtrlType è CERT_STORE_CTRL_RESYNC, la funzione restituisce un valore diverso da zero se la risincronizzazione ha avuto esito positivo. La funzione restituisce zero se la risincronizzazione non è riuscita.
Se dwCtrlType è CERT_STORE_CTRL_COMMIT, la funzione restituisce un valore diverso da zero per indicare il completamento corretto del commit nell'archiviazione persistente. La funzione restituisce zero se il commit non è riuscito.
Alcuni provider potrebbero non supportare tipi di controllo specifici. In questi casi , CertControlStore restituisce zero e GetLastError è impostato sul codice ERROR_NOT_SUPPORTED.
Commenti
La risincronizzazione di un archivio può essere eseguita in qualsiasi momento. Non è necessario seguire un evento di modifica della notifica segnalato.
CERT_STORE_CTRL_NOTIFY_CHANGE è supportato nei provider di archivi basati sul Registro di sistema usando la funzione RegNotifyChangeKeyValue .
CertControlStore che usa CERT_STORE_CTRL_NOTIFY_CHANGE viene chiamato una volta per ogni handle di eventi da passare con CERT_STORE_CTRL_RESYNC. Queste chiamate che usano CERT_STORE_CTRL_NOTIFY_CHANGE devono essere effettuate dopo la creazione di ogni evento e non dopo la segnalazione di un evento.
Esempio
Nell'esempio seguente viene illustrato come consentire a un'applicazione di ricevere una notifica quando si verifica una differenza tra il contenuto di un archivio memorizzato nella cache in uso e il contenuto di tale archivio man mano che viene salvato in modo permanente nell'archiviazione. Per l'esempio completo, incluso il contesto completo per questo esempio, vedere Esempio di programma C: impostazione e recupero delle proprietà dell'archivio certificati.
//--------------------------------------------------------------------
// 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");
}
Requisiti
| Client minimo supportato | Windows XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | wincrypt.h |
| Libreria | Crypt32.lib |
| DLL | Crypt32.dll |