CertControlStore 関数 (wincrypt.h)

CertControlStore 関数を使用すると、使用中のキャッシュされたストアの内容と、ストレージに永続化されるときにそのストアの内容に違いがある場合に、アプリケーションに通知を受け取ることができます。 異なる点は、保存時にストアに影響を与える変更が別の プロセス によって行われる場合に発生する可能性があります。

CertControlStore 関数は、必要に応じてキャッシュされたストアを同期するために使用でき、キャッシュされたストアで行われた変更を永続化されたストレージにコミットする手段を提供します。

構文

BOOL CertControlStore(
  [in] HCERTSTORE hCertStore,
  [in] DWORD      dwFlags,
  [in] DWORD      dwCtrlType,
  [in] void const *pvCtrlPara
);

パラメーター

[in] hCertStore

証明書ストアのハンドル。

[in] dwFlags

dwCtrlType パラメーターが CERT_STORE_CTRL_COMMIT に設定されている場合、このパラメーターには次のいずれかの値を指定できます。

dwCtrlType が CERT_STORE_CTRL_NOTIFY_CHANGE または CERT_STORE_CTRL_RESYNC に設定されている場合、dwFlags パラメーターは使用されず、0 に設定する必要があります。

[in] dwCtrlType

CertControlStore によって実行される制御アクション。 pvCtrlPara と dwFlags の解釈は、dwCtrlType の値によって異なります。 現在、次のアクションが定義されています。

[in] pvCtrlPara

dwCtrlType がCERT_STORE_NOTIFY_CHANGEの場合、pvCtrlPara はハンドルのアドレスに設定され、ストアの永続化された状態からの変更が検出されたときにシステムによって通知変更イベントが通知されます。 ハンドルは、関数 CreateEvent の呼び出しで初期化する必要があります。 レジストリ ベースのストアでは、 pvCtrlPara パラメーターを NULL に設定できます。 pvCtrlPara が NULL の場合は、内部通知変更イベントが作成され、シグナルが送信されるように登録されます。 内部通知変更イベントを使用すると、ストアが変更された場合にのみ再同期操作が許可されます。

dwCtrlType がCERT_STORE_CTRL_RESYNC場合は、pvCtrlPara を、永続化されたストアの次の変更時に通知されるイベント ハンドルのアドレスに設定します。 通常、このアドレスは、初期化中にCERT_STORE_CTRL_NOTIFY_CHANGEと共に渡されるイベント ハンドルのアドレスです。 渡されたイベント ハンドルがリアームされます。 pvCtrlPara がNULL に設定されている場合、イベントはリアームされません。

dwCtrlType がCERT_STORE_CTRL_COMMIT場合、pvCtrlPara は使用されず、NULL に設定する必要があります。

戻り値

関数が成功した場合、関数は 0 以外の値を返します。

関数が失敗すると、0 が返されます。 拡張エラー情報については、 GetLastError を呼び出します。

dwCtrlType がCERT_STORE_NOTIFY_CHANGEの場合、イベントシグナルのハンドルが正常に設定された場合、関数は 0 以外の値を返します。 イベント ハンドルが設定されていない場合、関数は 0 を返します。

dwCtrlType がCERT_STORE_CTRL_RESYNCの場合、再同期が成功した場合、関数は 0 以外の値を返します。 再同期に失敗した場合、関数は 0 を返します。

dwCtrlType がCERT_STORE_CTRL_COMMITの場合、永続化されたストレージへのコミットが正常に完了したことを示す 0 以外の値が返されます。 コミットに失敗した場合、関数は 0 を返します。

プロバイダーによっては、特定のコントロールの種類がサポートされていない場合があります。 このような場合、 CertControlStore は 0 を返し、 GetLastError はERROR_NOT_SUPPORTED コードに設定されます。

解説

ストアの再同期は、いつでも行うことができます。 シグナル通知変更イベントに従う必要はありません。

CERT_STORE_CTRL_NOTIFY_CHANGEは、レジストリ ベースのストア プロバイダーで RegNotifyChangeKeyValue 関数を使用してサポートされます。

CERT_STORE_CTRL_NOTIFY_CHANGEを使用する CertControlStore は、CERT_STORE_CTRL_RESYNCで渡されるイベント ハンドルごとに 1 回呼び出されます。 CERT_STORE_CTRL_NOTIFY_CHANGEを使用したこれらの呼び出しは、イベントが通知された後ではなく、各イベントが作成された後に行う必要があります。

例

次の例は、使用中のキャッシュされたストアの内容と、ストレージに永続化されるときにそのストアの内容に違いがある場合に、アプリケーションに通知を受け取ることを許可する方法を示しています。 この例の完全なコンテキストを含む完全な例については、「 サンプル C プログラム: 証明書ストアのプロパティの設定と取得」を参照してください。

//--------------------------------------------------------------------
// 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");
}

要件

関連項目

証明書ストア関数

CreateEvent

WaitForSingleObjectEx