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:

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.

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

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 only be used for the GetDatabaseLocations API. It may not be used for the DsRestoreRegister API.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Ntdsbcli.h.
  Library: Included as a resource in Ntdsbcli.dll.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

Backing Up and Restoring Active Directory, Directory Backup Functions, DsRestoreEnd, DsRestoreRegister