大网数据广告活动
域与目录服务

DsBackupPrepare function (Ntdsbcli.h)

· 52CE 我爱测

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.

[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)

See also

DsRestorePrepare

DsBackupFree

DsBackupOpenFile

DsBackupEnd

DsSetAuthIdentity

Backing Up an Active Directory Server

Directory Backup Functions

Source: Microsoft Learn / Windows Win32 documentation by Microsoft and contributors. Documentation licensed CC BY 4.0. Code samples are covered by the MIT License. Converted from Markdown, with links normalized and embedded media omitted.

资料来源与适用范围

资料来源
Microsoft Learn / Windows Win32 documentation
适用范围
Windows Win32 API · Source date 05/31/2018
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY 4.0 (documentation), MIT (code samples)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。