DsBackupRead

The DsBackupRead function reads one block from the currently open file into the given buffer. The client application is expected to call this function repeatedly until it gets the entire file (the application would have received the file size through a DsBackupOpenFile function call before calling DsBackupRead).

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

Parameters

hbc

[in] Points to the client context handle of the backup.

pvBuffer

[in] Pointer to the buffer that will receive the read data.

cbBuffer

[in] Specifies the size of the pvBuffer buffer. If the communication protocol is not TCP/IP, this value must be a multiple of 4096 bytes.

pcbRead

[out] Pointer to receive the actual number of bytes read.

Note  The number of bytes read, pcbRead, may be less than the size of the buffer, cbBuffer. This does not indicate an error. Some transports fragment the buffer being transmitted instead of filling the entire buffer with data.

Return Values

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

Remarks

Your application must allocate the space for the buffer where pvBuffer points and release this space with a call to the DsBackupFree function when you are finished with the buffer.

If the client or server cannot communicate using TCP/IP, the buffer must be a multiple of 4096 bytes. If your application does not use buffer sizes that are a multiple of 4096 bytes or the TCP/IP communication protocol, DsBackupRead fails.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Ntdsbcli.h.
  Library: Included as a resource in Ntdsbcli.dll.

See Also

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