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.

[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

Confira também

Funções de repositório de certificados

CreateEvent

WaitForSingleObjectEx