DsBackupPrepare

The DsBackupPrepare function prepares the directory on the specified server for the online backup and returns a backup context handle, which should be used in the subsequent calls to other backup functions.

HRESULT DsBackupPrepare(
  LPCWSTR szBackupServer,
  ULONG grbit,
  ULONG btFlag,
  PVOID *ppvExpiryToken,
  LPDWORD pcbExpiryTokenSize,
  HBC *phbc
);

Parameters

szBackupServer

[in] Specifies the name of the server to back up. Preceding backslashes are optional. An example of a server name is \\server1. The server name cannot contain any underscore.

grbit

[in] Determines whether to back up all log files during an incremental backup or the uncommitted log files during a full backup.

grbit	Description
1	Back up the log files.
0	Do not backup the log files.

btFlag

[in] Specifies the type of backup operations as listed in the table below. Use this parameter to test whether this type of backup can be performed at this time. If this function fails with a certain btFlag, this type of backup is not allowed.

btFlag	Description
BACKUP_TYPE_FULL	Full backup. Requesting backup of the complete directory (DIT, log files, and patch files). All data is backed up and transaction log files are truncated.
BACKUP_TYPE_INCREMENTAL	Not supported. This is an incremental backup. It only backs up changes that happened since the last backup.
BACKUP_TYPE_LOGS_ONLY	Back up only database logs, but not the database. This is normally used when performing a differential or incremental backup.

ppvExpiryToken

[out] Pointer to an expiry token associated with this backup. The client should save this token and send it back through DsRestorePrepare when attempting to restore data. When this token is no longer needed, the caller should free the allocated memory using DsBackupFree.

pcbExpiryTokenSize

[out] Pointer to the size of the expiry token as returned in the ppvExpiryToken parameter above.

phbc

[out] Specifies the client context handle for the backup.

Remarks

The DsBackupPrepare function requires that the caller be a member of the Backup Operators group on the server.

DsBackupPrepare returns an expiration token. It is an opaque cookie to the client. It should be supplied to DsRestorePrepare.

The token contains the backup date and time and the tombstone lifetime of the enterprise at the time the backup was created. At restore time, if the token is expired, the restore is denied. The token expires when time elapsed since the backup exceeds the tombstone lifetime. Obviously backups will be taken at a more frequent interval than the tombstone lifetime.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Ntdsbcli.h.
  Library: Included as a resource in Ntdsbcli.dll.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

Backing Up and Restoring Active Directory, Directory Backup Functions, DsBackupEnd, DsBackupFree, DsRestorePrepare