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 の値によって異なります。 現在、次のアクションが定義されています。
| 値 | 説明 |
|---|---|
|
キャッシュされたストアは再同期され、永続化されたストアと一致するように作成されます。 |
|
pvCtrlPara が指す領域にシグナルが返され、キャッシュされたストアの現在のコンテンツがストアの永続化状態と異なっていることを示します。 |
|
キャッシュされたストアに加えられた変更は、永続化されたストレージにコピーされます。 キャッシュされたストアが開かれた後、または最後のコミット以降に変更が行われなかった場合、呼び出しは無視されます。 ストア プロバイダーが変更を直ちに自動的に保持するプロバイダーである場合も、呼び出しは無視されます。 |
|
すべての列挙または検索ストア呼び出しの開始時に、ストアで変更が行われたかどうかを判断するチェックが行われます。 ストアが変更された場合は、再同期が行われます。 このチェックは、pPrevContext が NULL の場合、最初の列挙または検索呼び出しでのみ行われます。
pvCtrPara メンバーは使用されず、NULL に設定する必要があります。 |
|
前のCERT_STORE_CTRL_NOTIFY_CHANGEまたはCERT_STORE_CTRL_RESYNCで渡されたイベント HANDLE の通知通知を取り消します。 pvCtrlPara パラメーターは、取り消されるイベント HANDLE を指します。 |
[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");
}
要件
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | wincrypt.h |
| Library | Crypt32.lib |
| [DLL] | Crypt32.dll |