ReadFileVlm

[This is preliminary documentation and subject to change.]

The ReadFileVlm function reads data from a file asynchronously. ReadFileVlm is designed solely for asynchronous operation, unlike the ReadFile function, which is designed for both synchronous and asynchronous operation.

BOOL ReadFileVlm(
  HANDLE hFile,                // handle of file to read 
  PVOID64 lpBuffer,            // pointer to buffer 
  DWORD nNumberOfBytesToRead,  // number of bytes to read
  LPDWORD lpReserved,          // reserved; must be NULL
  LPOVERLAPPED lpOverlapped    // pointer to offset 
);
 

Parameters

hFile

Open handle that specifies the file to read from. To open a file handle, use the CreateFile function. To specify asynchronous I/O, this file handle must have been created with the FILE_FLAG_OVERLAPPED flag. To specify noncached I/O, this file handle must have been created with the FILE_FLAG_NO_BUFFERING flag.

lpBuffer

Pointer to a buffer that receives the data read from the file. The address specified can be used to access memory in processes allocated using the VirtualAllocVlm function. Therefore, the address specified must be 64 bits or a sign-extended 32-bit address.

The buffer pointed to by the lpBuffer parameter must remain valid for the duration of the read operation. The calling process should not use this buffer until the read operation is completed.

nNumberOfBytesToRead

Number of bytes to read from the file.

lpReserved

Reserved; must be NULL.

lpOverlapped

Pointer to an OVERLAPPED data structure that supplies data to be used during the overlapped (asynchronous) read operation.

If the file specified by the hFile parameter supports byte offsets, the process that calls ReadFileVlm must specify a byte offset within the file at which reading should begin. The calling process specifies the byte offset by setting the OVERLAPPED structure's Offset and OffsetHigh members.

ReadFileVlm uses the OVERLAPPED structure's Internal and InternalHigh members. An application should not set these members.

The OVERLAPPED data structure pointed to by the lpOverlapped parameter must remain valid for the duration of the read operation. The structure should not be a variable that can go out of scope while the read operation is in progress.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

If ReadFileVlm attempts to read past the end of the file, the function returns zero, and GetLastError returns the error code ERROR_HANDLE_EOF.

Remarks

If a portion of the file specified by hFile is locked by another process and the portion read by the read operation overlaps the locked portion, a call to ReadFileVlm fails.

Accessing the input buffer while a read operation is using the buffer may lead to corruption of the data read into that buffer. Applications must not read from, write to, reallocate, or free the input buffer that a read operation is using until the read operation completes.

To determine whether an asynchronous I/O operation has completed, you can use the HasOverlappedIoCompleted macro.

The ReadFileVlm function may fail if there are too many outstanding asynchronous I/O requests. In the event of such a failure, GetLastError can return ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY.

To cancel all pending asynchronous I/O operations, use the CancelIo function. CancelIo only cancels operations issued by the calling thread for the specified file handle. I/O operations that are canceled complete with the error code ERROR_OPERATION_ABORTED.

If your application attempts to read from a floppy drive that does not contain a floppy disk, the operating system displays a message prompting the user to retry the operation. To prevent the system from displaying this message, call the SetErrorMode function with the flag SEM_NOOPENFILEERRORBOX set for the uMode parameter.

Note  To guard against an access violation, use structured exception handling to protect any code that writes to or reads from a memory-mapped view. For more information on structured exception handling, see Reading and Writing.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use kernel32.lib.

See Also

Memory Management Overview, Memory Management Functions, Very Large Memory (VLM), CancelIo, CreateFile, FileIOCompletionRoutine, HasOverlappedIoCompleted, MsgWaitForMultipleObjectsEx, OVERLAPPED, ReadFile, SetErrorMode, SleepEx, VirtualAllocVlm, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFileVlm