DsRestoreRegister function

[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 DsRestoreRegister function registers a restore operation.This function interlocks all subsequent restore operations and prevents the restore target from starting until the DsRestoreRegisterComplete function is called.

Syntax

HRESULT DsRestoreRegister(
  _In_ HBC        hbc,
  _In_ LPCTSTR    szCheckPointFilePath,
  _In_ LPCTSTR    szLogPath,
  _In_ EDB_RSTMAP rgrstmap[],
  _In_ LONG       crstmap,
  _In_ LPCTSTR    szBackupLogPath,
  _In_ ULONG      genLow,
  _In_ ULONG      genHigh
);

Parameters

hbc [in]

Contains the restoration context handle obtained with the DsRestorePrepare function.

szCheckPointFilePath [in]

Pointer to a null-terminated string that contains the path to the checkpoint file. This path is provided by the DsRestoreGetDatabaseLocations function and has a BFT value of BFT_CHECKPOINT_DIR. Typically this is the same as the system database path. This path is required for proper backup restore function. This parameter cannot be NULL. Passing NULL in this parameter will cause an error during the restore process.

szLogPath [in]

Pointer to a null-terminated string that contains the path where the log files will be restored. This path is provided by the DsRestoreGetDatabaseLocations function and has a BFT value of BFT_LOG_DIR. If the path points to an empty directory, new log files are created there. This parameter cannot be NULL.

rgrstmap [in]

An array of EDB_RSTMAP structures that contains the old and new paths for each database. There is one structure for each database. For the directory, there is a structure for the system database and another structure for the directory database. The order of the elements in the array does not matter. The crstmap parameter contains the number of elements in the array.

crstmap [in]

Contains the number of elements in the rgrstmap array.

szBackupLogPath [in]

Pointer to a null-terminated string that contains the path where the backed up log files currently reside. This parameter cannot be NULL.

genLow [in]

Contains the lowest log number to restore in this restore session. This is a hexadecimal number in the range from 0x00000 to 0xFFFFF.

genHigh [in]

Contains the highest log number to restore in this restore session. This is a hexadecimal number in the range from 0x00000 to 0xFFFFF.

Return value

Returns S_OK if the function is successful or a Win32 or RPC error code otherwise. The following list lists 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

One or more parameters are invalid.

hrMissingExpiryToken

The expiry token supplied to DsRestorePrepare was invalid. This value is defined in Ntdsbmsg.h.

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
DsRestoreRegisterW (Unicode) and DsRestoreRegisterA (ANSI)

See also

DsRestoreRegisterComplete

DsRestorePrepare

DsRestoreGetDatabaseLocations

DsRestoreEnd

EDB_RSTMAP

Restoring Active Directory

Directory Backup Functions