Kernel32BackupRead Method

[DllImportAttribute("Kernel32.dll", SetLastError = true)]
public static bool BackupRead(
	SafeFileHandle hFile,
	IntPtr buffer,
	uint numberOfBytesToRead,
	ref uint refNumberOfBytesRead,
	bool abort,
	bool processSecurity,
	ref IntPtr refContext
)

<DllImportAttribute("Kernel32.dll", SetLastError := true>]
Public Shared Function BackupRead ( 
	hFile As SafeFileHandle,
	buffer As IntPtr,
	numberOfBytesToRead As UInteger,
	ByRef refNumberOfBytesRead As UInteger,
	abort As Boolean,
	processSecurity As Boolean,
	ByRef refContext As IntPtr
) As Boolean

Dim hFile As SafeFileHandle
Dim buffer As IntPtr
Dim numberOfBytesToRead As UInteger
Dim refNumberOfBytesRead As UInteger
Dim abort As Boolean
Dim processSecurity As Boolean
Dim refContext As IntPtr

Dim returnValue As Boolean

returnValue = Kernel32.BackupRead(hFile, 
	buffer, numberOfBytesToRead, refNumberOfBytesRead, 
	abort, processSecurity, refContext)

public:
[DllImportAttribute(L"Kernel32.dll", SetLastError = true)]
static bool BackupRead(
	SafeFileHandle^ hFile, 
	IntPtr buffer, 
	unsigned int numberOfBytesToRead, 
	unsigned int% refNumberOfBytesRead, 
	bool abort, 
	bool processSecurity, 
	IntPtr% refContext
)

[<DllImportAttribute("Kernel32.dll", SetLastError = true)>]
static member BackupRead : 
        hFile : SafeFileHandle * 
        buffer : IntPtr * 
        numberOfBytesToRead : uint32 * 
        refNumberOfBytesRead : uint32 byref * 
        abort : bool * 
        processSecurity : bool * 
        refContext : IntPtr byref -> bool 

No code example is currently available or this language may not be supported.

Parameters

hFile  SafeFileHandle

Handle to the file or directory to be backed up. To obtain the handle, call the CreateFile(String, FileAccessRights, FileShare, IntPtr, FileMode, CreateFileFlags, IntPtr) function.

The SACLs are not read unless the file handle was created with the 'ACCESS_SYSTEM_SECURITY' access right. For more information, see File security and access rights.

The handle must be synchronous (nonoverlapped). This means that the Overlapped flag must not be set when CreateFile(String, FileAccessRights, FileShare, IntPtr, FileMode, CreateFileFlags, IntPtr) is called.

This function does not validate that the handle it receives is synchronous, so it does not return an error code for a synchronous handle, but calling it with an asynchronous (overlapped) handle can result in subtle errors that are very difficult to debug.

The BackupRead function may fail if CreateFile(String, FileAccessRights, FileShare, IntPtr, FileMode, CreateFileFlags, IntPtr) was called with the flag NoBuffering. In this case, GetLastWin32Error returns ERROR_INVALID_PARAMETER.

buffer  IntPtr

Pointer to a buffer that receives the data.

numberOfBytesToRead  UInt32

Length of the buffer, in bytes.

The buffer size must be greater than the size of a FindStreamInfo structure.

refNumberOfBytesRead  UInt32

Receives the number of bytes read.

If the function returns , and the variable pointed to by refNumberOfBytesRead is zero, then all the data associated with the file handle has been read.

abort  Boolean

Indicates whether you have finished using BackupRead(SafeFileHandle, IntPtr, UInt32, UInt32, Boolean, Boolean, IntPtr) on the handle.

While you are backing up the file, specify this parameter as .

Once you are done using BackupRead(SafeFileHandle, IntPtr, UInt32, UInt32, Boolean, Boolean, IntPtr), you must call BackupRead(SafeFileHandle, IntPtr, UInt32, UInt32, Boolean, Boolean, IntPtr) one more time specifying for this parameter and passing the appropriate refContext.

refContext must be passed when abort parameter is ; all other parameters are ignored.

processSecurity  Boolean

Indicates whether the function will restore the access-control list (ACL) data for the file or directory.

If processSecurity is , the ACL data will be backed up.

refContext  IntPtr

Pointer to a variable that receives a pointer to an internal data structure used by BackupRead(SafeFileHandle, IntPtr, UInt32, UInt32, Boolean, Boolean, IntPtr) to maintain context information during a backup operation.

You must set the variable pointed to by refContext to NULL before the first call to BackupRead(SafeFileHandle, IntPtr, UInt32, UInt32, Boolean, Boolean, IntPtr) for the specified file or directory.

The function allocates memory for the data structure, and then sets the variable to point to that structure. You must not change refContext or the variable that it points to between calls to BackupRead(SafeFileHandle, IntPtr, UInt32, UInt32, Boolean, Boolean, IntPtr).

To release the memory used by the data structure, call BackupRead(SafeFileHandle, IntPtr, UInt32, UInt32, Boolean, Boolean, IntPtr) with the abort parameter set to when the backup operation is complete.

Return Value

If the function fails, the return value is , indicating that an I/O error occurred.

To get extended error information, call GetLastWin32Error.

Reference