CryptContextAddRef function (wincrypt.h)

Article
02/22/2024

Important This API is deprecated. New and existing software should start using Cryptography Next Generation APIs. Microsoft may remove this API in future releases.

The CryptContextAddRef function adds one to the reference count of an HCRYPTPROV cryptographic service provider (CSP) handle. This function should be used if the CSP handle is included as a member of any structure passed to another function. The CryptReleaseContext function should be called when the CSP handle is no longer needed.

Syntax

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

Parameters

[in] hProv

HCRYPTPROV handle for which the reference count is being incremented. This handle must have already been created using CryptAcquireContext.

[in] pdwReserved

Reserved for future use and must be NULL.

[in] dwFlags

Reserved for future use and must be zero.

Return value

If the function succeeds, the return value is nonzero (TRUE).

If the function fails, the return value is zero (FALSE). For extended error information, call GetLastError. One possible error code is the following.

Return code	Description
ERROR_INVALID_PARAMETER	One of the parameters contains a value that is not valid. This is most often a pointer that is not valid.

Remarks

This function increases the reference count on a HCRYPTPROV handle so that multiple calls to CryptReleaseContext are required to actually release the handle.

Examples

The following example increments the reference count on an acquired CSP handle.

//--------------------------------------------------------------------
// 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.

For another example that uses this function, see Example C Program: Using CryptAcquireContext.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	wincrypt.h
Library	Advapi32.lib
DLL	Advapi32.dll

Share via