Função CertControlStore (wincrypt.h)
A função CertControlStore permite que um aplicativo seja notificado quando houver uma diferença entre o conteúdo de um repositório armazenado em cache em uso e o conteúdo desse repositório, pois ele é persistido no armazenamento. Diferenças podem ocorrer à medida que outro processo faz uma alteração que afeta o repositório à medida que ele é persistente.
A função CertControlStore pode ser usada para sincronizar um repositório armazenado em cache, se necessário, e fornece um meio de confirmar as alterações feitas no repositório armazenado em cache para o armazenamento persistente.
Sintaxe
BOOL CertControlStore(
[in] HCERTSTORE hCertStore,
[in] DWORD dwFlags,
[in] DWORD dwCtrlType,
[in] void const *pvCtrlPara
);
Parâmetros
[in] hCertStore
Identificador do repositório de certificados.
[in] dwFlags
Se o parâmetro dwCtrlType for definido como CERT_STORE_CTRL_COMMIT, esse parâmetro poderá ser um dos valores a seguir.
Se dwCtrlType estiver definido como CERT_STORE_CTRL_NOTIFY_CHANGE ou CERT_STORE_CTRL_RESYNC, o parâmetro dwFlags não será usado e deverá ser definido como zero.
[in] dwCtrlType
Ação de controle a ser tomada pelo CertControlStore. As interpretações de pvCtrlPara e dwFlags dependem do valor de dwCtrlType. Atualmente, as ações a seguir são definidas.
| Valor | Significado |
|---|---|
|
O repositório armazenado em cache é ressincronizado e feito para corresponder ao repositório persistente. |
|
Um sinal é retornado no espaço apontado por pvCtrlPara para indicar que o conteúdo atual do repositório armazenado em cache difere do estado persistente do repositório. |
|
Todas as alterações feitas no repositório armazenado em cache são copiadas para o armazenamento persistente. Se nenhuma alteração tiver sido feita desde que o repositório armazenado em cache foi aberto ou desde o último commit, a chamada será ignorada. A chamada também será ignorada se o provedor de repositório for um provedor que persista automaticamente as alterações imediatamente. |
|
No início de cada enumeração ou chamada ao repositório, uma marcar é feita para determinar se uma alteração foi feita no repositório. Se o repositório tiver sido alterado, uma sincronização será feita. Esse marcar só é feito na primeira enumeração ou em chamadas de localização, quando o pPrevContext é NULL.
O membro pvCtrPara não é usado e deve ser definido como NULL. |
|
Cancela a sinalização de notificação do HANDLE do evento passado em um CERT_STORE_CTRL_NOTIFY_CHANGE ou CERT_STORE_CTRL_RESYNC anterior. O parâmetro pvCtrlPara aponta para o HANDLE do evento a ser cancelado. |
[in] pvCtrlPara
Se dwCtrlType for CERT_STORE_NOTIFY_CHANGE, pvCtrlPara será definido como o endereço de um identificador em que o sistema sinaliza o evento de alteração de notificação quando uma alteração do estado persistente do repositório é detectada. O identificador deve ser inicializado com uma chamada para a função CreateEvent. O parâmetro pvCtrlPara pode ser definido como NULL para repositórios baseados em registro. Se pvCtrlPara for NULL, um evento de alteração de notificação interna será criado e registrado para ser sinalizado. O uso do evento de alteração de notificação interna permite operações de ressincronização somente se o repositório foi alterado.
Se dwCtrlType for CERT_STORE_CTRL_RESYNC, defina pvCtrlPara como o endereço do identificador de evento a ser sinalizado na próxima alteração no repositório persistente. Normalmente, esse endereço é o endereço do identificador de evento passado com CERT_STORE_CTRL_NOTIFY_CHANGE durante a inicialização. O identificador de evento passado está armado novamente. Se pvCtrlPara estiver definido como NULL, nenhum evento será armado novamente.
Se dwCtrlType CERT_STORE_CTRL_COMMIT, pvCtrlPara não será usado e deverá ser definido como NULL.
Valor retornado
Se a função for bem-sucedida, a função retornará diferente de zero.
Se a função falhar, ela retornará zero. Para obter informações de erro estendidas, chame GetLastError.
Se dwCtrlType for CERT_STORE_NOTIFY_CHANGE, a função retornará diferente de zero se um identificador para o sinal de evento tiver sido configurado com êxito. A função retornará zero se o identificador de evento não estiver configurado.
Se dwCtrlType for CERT_STORE_CTRL_RESYNC, a função retornará diferente de zero se a ressincronização for bem-sucedida. A função retornará zero se a ressincronização falhar.
Se dwCtrlType for CERT_STORE_CTRL_COMMIT, a função retornará diferente de zero para indicar a conclusão bem-sucedida do commit para o armazenamento persistente. A função retornará zero se a confirmação falhar.
Alguns provedores podem não dar suporte a tipos de controle específicos. Nesses casos, CertControlStore retorna zero e GetLastError é definido como o código ERROR_NOT_SUPPORTED.
Comentários
A ressincronização de um repositório pode ser feita a qualquer momento. Ele não precisa seguir um evento de alteração de notificação sinalizado.
CERT_STORE_CTRL_NOTIFY_CHANGE tem suporte em provedores de repositório baseados em registro usando a função RegNotifyChangeKeyValue .
CertControlStore usando CERT_STORE_CTRL_NOTIFY_CHANGE é chamado uma vez para que cada identificador de evento seja passado com CERT_STORE_CTRL_RESYNC. Essas chamadas usando CERT_STORE_CTRL_NOTIFY_CHANGE devem ser feitas depois que cada evento é criado e não depois que um evento é sinalizado.
Exemplos
O exemplo a seguir mostra como permitir que um aplicativo seja notificado quando houver uma diferença entre o conteúdo de um repositório armazenado em cache em uso e o conteúdo desse repositório à medida que ele é persistido no armazenamento. Para obter o exemplo completo, incluindo o contexto completo para este exemplo, consulte Exemplo de Programa C: Configurando e obtendo propriedades do repositório de certificados.
//--------------------------------------------------------------------
// 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");
}
Requisitos
| Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | wincrypt.h |
| Biblioteca | Crypt32.lib |
| DLL | Crypt32.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de