Directory Services

DsBackupPrepare

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

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

Parameters

szBackupServer
[in] Pointer to a null-terminated string that contains the name of the server to back up. Preceding backslashes are optional. For example, "\\server1". The server name cannot contain an underscore (_).
grbit
[in] Determines if the log files will be backed up. This value should always be 0 because incremental backups are not supported.
btBackupType
[in] Specifies the type of backup. This can be one of the following values.
Value Meaning
BACKUP_TYPE_FULL Specifies a full backup. The complete directory (DIT, log files, and patch files) are backed up. All data is backed up and transaction log files are truncated. Only full backups are supported.
BACKUP_TYPE_LOGS_ONLY This value is not supported. Specifies that only the database logs, and not the database itself, will be backed up. This is normally used when performing a differential or incremental backup.
BACKUP_TYPE_INCREMENTAL This value is not supported. DsBackupPrepare returns ERROR_INVALID_PARAMETER.
ppvExpiryToken
[out] Pointer to a PVOID value that receives a pointer to an expiry token associated with this backup. pcbExpiryTokenSize receives the size of this data, in bytes. The caller should save the contents of this token with the backup because the token must be passed to DsRestorePrepare when attempting to restore data. After the token has been stored and is no longer required, the caller should free the allocated memory using DsBackupFree.
pcbExpiryTokenSize
[out] Pointer to a DWORD value that receives the size, in bytes, of the token in ppvExpiryToken.
phbc
[out] Pointer to an HBC value that receives the handle for the backup. This handle is used when calling other Directory Service backup functions, such as DsBackupOpenFile and DsBackupEnd.

Return Values

Returns a standard HRESULT value, a Win32 error value, an RPC error value or one of the following.
Return Code Description
ERROR_SUCCESS The function was successful.
ERROR_INVALID_PARAMETER szBackupServer and/or phbcBackupContext are invalid.
ERROR_NOT_ENOUGH_MEMORY A memory allocation failure occurred.
hrInvalidParam ppvExpiryToken and/or pcbExpiryTokenSize are invalid. This value is defined in Ntdsbmsg.h.

Remarks

This function requires that the caller has the SE_BACKUP_NAME privilege. The DsSetAuthIdentity function can be used to change the security context under which this function is called.

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Unicode: Implemented as Unicode and ANSI versions.
Header: Declared in Ntdsbcli.h.
Library: Use Ntdsbcli.lib.

See Also

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