DsRestorePrepare

The DsRestorePrepare function connects to the specified directory server and prepares it for restore.

HRESULT DsRestorePrepare(
  LPCWSTR szServerName,
  ULONG rtFlag,
  PVOID pvExpiryToken,
  DWORD cbExpiryTokenSize,
  HBC* phbc
);

Parameters

szServerName

[in] Name of the server to restore. Preceding backslashes are optional. An example of a server name is \\server1.

Note  The server name cannot contain an underscore.

rtFlag

[in] Specifies the type of restoration to perform:

The value of rtFlag is 0 if no special flags are specified.

Value	Meaning
RESTORE_TYPE_CATCHUP	Default. The restored version is reconciled through the standard reconciliation logic so that the restored DIT can catch up with the rest of the enterprise.
RESTORE_TYPE_AUTHORATATIVE	Not Supported.
RESTORE_TYPE_ONLINE	Not Supported. Restoration is done when NTDS is online.

pvExpiryToken

[in] Pointer to the expiry token associated with this backup. The client receives this when the directory is backed up.

cbExpiryTokenSize

[in] Size of the expiry token.

phbc

[out] Pointer to receive the backup context handle to be passed to subsequent restore function calls.

Return Values

One of the standard HRESULT success codes; otherwise, a failure code.

Remarks

The DsRestorePrepare function requires that the caller is a member of the Administrators group on the server.

DsRestorePrepare may be used with or without a token provided. If the token is provided, it is checked for expiration, and all operations are allowed on the context returned. If the token is not provided, the context returned is restricted, and may be used only for the DsRestoreGetDatabaseLocations function. It may not be used for the DsRestoreRegister function.

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

Restoring Active Directory, Directory Backup Functions, DsRestoreGetDatabaseLocations, DsRestoreRegister, DsRestoreRegisterComplete, DsRestoreEnd