Função CertAddStoreToCollection (wincrypt.h)

A função CertAddStoreToCollection adiciona um repositório de certificados irmão a um repositório de certificados de coleção. Quando um repositório de certificados é adicionado a um repositório de coleções, todos os certificados, as CRLs ( listas de revogação de certificados ) e as CTLs ( listas de confiança de certificado ) no repositório que foi adicionado ao repositório de coleções podem ser recuperados usando chamadas de função localizar ou enumerar que usam o repositório de coleções.

Sintaxe

BOOL CertAddStoreToCollection(
  [in]           HCERTSTORE hCollectionStore,
  [in, optional] HCERTSTORE hSiblingStore,
  [in]           DWORD      dwUpdateFlags,
  [in]           DWORD      dwPriority
);

Parâmetros

[in] hCollectionStore

Identificador de um repositório de certificados.

[in, optional] hSiblingStore

Identificador de um repositório irmão a ser adicionado ao repositório de coleções. Para obter mais informações, consulte Comentários.

[in] dwUpdateFlags

Indica se certificados, CRLs e CTLs podem ser adicionados ao novo membro do repositório irmão do repositório de coleções. Para habilitar a adição, defina dwUpdateFlag como CERT_PHYSICAL_STORE_ADD_ENABLE_FLAG. Para desabilitar adições, defina dwUpdateFlag como zero.

[in] dwPriority

Define um nível de prioridade do novo repositório na coleção, sendo zero a prioridade mais baixa. Se zero for passado para esse parâmetro, o repositório especificado será acrescentado como o último repositório na coleção. Os níveis de prioridade dos repositórios em uma coleção determinam a ordem na qual os repositórios são enumerados e a ordem de pesquisa dos repositórios ao tentar recuperar um certificado, CRL ou CTL. Os níveis de prioridade também determinam para qual repositório de uma coleção um novo certificado, CRL ou CTL é adicionado. Para obter mais informações, consulte Comentários.

Retornar valor

Se a função for bem-sucedida, a função retornará diferente de zero e um novo repositório será adicionado à coleção de repositórios.

Se a função falhar, ela retornará zero e o repositório não foi adicionado.

Comentários

Um repositório de coleção tem o mesmo identificador HCERTSTORE que um único repositório; assim, quase todas as funções que se aplicam a qualquer repositório de certificados também se aplicam a qualquer repositório de coleção. Os processos de enumeração e pesquisa abrangem todos os repositórios em um repositório de coleções; no entanto, funções como CertAddCertificateLinkToStore que adicionam links a repositórios não podem ser usadas com repositórios de coleção.

Quando um certificado, CRL ou CTL é adicionado a um repositório de coleções, a lista de repositórios irmãos na coleção é pesquisada com prioridade para localizar o primeiro repositório que permite adicionar. A adição será habilitada se CERT_PHYSICAL_STORE_ADD_ENABLE_FLAG tiver sido definido na chamada CertAddStoreToCollection . Com qualquer função que adicione elementos a um repositório, se um repositório que permite adicionar não retornar êxito, a função de adição continuará no próximo repositório sem fornecer notificação.

Quando um repositório de coleções e suas lojas irmãos são fechados com a CertCloseStore usando CERT_CLOSE_STORE_FORCE_FLAG, o repositório de coleções deve ser fechado antes de suas lojas irmãos. Se CERT_CLOSE_STORE_FORCE_FLAG não for usado, os repositórios poderão ser fechados em qualquer ordem.

Exemplos

O exemplo a seguir mostra a adição de um repositório de certificados irmão a um repositório de certificados de coleção. Para obter um exemplo completo, incluindo o contexto completo para este exemplo, consulte Exemplo de Programa C: Coleta e Operações de Repositório de Certificados Irmãos.

//-------------------------------------------------------------------
// Declare and initialize variables.

HCERTSTORE  hCollectionStore = NULL;     // The collection store 
                                         // handle
HCERTSTORE  hMemoryStore = NULL;         // A memory store handle
LPCSTR pszFileName = "TestStor.sto";     // Output file name
LPWSTR pswzFirstCert = L"Full Test Cert";// Subject of the first
                                         // certificate
LPWSTR pswzSecondCert = L"Microsoft";    // Subject of the second 
                                         // certificate
//-------------------------------------------------------------------
// Open a collection certificate store.

if(hCollectionStore = CertOpenStore(
    CERT_STORE_PROV_COLLECTION, // A collection store
    0,                          // Encoding type; not used with a
                                // collection store
    NULL,                       // Use the default provider
    0,                          // No flags
    NULL))                      // Not needed

{
    printf("The collection store was opened. \n");
}
else
{
    printf( "There was an error while opening the "
        "collection store! \n");
    exit(1);
}
//-------------------------------------------------------------------
// Open a new certificate store in memory.

if(hMemoryStore = CertOpenStore(
    CERT_STORE_PROV_MEMORY,    // A memory store
    0,                         // Encoding type; not used with a
                               // memory store
    NULL,                      // Use the default provider
    0,                         // No flags
    NULL))                     // Not needed
{
    printf("The memory store was opened. \n");
}
else
{
    printf( "There was an error while opening the memory store! \n");
    exit(1);
}
//-------------------------------------------------------------------
// Add the memory store as a sibling to the collection store. 
// All certificates in the memory store and any new certificate
// added to the memory store will also be available in the 
// collection
// store.

if(CertAddStoreToCollection(
    hCollectionStore,
    hMemoryStore,
    CERT_PHYSICAL_STORE_ADD_ENABLE_FLAG,  // New certificates can be
                                          // added to the sibling
                                          // store.
    1))                                   // The sibling store's 
                                          // priority.
                                          // Because this is the 
                                          // store with the highest
                                          // priority, certificates
                                          // added to the collection
                                          // store will actually be
                                          // stored in this store.
{
    printf("The memory store was added to the collection store.\n");
}
else
{
    printf("The memory store was not added to the "
        "collection store.\n");
    exit(1);
}


//-------------------------------------------------------------------
// The store handles must be closed.

if(CertCloseStore(hCollectionStore,
                  0))
{
    printf("The collection store was closed. \n");
}
else
{
    printf("There was an error while closing the "
        "collection store! \n");
}

if(CertCloseStore(hMemoryStore, 0))
{
    printf("The memory store was closed. \n");
}
else
{
    printf("There was an error while closing the memory store! \n");
}

Requisitos

Confira também

CertRemoveStoreFromCollection

Funções de repositório de certificados