DsBackupPrepare function

Article
12/11/2020

[This function is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions. Beginning with Windows Vista, use Volume Shadow Copy Service (VSS) instead.]

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.

Syntax

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

Parameters

szBackupServer [in]: Pointer to a null-terminated string that contains the name of the server to backup. Preceding backslashes are optional. The server must be the same computer that this function is called from. The server name cannot contain an underscore (_) character. An example of a server name is "\\server1".
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.
BACKUP_TYPE_FULL: Specifies a full backup. The complete directory (DIT, log files, and update 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, in bytes, of this data. The caller must 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 value

Returns S_OK if the function is successful or an error code otherwise. The following list lists other possible error codes.

ERROR_ACCESS_DENIED: The caller does not have the proper access privileges to call this function. The DsSetAuthIdentity function can be used to set the credentials to use for the backup and restore functions.
ERROR_INVALID_PARAMETER: szBackupServer or phbcBackupContext are not valid.
ERROR_NOT_ENOUGH_MEMORY: A memory allocation failure occurred.
hrCouldNotConnect: The server in szBackupServer could not be found, is not a domain controller or szBackupServer is not formatted correctly. This value is defined in ntdsbmsg.h.
hrInvalidParam: ppvExpiryToken and/or pcbExpiryTokenSize are invalid. This value is defined in Ntdsbmsg.h.
RPC_S_INVALID_BINDING: The function is called remotely or the server in szServerName is not a domain controller.

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

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Header	Ntdsbcli.h
Library	Ntdsbcli.lib
DLL	Ntdsbcli.dll
Unicode and ANSI names	DsBackupPrepareW (Unicode) and DsBackupPrepareA (ANSI)