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