Freigeben über


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.

Wert Bedeutung
CERT_STORE_CTRL_COMMIT_FORCE_FLAG
Erzwingt, dass der Inhalt des Cachespeichers in einen dauerhaften Speicher kopiert wird, auch wenn der Cache nicht geändert wurde.
CERT_STORE_CTRL_COMMIT_CLEAR_FLAG
Verhindert das Kopieren des Inhalts des Cachespeichers in einen dauerhaften Speicher, auch wenn der Speicher geschlossen wird.
CERT_STORE_CTRL_INHIBIT_DUPLICATE_HANDLE_FLAG
Hemmt ein doppeltes Handle des Ereignisses HANDLE. Wenn dieses Flag festgelegt ist, muss CertControlStore mit CERT_STORE_CTRL_CANCEL_NOTIFY übergeben für dieses Ereignis handle aufgerufen werden, bevor das hCertStore-Handle geschlossen wird.
 

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
CERT_STORE_CTRL_RESYNC
Der zwischengespeicherte Speicher wird neu synchronisiert und so erstellt, dass er dem persistenten Speicher entspricht.
CERT_STORE_CTRL_NOTIFY_CHANGE
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.
CERT_STORE_CTRL_COMMIT
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.
CERT_STORE_CTRL_AUTO_RESYNC
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.

CERT_STORE_CTRL_CANCEL_NOTIFY
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

Zertifikatspeicherfunktionen

CreateEvent

WaitForSingleObjectEx