Função CryptContextAddRef (wincrypt.h)

Artigo
07/16/2024

Importante essa API foi preterida. O software novo e existente deve começar a usar APIs de Próxima Geração da Criptografia. Microsoft pode remover essa API em versões futuras.

A função CryptContextAddRef adiciona uma à contagem de referência de um identificador CSP ( provedor de serviços criptográficos) do HCRYPTPROV. Essa função deverá ser usada se o identificador CSP for incluído como membro de qualquer estrutura passada para outra função. A função CryptReleaseContext deve ser chamada quando o identificador CSP não for mais necessário.

Sintaxe

BOOL CryptContextAddRef(
  [in] HCRYPTPROV hProv,
  [in] DWORD      *pdwReserved,
  [in] DWORD      dwFlags
);

Parâmetros

[in] hProv

identificador de HCRYPTPROV para o qual a contagem de referência está sendo incrementada. Esse identificador já deve ter sido criado usando CryptAcquireContext.

[in] pdwReserved

Reservado para uso futuro e deve ser NULL.

[in] dwFlags

Reservado para uso futuro e deve ser zero.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será diferente de zero (TRUE).

Se a função falhar, o valor retornado será zero (FALSE). Para obter informações de erro estendidas, chame GetLastError. Um código de erro possível é o seguinte.

Código de retorno	Descrição
ERROR_INVALID_PARAMETER	Um dos parâmetros contém um valor que não é válido. Isso geralmente é um ponteiro que não é válido.

Observações

Essa função aumenta a contagem de referência em um identificador de HCRYPTPROV para que várias chamadas para CryptReleaseContext sejam necessárias para realmente liberar o identificador.

Exemplos

O exemplo a seguir incrementa a contagem de referência em um identificador CSP adquirido.

//--------------------------------------------------------------------
// hCryptProv is a HCRYPTPROV variable that was previously acquired
// by using CryptAcquireContext or CryptAcquireCertificatePrivateKey.

if(CryptContextAddRef(
       hCryptProv, 
       NULL, 
       0)) 
{
    printf("CryptContextAddRef succeeded. \n");
}
else
{
   printf("Error during CryptContextAddRef!\n");
   exit(1);
}
//--------------------------------------------------------------------
//  The reference count on hCryptProv is now greater than one. The 
//  first call to CryptReleaseContext will not release the provider 
//  handle. A second call to CryptReleaseContext would be needed to 
//  release the context.

Para obter outro exemplo que usa essa função, consulte Exemplo de Programa C: Usando CryptAcquireContext.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	wincrypt.h
biblioteca	Advapi32.lib
de DLL	Advapi32.dll

Consulte também

CryptAcquireContext

CryptReleaseContext

Funções do provedor de serviços

Compartilhar via