CertSrvBackupOpenFileW function (certbcli.h)

Article
10/13/2021

The CertSrvBackupOpenFile function opens a file for backup.

Syntax

HRESULT CERTBCLI_API CertSrvBackupOpenFileW(
  [in]  HCSBC         hbc,
  [in]  WCHAR const   *pwszAttachmentName,
  [in]  DWORD         cbReadHintSize,
  [out] LARGE_INTEGER *pliFileSize
);

Parameters

[in] hbc

A handle to a Certificate Services backup context.

[in] pwszAttachmentName

File name to open for backup purposes. This file name would be parsed from a list produced by means of CertSrvBackupGetBackupLogs or CertSrvBackupGetDatabaseNames. Note that the names returned by CertSrvBackupGetBackupLogs and CertSrvBackupGetDatabaseNames must have the single-WCHAR CSBFT_* prefix stripped before CertSrvBackupOpenFile is called.

[in] cbReadHintSize

Number of bytes used as a hint when the file is read by CertSrvBackupRead. The cbReadHintSize parameter passed to the first CertSrvBackupOpenFile call for the backup context is used to size the read buffer. Pass zero for this parameter, and the buffer will be sized at a reasonably efficient size chosen by CertSrvBackupOpenFile. If insufficient memory is available, the buffer size will be reduced until memory allocation succeeds or until the buffer size reaches its minimum possible value. Pass a nonzero size to cause CertSrvBackupOpenFile to size the buffer to a power of two near the value of cbReadHintSize. The implementation will choose only powers of two between 64 KB and 4 MB.

[out] pliFileSize

A pointer to a LARGE_INTEGER value that represents the number of bytes in the file.

Return value

If the function succeeds, the function returns S_OK.

If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see Common HRESULT Values.

Remarks

Use this function to open a file for backup purposes. When you have finished using the file, close the file by calling the CertSrvBackupClose function.

The name of this function in Certadm.dll is CertSrvBackupOpenFileW. You must use this form of the name when calling GetProcAddress. Also, this function is defined as type FNCERTSRVBACKUPOPENFILEW in Certbcli.h.

Examples

FNCERTSRVBACKUPOPENFILEW* pfnOpenFile;
char * szBackupOpenFunc = "CertSrvBackupOpenFileW";
LARGE_INTEGER liFileSize;
HRESULT       hr=0;

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

// Open the file.
// hCSBC was set by an earlier call to CertSrvBackupPrepare.
// pwszFile specifies the name of a file.
// This name could have resulted from parsing the
// output from CertSrvBackupGetDatabaseNames, and so on.
hr = pfnOpenFile(hCSBC,
                pwszFile,
                0,
                &liFileSize);
if (FAILED(hr))
{
    printf("Failed pfnOpenFile call [%x] %ws\n",
           hr,
           pwszFile);
           exit(1); // Or other appropriate error action.
}

// Use the opened file as needed.
// When you have finished using the file, call CertSrvBackupClose.
// ...

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