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.

[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

Weitere Informationen

Zertifikatspeicherfunktionen

CreateEvent

WaitForSingleObjectEx