CertControlStore-Funktion (wincrypt.h)
Mit der CertControlStore-Funktion kann eine Anwendung benachrichtigt werden, wenn ein Unterschied zwischen dem Inhalt eines zwischengespeicherten Speichers und dem Inhalt dieses Speichers besteht, während er im Speicher gespeichert wird. Unterschiede können auftreten, wenn ein anderer Prozess eine Änderung vornimmt, die sich auf den Speicher auswirkt, während er beibehalten wird.
Die CertControlStore-Funktion kann verwendet werden, um einen zwischengespeicherten Speicher bei Bedarf zu synchronisieren, und bietet eine Möglichkeit zum Committen von Änderungen, die im zwischengespeicherten Speicher vorgenommen wurden.
Syntax
BOOL CertControlStore(
[in] HCERTSTORE hCertStore,
[in] DWORD dwFlags,
[in] DWORD dwCtrlType,
[in] void const *pvCtrlPara
);
Parameter
[in] hCertStore
Handle des Zertifikatspeichers.
[in] dwFlags
Wenn der dwCtrlType-Parameter auf CERT_STORE_CTRL_COMMIT festgelegt ist, kann dieser Parameter einer der folgenden Werte sein.
Wenn dwCtrlType auf CERT_STORE_CTRL_NOTIFY_CHANGE oder CERT_STORE_CTRL_RESYNC festgelegt ist, wird der dwFlags-Parameter nicht verwendet und muss auf null festgelegt werden.
[in] dwCtrlType
Steuerungsaktion, die von CertControlStore ausgeführt werden soll. Die Interpretationen von pvCtrlPara und dwFlags hängen vom Wert von dwCtrlType ab. Derzeit sind die folgenden Aktionen definiert.
| Wert | Bedeutung |
|---|---|
|
Der zwischengespeicherte Speicher wird neu synchronisiert und so erstellt, dass er dem persistenten Speicher entspricht. |
|
Im Bereich, auf den pvCtrlPara verweist, wird ein Signal zurückgegeben, um anzugeben, dass sich der aktuelle Inhalt des zwischengespeicherten Speichers vom persistenten Zustand des Speichers unterscheidet. |
|
Alle Änderungen, die am zwischengespeicherten Speicher vorgenommen werden, werden in den dauerhaften Speicher kopiert. Wenn seit dem Öffnen des zwischengespeicherten Speichers oder seit dem letzten Commit keine Änderungen vorgenommen wurden, wird der Aufruf ignoriert. Der Aufruf wird auch ignoriert, wenn der Speicheranbieter ein Anbieter ist, der Änderungen automatisch sofort speichert. |
|
Zu Beginn jeder Enumeration oder jedes Suchspeicheraufrufs wird überprüft, ob eine Änderung im Speicher vorgenommen wurde. Wenn sich der Speicher geändert hat, wird eine erneute Synchronisierung durchgeführt. Diese Überprüfung erfolgt nur bei der ersten Enumeration oder bei Suchaufrufen, wenn pPrevContextNULL ist.
Der pvCtrPara-Member wird nicht verwendet und muss auf NULL festgelegt werden. |
|
Bricht die Benachrichtigung über das Ereignis HANDLE ab, das in einem vorherigen CERT_STORE_CTRL_NOTIFY_CHANGE oder CERT_STORE_CTRL_RESYNC übergeben wurde. Der parameter pvCtrlPara verweist auf das ereignis HANDLE, das abgebrochen werden soll. |
[in] pvCtrlPara
Wenn dwCtrlType CERT_STORE_NOTIFY_CHANGE ist, wird pvCtrlPara auf die Adresse eines Handles festgelegt, bei dem das System das Benachrichtigungsänderungsereignis signalisiert, wenn eine Änderung aus dem persistenten Zustand des Speichers erkannt wird. Das Handle muss mit einem Aufruf der Funktion CreateEvent initialisiert werden. Der Parameter pvCtrlPara kann für registrierungsbasierte Speicher auf NULL festgelegt werden. Wenn pvCtrlParaNULL ist, wird ein internes Benachrichtigungsänderungsereignis erstellt und registriert, um signalisiert zu werden. Die Verwendung des internen Änderungsereignisses für Benachrichtigungen ermöglicht nur dann Erneutsynchronisierungsvorgänge, wenn der Speicher geändert wurde.
Wenn dwCtrlType CERT_STORE_CTRL_RESYNC ist, legen Sie pvCtrlPara auf die Adresse des Ereignishandles fest, das bei der nächsten Änderung im persistenten Speicher signalisiert wird. In der Regel ist diese Adresse die Adresse des Ereignishandles, das während der Initialisierung mit CERT_STORE_CTRL_NOTIFY_CHANGE übergeben wird. Das übergebene Ereignishandle wird umstrukturiert. Wenn pvCtrlPara auf NULL festgelegt ist, wird kein Ereignis umstrukturiert.
Wenn dwCtrlType CERT_STORE_CTRL_COMMIT, wird pvCtrlPara nicht verwendet und muss auf NULL festgelegt werden.
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt die Funktion ungleich null zurück.
Wenn die Funktion fehlschlägt, wird null zurückgegeben. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.
Wenn dwCtrlType CERT_STORE_NOTIFY_CHANGE ist, gibt die Funktion ungleich null zurück, wenn ein Handle für das Ereignissignal erfolgreich eingerichtet wurde. Die Funktion gibt null zurück, wenn das Ereignishandle nicht eingerichtet wurde.
Wenn dwCtrlType CERT_STORE_CTRL_RESYNC ist, gibt die Funktion ungleich null zurück, wenn die Erneute Synchronisierung erfolgreich war. Die Funktion gibt null zurück, wenn bei der Neusynchronisierung ein Fehler aufgetreten ist.
Wenn dwCtrlType CERT_STORE_CTRL_COMMIT ist, gibt die Funktion ungleich null zurück, um den erfolgreichen Abschluss des Commits für dauerhaften Speicher anzugeben. Die Funktion gibt null zurück, wenn beim Commit ein Fehler aufgetreten ist.
Einige Anbieter unterstützen möglicherweise keine bestimmten Steuerelementtypen. In diesen Fällen gibt CertControlStore null zurück, und GetLastError ist auf den ERROR_NOT_SUPPORTED Code festgelegt.
Hinweise
Die Neusynchronisierung eines Speichers kann jederzeit durchgeführt werden. Es muss kein signalisiertes Benachrichtigungsänderungsereignis folgen.
CERT_STORE_CTRL_NOTIFY_CHANGE wird von registrierungsbasierten Speicheranbietern mithilfe der RegNotifyChangeKeyValue-Funktion unterstützt.
CertControlStore mit CERT_STORE_CTRL_NOTIFY_CHANGE wird einmal für jedes Ereignishandle aufgerufen, das mit CERT_STORE_CTRL_RESYNC übergeben werden soll. Diese Aufrufe mit CERT_STORE_CTRL_NOTIFY_CHANGE müssen nach der Erstellung jedes Ereignisses und nicht nach dem Signalisieren eines Ereignisses erfolgen.
Beispiele
Das folgende Beispiel zeigt, dass eine Anwendung benachrichtigt werden kann, wenn ein Unterschied zwischen dem Inhalt eines zwischengespeicherten Speichers und den Inhalten dieses Speichers besteht, während er im Speicher gespeichert wird. Das vollständige Beispiel einschließlich des vollständigen Kontexts für dieses Beispiel finden Sie unter Beispiel-C-Programm: Festlegen und Abrufen von Zertifikatspeichereigenschaften.
//--------------------------------------------------------------------
// 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");
}
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | wincrypt.h |
| Bibliothek | Crypt32.lib |
| DLL | Crypt32.dll |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für