3.1.4.1.18 ICertAdminD::BackupPrepare (Opnum 20)

  • Article

The BackupPrepare method is used to prepare the database for performing further backup operations, such as BackupEnd, BackupGetAttachmentInformation, BackupGetBackupLogs, BackupOpenFile, BackupReadFile, BackupCloseFile, and BackupTruncateLogs.

 HRESULT BackupPrepare(
   [in, string, unique] wchar_t const* pwszAuthority,
   [in] unsigned long grbitJet,
   [in] unsigned long dwBackupFlags,
   [in] WCHAR const * pwszBackupAnnotation,
   [in] DWORD dwClientIdentifier
 );

pwszAuthority: See the pwszAuthority definition in section 3.1.4.1.1.

grbitJet: An unsigned long value. This MUST be one of the following values.

Value

Meaning

0x00000000

Prepare for full backup of the CA database.

0x00000001

Prepare for an incremental backup as opposed to a full backup. This means that only the log files since the last full or incremental backup will be backed up.

dwBackupFlags: An unsigned long value. MUST be 0. MUST be ignored on receipt.

pwszBackupAnnotation: Not Used. Can be set to any arbitrary value, and MUST be ignored on receipt.

dwClientIdentifier: An unsigned long value. Not used. MUST be 0. MUST be ignored on receipt.

If Config_CA_Interface_Flags contains the value IF_NOREMOTEICERTADMINBACKUP, the server SHOULD return an error.<46>

The CA server MUST enforce the following sequencing rules:<47>

  • Before a CA backup can occur, BackupPrepare MUST be called by the client to notify the CA that a backup of the CA is about to happen:

    • If BackupGetAttachmentInformation is called without a previous call to BackupPrepare with the grbitJet parameter set to 0 (for a full backup), the CA MUST fail. The error code SHOULD be 0xc8000209.

    • If BackupPrepare is not called, the remaining database backup-related APIs (BackupGetAttachmentInformation, BackupGetBackupLogs, BackupOpenFile/BackupReadFile, BackupCloseFile, and BackupEnd) MUST fail.

  • If BackupPrepare is called again by the same client (before calling BackupEnd), the CA MUST fail.

  • If BackupReadFile is called before BackupOpenFile, the CA MUST fail.

  • If BackupCloseFile is called before BackupOpenFile, the CA MUST fail.

  • If BackupOpenFile is called again (before calling BackupCloseFile), the CA MUST fail.

  • BackupReadFile MUST be called after BackupOpenFile and before BackupCloseFile; otherwise, the CA MUST fail.

  • BackupEnd MUST be the final API for a backup session.

  • If BackupTruncateLogs is called before all the log files returned by BackupGetBackupLogs and all of the database files returned by BackupGetAttachmentInformation are backed up, the CA MUST fail.

If the preceding sequencing rules are not met, the server MUST return ERROR_UNEXPECTED_ERROR.

The CA server MUST take into account the grbitJet value to account for an incremental backup versus a full backup. If a full backup has not taken place, the CA MUST return failure if the method is invoked for an incremental backup (grbitJet parameter value 1).