WriteFileVlm

[This is preliminary documentation and subject to change.]

The WriteFileVlm function writes data to a file. WriteFileVlm is designed solely for asynchronous operation.

BOOL WriteFileVlm(
  HANDLE hFile,                 // handle to output file
  PVOID64 lpBuffer,             // pointer to input buffer
  DWORD nNumberOfBytesToWrite,  // number of bytes to write
  LPDWORD lpReserved,           // reserved, must be NULL
  LPOVERLAPPED lpOverlapped     // pointer to async. i/o data
);
 

Parameters

hFile

Open handle that specifies the file to write to. The file handle must have been created (using the CreateFile function) with GENERIC_WRITE access to the file. 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 the buffer containing the data to be written to the file. The address specified can be used to access memory in processes allocated using the VirtualAllocVlm function. Therefore, the address specified must be a 64-bit address or a sign-extended 32-bit address.

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

nNumberOfBytesToWrite

Number of bytes to write to the file. If the nNumberOfBtyesToWrite parameter is zero, WriteFileVlm changes the time stamp of the file and does not truncate or otherwise modify the data in the file.

lpReserved

Reserved; must be NULL.

lpOverlapped

Pointer to an OVERLAPPED structure. The lpOverlapped parameter is required and must point to a valid OVERLAPPED structure. The write operation starts at the offset specified in the OVERLAPPED structure, and WriteFileVlm may return before the write operation has been completed. In this case, WriteFileVlm returns FALSE and the GetLastError function returns ERROR_IO_PENDING. This functionality allows the calling process to continue processing while the write operation is being completed. An application can use either the GetOverlappedResult or HasOverlappedIoCompleted function to retrieve I/O completion notification. An application can use the GetQueuedCompletionStatus function to retrieve I/O completion.

For files that support byte offsets, you must specify a byte offset at which to start writing to the file. You specify this offset by setting the Offset and OffsetHigh members of the OVERLAPPED structure. For files that do not support byte offsets, Offset and OffsetHigh are ignored.

WriteFileVlm uses the Internal and InternalHigh members of the OVERLAPPED structure. A process should not change the value of these members.

The OVERLAPPED data structure must remain valid for the duration of the write operation. The structure should not be a variable that can go out of scope while the write operation is pending completion.

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.

Remarks

If part of the output file is locked by another process and the specified operation writes to the locked portion, WriteFileVlm fails.

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

WriteFileVlm can fail returning the messages ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY if there are too many outstanding asynchronous I/O requests.

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 write to a floppy drive that does not have 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 SEM_NOOPENFILEERRORBOX flag 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, GetOverlappedResult, GetQueuedCompletionStatus, HasOverlappedIoCompleted, MsgWaitForMultipleObjectsEx, OVERLAPPED, ReadFileVlm, SetEndOfFile, SetErrorMode, SleepEx, SignalObjectAndWait, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFileEx