CertSrvBackupRead function (certbcli.h)

Article
02/22/2024

The CertSrvBackupRead function reads bytes from a Certificate Services file.

Syntax

HRESULT CERTBCLI_API CertSrvBackupRead(
  [in]  HCSBC hbc,
  [out] VOID  *pvBuffer,
  [in]  DWORD cbBuffer,
  [out] DWORD *pcbRead
);

Parameters

[in] hbc

A handle to a Certificate Services backup context.

[out] pvBuffer

Void pointer to storage which will contain bytes read from the file being backed up.

[in] cbBuffer

Size of the storage area referenced by pvBuffer.

[out] pcbRead

A pointer to a DWORD value which represents the actual number of bytes read by CertSrvBackupRead. The number of bytes read can be less than the size of the storage area allocated to pvBuffer if the end of the file has been reached.

Return value

The return value is an HRESULT. A value of S_OK indicates success.

Remarks

After opening the file for backup purposes (using CertSrvBackupOpenFile), call CertSrvBackupRead to retrieve the contents of the file, and call an application-specific routine to write the contents to a backup medium. CertSrvBackupRead and the application-specific routine can be placed in a loop until all the bytes of the file are read and backed up. When done reading the file, close it by calling CertSrvBackupClose.

Examples


#include <windows.h>
#include <stdio.h>
#include <Certbcli.h>

#define BUFFSIZE 524288

FNCERTSRVBACKUPREAD* pfnRead;
char * szBackupReadFunc = "CertSrvBackupRead";
BYTE       ReadBuff[BUFFSIZE];
DWORD      cbRead=0;
HRESULT    hr=0;

// Get the address for the desired function.    
// hInst was set by calling LoadLibrary for Certadm.dll.
pfnRead = (FNCERTSRVBACKUPREAD*)GetProcAddress(hInst,
                                          szBackupReadFunc);
if ( NULL == pfnRead )
{
    printf("Failed GetProcAddress - %s, error=%d\n",
           szBackupReadFunc,
           GetLastError() );
    exit(1); // Or other appropriate error action.
}

// Read the file.
// hCSBC represents an HCSBC used in
// an earlier call to CertSrvBackupOpenFile.
// To read the entire file, this code
// would be placed in a loop.
hr = pfnRead( hCSBC,
              &ReadBuff,
              BUFFSIZE,
              &cbRead );
if (FAILED(hr))
{
    printf("Failed pfnRead call [%x]\n", hr);
    exit(1); // Or other appropriate error action.
}

// Use the bytes read as needed. For example,
// in an application-specific routine to back
// up the file contents.
// ...

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	certbcli.h (include Certsrv.h)
Library	Certadm.lib
DLL	Certadm.dll