Directory Services

DsBackupRead

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 can be used to obtain the entire size of the backup file.

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

Parameters

hbc
[in] Contains the backup handle provided by DsBackupPrepare.
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. If the communication protocol is not TCP/IP, this value must be a multiple of 4096 bytes. To avoid the possibility of this error, always use a buffer size that is a multiple of 4096 bytes.
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 Values

Returns a standard HRESULT value, a Win32 error value, an RPC error value or one of the following.
Return Code Description
ERROR_SUCCESS The function was successful.
ERROR_INVALID_PARAMETER One or more parameters are invalid.
ERROR_HANDLE_EOF The end of the backup file was reached.

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Header: Declared in Ntdsbcli.h.
Library: Use Ntdsbcli.lib.

See Also

DsBackupOpenFile, DsBackupPrepare, DsBackupFree, Directory Backup Functions, Backing Up and Restoring Active Directory