DsBackupRead 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 DsBackupRead function reads a block of data from the current open file, into a buffer. The client application is expected to call this function repeatedly until the entire backup file has been received. The DsBackupOpenFile function provides the entire size of the backup file.

Syntax

HRESULT DsBackupRead(
  _In_  HBC    hbc,
  _In_  PVOID  pvBuffer,
  _In_  DWORD  cbBuffer,
  _Out_ PDWORD pcbRead
);

Parameters

hbc [in]

Contains the backup context handle obtained with the DsBackupPrepare function.

pvBuffer [in]

Pointer to a buffer that receives the data. This buffer must be at least cbBuffer bytes in size.

cbBuffer [in]

Contains the size, in bytes, of the buffer at pvBuffer. This value must be a multiple of 8192 and must be greater than or equal to 24576.

pcbRead [out]

Pointer to a DWORD value that receives the actual number of bytes read. This may be less than the number of bytes requested because some transports fragment the buffer being transmitted instead of filling the entire buffer with data.

Return value

Returns S_OK if the function is successful or a Win32 or RPC error code otherwise. Possible error codes include the following.

ERROR_INVALID_PARAMETER

One or more parameters are not valid.

ERROR_HANDLE_EOF

The end of the backup file was reached.

Requirements

Minimum supported client
Windows Vista
Minimum supported server
Windows Server 2008
Header
Ntdsbcli.h
Library
Ntdsbcli.lib
DLL
Ntdsbcli.dll

See also

DsBackupOpenFile

DsBackupPrepare

DsBackupFree

Backing Up an Active Directory Server

Directory Backup Functions