File class

Takes ownership of a handle.

Syntax

explicit File(HANDLE handle = INVALID_HANDLE_VALUE) noexcept;

Parameters

handleHANDLE

The handle to own; default: none.Default: INVALID_HANDLE_VALUE

Takes over another object's handle.

Syntax

File(File&& other) noexcept;

Parameters

otherFile&&

The object to take the handle from; holds no handle afterwards.

Remarks

Closes the handle.

Syntax

~File() noexcept;

Remarks

Takes over another object's handle.

Syntax

File& operator=(File&& other) noexcept;

Parameters

otherFile&&

The object to take the handle from; holds no handle afterwards.

Return value

Type: File&

This object.

Remarks

true if a handle is held.

Syntax

bool IsValid() const noexcept;

Return value

Type: bool

true if a handle is held; false if the object holds INVALID_HANDLE_VALUE.

The handle, still owned by this object.

Syntax

HANDLE GetHandle() const noexcept;

Return value

Type: HANDLE

The handle, or INVALID_HANDLE_VALUE if none is held; do not close it.

GetFileSizeEx.

Syntax

ErrorCode GetSize(FileSize& size) const noexcept;

Parameters

sizeFileSize&

Receives the file size in bytes; unchanged on failure.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

GetFileType (FILE_TYPE_DISK, FILE_TYPE_PIPE, ...).

Syntax

ErrorCode GetType(DWORD& type) const noexcept;

Parameters

typeDWORD&

Receives the FILE_TYPE_* value; FILE_TYPE_UNKNOWN on failure or for an unknown type.

Return value

Type: ErrorCode

ERROR_SUCCESS for a known type; otherwise the GetLastError code, which is also ERROR_SUCCESS if the type is simply unknown.

Closes the handle.

Syntax

ErrorCode Close() noexcept;

Return value

Type: ErrorCode

ERROR_SUCCESS if the handle was closed or none was held; otherwise the CloseHandle error.

Remarks

See also

Create

Opens or creates a file (CreateFileW).

Syntax

ErrorCode Create(
    const FileName& fileName,
    DWORD desiredAccess,
    DWORD shareMode,
    SECURITY_ATTRIBUTES* securityAttributes,
    DWORD creationDisposition,
    DWORD flagsAndAttributes,
    HANDLE templateFile
) noexcept;

Parameters

fileNameconst FileName&

Path of the file, device or pipe; must not be nullptr.

desiredAccessDWORD

Requested access: GENERIC_READ, GENERIC_WRITE, both, specific rights such as DELETE, or 0 to query attributes only.

shareModeDWORD

What other opens may do meanwhile: 0 (exclusive) or a combination of FILE_SHARE_READ, FILE_SHARE_WRITE and FILE_SHARE_DELETE.

securityAttributesSECURITY_ATTRIBUTES*

Security descriptor and handle inheritance; nullptr for the defaults.

creationDispositionDWORD

CREATE_NEW, CREATE_ALWAYS, OPEN_EXISTING, OPEN_ALWAYS or TRUNCATE_EXISTING.

flagsAndAttributesDWORD

FILE_ATTRIBUTE_* and FILE_FLAG_* values; FILE_FLAG_OVERLAPPED is required for AsyncIo::AsyncFile, FILE_FLAG_NO_BUFFERING requires sector-aligned buffers and sizes.

templateFileHANDLE

Handle opened with GENERIC_READ whose attributes a new file takes over; usually nullptr.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

Remarks

See also

Close

DeleteFileW.

Syntax

static ErrorCode Delete(const FileName& fileName) noexcept;

Parameters

fileNameconst FileName&

Path of the file to delete; must not be nullptr.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

SetEndOfFile at the current file pointer.

Syntax

ErrorCode SetEof() const noexcept;

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

Remarks

See also

SetEofInformation

SetFilePointerEx.

Syntax

ErrorCode SetFilePointer(
    const Distance& distanceToMove,
    Distance* newFilePointer,
    DWORD moveMethod
) const noexcept;

Parameters

distanceToMoveconst Distance&

Bytes to move the file pointer; negative values move it backwards.

newFilePointerDistance*

Receives the new position; may be nullptr.

moveMethodDWORD

Starting point of the move: FILE_BEGIN, FILE_CURRENT or FILE_END.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

ReadFile.

Syntax

ErrorCode Read(
    void* buffer,
    DWORD bytesToRead,
    DWORD* bytesRead,
    OVERLAPPED* overlapped
) const noexcept;

Parameters

buffervoid*

Receives the data; at least bytesToRead bytes.

bytesToReadDWORD

Maximum number of bytes to read.

bytesReadDWORD*

Receives the number of bytes read (0 at end of file); may be nullptr only with overlapped.

overlappedOVERLAPPED*

File offset and completion state for an overlapped handle; nullptr for a synchronous read at the file pointer.

Return value

Type: ErrorCode

ERROR_SUCCESS if the read completed, ERROR_IO_PENDING if it is still running (overlapped), or the Win32 error code (e.g. ERROR_HANDLE_EOF).

Remarks

See also

Write, AsyncIo::AsyncFile::ReadAsync

ReadFileEx.

Syntax

ErrorCode Read(
    void* buffer,
    DWORD bytesToRead,
    OVERLAPPED* overlapped,
    LPOVERLAPPED_COMPLETION_ROUTINE completionRoutine
) const noexcept;

Parameters

buffervoid*

Receives the data; at least bytesToRead bytes, valid until the completion routine ran.

bytesToReadDWORD

Maximum number of bytes to read.

overlappedOVERLAPPED*

File offset of the read; must not be nullptr and must stay valid until the completion routine ran.

completionRoutineLPOVERLAPPED_COMPLETION_ROUTINE

Runs as an APC in an alertable wait of the calling thread.

Return value

Type: ErrorCode

ERROR_SUCCESS if the read was queued (the result arrives in the completion routine); otherwise the Win32 error code.

Remarks

ReadFileScatter.

Syntax

ErrorCode Read(
    FILE_SEGMENT_ELEMENT* segments,
    DWORD bytesToRead,
    OVERLAPPED& overlapped
) const noexcept;

Parameters

segmentsFILE_SEGMENT_ELEMENT*

Array of page-sized, page-aligned buffers, terminated by a nullptr element; valid until the completion.

bytesToReadDWORD

Total bytes to read; a multiple of the volume sector size.

overlappedOVERLAPPED&

File offset and completion state; must stay valid until the completion.

Return value

Type: ErrorCode

ERROR_SUCCESS if the read completed, ERROR_IO_PENDING if it is still running, or the Win32 error code.

Remarks

CancelIo: cancels the calling thread's pending operations.

Syntax

ErrorCode CancelIo() const noexcept;

Return value

Type: ErrorCode

ERROR_SUCCESS if the cancellation was requested; otherwise the Win32 error code.

CancelIoEx for one operation, from any thread.

Syntax

ErrorCode CancelIo(OVERLAPPED& overlapped) const noexcept;

Parameters

overlappedOVERLAPPED&

The OVERLAPPED of the pending operation to cancel.

Return value

Type: ErrorCode

ERROR_SUCCESS if the cancellation was requested, ERROR_NOT_FOUND if nothing was pending, or another Win32 error code.

Remarks

FlushFileBuffers; blocks until the data is on the device.

Syntax

ErrorCode Flush() const noexcept;

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

CreateHardLinkW.

Syntax

static ErrorCode CreateHardLink(
    const FileName& fileName,
    const FileName& existingFileName
) noexcept;

Parameters

fileNameconst FileName&

Becomes a new name of existingFileName.

existingFileNameconst FileName&

Path of an existing file on the same volume.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

CreateSymbolicLinkW.

Syntax

static ErrorCode CreateSymbolicLink(
    const FileName& symlinkFileName,
    const FileName& targetFileName,
    DWORD flags
) noexcept;

Parameters

symlinkFileNameconst FileName&

Path of the link to create.

targetFileNameconst FileName&

Path the link points to; may be relative and need not exist.

flagsDWORD

0 for a file, SYMBOLIC_LINK_FLAG_DIRECTORY for a directory, optionally combined with SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

DecryptFileW (EFS).

Syntax

static ErrorCode Decrypt(const FileName& fileName) noexcept;

Parameters

fileNameconst FileName&

Path of the encrypted file or directory.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

See also

Encrypt

EncryptFileW (EFS).

Syntax

static ErrorCode Encrypt(const FileName& fileName) noexcept;

Parameters

fileNameconst FileName&

Path of the file or directory to encrypt; a file must not be open elsewhere.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

See also

Decrypt

FileEncryptionStatusW.

Syntax

static ErrorCode EncryptionStatus(const FileName& fileName, DWORD& status) noexcept;

Parameters

fileNameconst FileName&

Path of the file or directory.

statusDWORD&

Receives a FILE_* status such as FILE_ENCRYPTABLE or FILE_IS_ENCRYPTED.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

GetBinaryTypeW (SCS_* value).

Syntax

static ErrorCode GetBinaryType(
    const FileName& fileName,
    DWORD& binaryType
) noexcept;

Parameters

fileNameconst FileName&

Path of the file to examine.

binaryTypeDWORD&

Receives the executable type, e.g. SCS_64BIT_BINARY.

Return value

Type: ErrorCode

ERROR_SUCCESS for an executable; otherwise the Win32 error code (also for a file that is not executable).

GetCompressedFileSizeW: bytes the file occupies on disk.

Syntax

static ErrorCode GetCompressedSize(
    const FileName& fileName,
    FileSize& fileSize
) noexcept;

Parameters

fileNameconst FileName&

Path of the file.

fileSizeFileSize&

Receives the size on disk in bytes; unchanged on failure.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

GetFileAttributesW.

Syntax

static ErrorCode GetAttributes(
    const FileName& fileName,
    DWORD& attributes
) noexcept;

Parameters

fileNameconst FileName&

Path of the file or directory.

attributesDWORD&

Receives the FILE_ATTRIBUTE_* flags; INVALID_FILE_ATTRIBUTES on failure.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

See also

SetAttributes

GetFileAttributesExW (attributes, times, size).

Syntax

static ErrorCode GetAttributes(
    const FileName& fileName,
    WIN32_FILE_ATTRIBUTE_DATA& attributes
) noexcept;

Parameters

fileNameconst FileName&

Path of the file or directory.

attributesWIN32_FILE_ATTRIBUTE_DATA&

Receives the attributes, times and size.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

GetFileBandwidthReservation.

Syntax

ErrorCode GetBandwidthReservation(
    DWORD& periodMilliseconds,
    DWORD& bytesPerPeriod,
    BOOL& discardable,
    DWORD& transferSize,
    DWORD& numOutstandingRequests
) const noexcept;

Parameters

periodMillisecondsDWORD&

Receives the reservation period in milliseconds.

bytesPerPeriodDWORD&

Receives the bytes reserved per period.

discardableBOOL&

Receives whether unused bandwidth of a period is discarded.

transferSizeDWORD&

Receives the recommended transfer size in bytes.

numOutstandingRequestsDWORD&

Receives the number of requests to keep outstanding.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

See also

SetBandwidthReservation

SetFileBandwidthReservation.

Syntax

ErrorCode SetBandwidthReservation(
    DWORD periodMilliseconds,
    DWORD bytesPerPeriod,
    BOOL discardable,
    DWORD& transferSize,
    DWORD& numOutstandingRequests
) const noexcept;

Parameters

periodMillisecondsDWORD

Length of the reservation period in milliseconds.

bytesPerPeriodDWORD

Bytes to reserve per period; 0 removes the reservation.

discardableBOOL

TRUE if bandwidth not used in a period may be discarded; FALSE to carry it over.

transferSizeDWORD&

Receives the transfer size to use.

numOutstandingRequestsDWORD&

Receives the number of requests to keep outstanding.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

See also

GetBandwidthReservation

GetFileInformationByHandle.

Syntax

ErrorCode GetInformation(BY_HANDLE_FILE_INFORMATION& information) const noexcept;

Parameters

informationBY_HANDLE_FILE_INFORMATION&

Receives attributes, times, volume serial number, size, link count and file index.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

GetFileInformationByHandleEx(FileBasicInfo).

Syntax

ErrorCode GetBasicInformation(FILE_BASIC_INFO& information) const noexcept;

Parameters

informationFILE_BASIC_INFO&

Receives the creation, access, write and change times and the attributes.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

See also

SetBasicInformation

GetFileInformationByHandleEx(FileStandardInfo).

Syntax

ErrorCode GetStandardInformation(FILE_STANDARD_INFO& information) const noexcept;

Parameters

informationFILE_STANDARD_INFO&

Receives allocation size, end of file, link count, delete-pending state and whether it is a directory.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

GetFileInformationByHandleEx(FileNameInfo).

Syntax

ErrorCode GetNameInformation(FILE_NAME_INFO& information) const noexcept;

Parameters

informationFILE_NAME_INFO&

Receives the name length in bytes and the path without the volume.

Return value

Type: ErrorCode

ERROR_SUCCESS, ERROR_MORE_DATA if the name does not fit, or another Win32 error code.

Remarks

GetFileInformationByHandleEx(FileStreamInfo).

Syntax

ErrorCode GetStreamInformation(FILE_STREAM_INFO& information) const noexcept;

Parameters

informationFILE_STREAM_INFO&

Receives the first stream entry: name, size and allocation size.

Return value

Type: ErrorCode

ERROR_SUCCESS, ERROR_MORE_DATA if the data does not fit, or another Win32 error code.

Remarks

GetFileInformationByHandleEx(FileCompressionInfo).

Syntax

ErrorCode GetCompressionInformation(
    FILE_COMPRESSION_INFO& information
) const noexcept;

Parameters

informationFILE_COMPRESSION_INFO&

Receives the compressed size and the compression format and parameters.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

GetFileInformationByHandleEx(FileAttributeTagInfo).

Syntax

ErrorCode GetAttributeTagInformation(
    FILE_ATTRIBUTE_TAG_INFO& information
) const noexcept;

Parameters

informationFILE_ATTRIBUTE_TAG_INFO&

Receives the attributes and the reparse tag.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

GetFileInformationByHandleEx(FileIdBothDirectoryInfo).

Syntax

ErrorCode GetIdBothDirectoryInformation(
    FILE_ID_BOTH_DIR_INFO& information
) const noexcept;

Parameters

informationFILE_ID_BOTH_DIR_INFO&

Receives the next directory entry (handle opened on a directory) with long and short name and file id.

Return value

Type: ErrorCode

ERROR_SUCCESS, ERROR_NO_MORE_FILES after the last entry, ERROR_MORE_DATA if the entry does not fit, or another Win32 error code.

Remarks

GetFileInformationByHandleEx(FileIdBothDirectoryRestartInfo).

Syntax

ErrorCode GetIdBothDirectoryRestartInformation(
    FILE_ID_BOTH_DIR_INFO& information
) const noexcept;

Parameters

informationFILE_ID_BOTH_DIR_INFO&

Receives the first directory entry again (enumeration restarts), with long and short name and file id.

Return value

Type: ErrorCode

ERROR_SUCCESS, ERROR_MORE_DATA if the entry does not fit, or another Win32 error code.

Remarks

GetFileInformationByHandleEx(FileRemoteProtocolInfo).

Syntax

ErrorCode GetRemoteProtocolInformation(
    FILE_REMOTE_PROTOCOL_INFO& information
) const noexcept;

Parameters

informationFILE_REMOTE_PROTOCOL_INFO&

Receives the network protocol (e.g. SMB) and its version for a remote file.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

GetFileInformationByHandleEx(FileFullDirectoryInfo).

Syntax

ErrorCode GetFullDirectoryInformation(
    FILE_FULL_DIR_INFO& information
) const noexcept;

Parameters

informationFILE_FULL_DIR_INFO&

Receives the next directory entry (handle opened on a directory) with name, times, sizes and attributes.

Return value

Type: ErrorCode

ERROR_SUCCESS, ERROR_NO_MORE_FILES after the last entry, ERROR_MORE_DATA if the entry does not fit, or another Win32 error code.

Remarks

GetFileInformationByHandleEx(FileFullDirectoryRestartInfo).

Syntax

ErrorCode GetFullDirectoryRestartInformation(
    FILE_FULL_DIR_INFO& information
) const noexcept;

Parameters

informationFILE_FULL_DIR_INFO&

Receives the first directory entry again (enumeration restarts), with name, times, sizes and attributes.

Return value

Type: ErrorCode

ERROR_SUCCESS, ERROR_MORE_DATA if the entry does not fit, or another Win32 error code.

Remarks

GetFileInformationByHandleEx(FileStorageInfo).

Syntax

ErrorCode GetStorageInformation(FILE_STORAGE_INFO& information) const noexcept;

Parameters

informationFILE_STORAGE_INFO&

Receives the logical and physical sector sizes and alignment of the volume.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

GetFileInformationByHandleEx(FileAlignmentInfo).

Syntax

ErrorCode GetAlignmentInformation(FILE_ALIGNMENT_INFO& information) const noexcept;

Parameters

informationFILE_ALIGNMENT_INFO&

Receives the buffer alignment the device requires for unbuffered I/O.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

GetFileInformationByHandleEx(FileIdInfo).

Syntax

ErrorCode GetIdInformation(FILE_ID_INFO& information) const noexcept;

Parameters

informationFILE_ID_INFO&

Receives the volume serial number and the 128-bit file id.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

GetFileInformationByHandleEx(FileIdExtdDirectoryInfo).

Syntax

ErrorCode GetIdExtendedDirectoryInformation(
    FILE_ID_EXTD_DIR_INFO& information
) const noexcept;

Parameters

informationFILE_ID_EXTD_DIR_INFO&

Receives the next directory entry (handle opened on a directory) with name and 128-bit file id.

Return value

Type: ErrorCode

ERROR_SUCCESS, ERROR_NO_MORE_FILES after the last entry, ERROR_MORE_DATA if the entry does not fit, or another Win32 error code.

Remarks

GetFileInformationByHandleEx(FileIdExtdDirectoryRestartInfo).

Syntax

ErrorCode GetIdExtendedDirectoryRestartInformation(
    FILE_ID_EXTD_DIR_INFO& information
) const noexcept;

Parameters

informationFILE_ID_EXTD_DIR_INFO&

Receives the first directory entry again (enumeration restarts), with name and 128-bit file id.

Return value

Type: ErrorCode

ERROR_SUCCESS, ERROR_MORE_DATA if the entry does not fit, or another Win32 error code.

Remarks

GetFinalPathNameByHandleW.

Syntax

ErrorCode GetFinalPath(
    PathBuffer filePath,
    DWORD& filePathLength,
    DWORD flags
) const noexcept;

Parameters

filePathPathBuffer

Receives the null-terminated path; filePathLength characters.

filePathLengthDWORD&

In: buffer size in characters. Out: characters written, or the size needed (including the terminator) if the buffer is too small.

flagsDWORD

FILE_NAME_NORMALIZED or FILE_NAME_OPENED, combined with a VOLUME_NAME_* value (0 = normalized DOS path).

Return value

Type: ErrorCode

ERROR_SUCCESS (also for a too small buffer, see remarks); otherwise the Win32 error code.

Remarks

GetFullPathNameW.

Syntax

static ErrorCode GetFullPath(
    FileName fileName,
    PathBuffer fullPath,
    DWORD& fullPathLength,
    PathBuffer* filePart
) noexcept;

Parameters

fileNameFileName

Relative or absolute path to resolve against the current directory; need not exist.

fullPathPathBuffer

Receives the null-terminated full path; fullPathLength characters.

fullPathLengthDWORD&

In: buffer size in characters. Out: characters written, or the size needed (including the terminator) if the buffer is too small.

filePartPathBuffer*

Receives a pointer into fullPath to the final name component; may be nullptr.

Return value

Type: ErrorCode

ERROR_SUCCESS (also for a too small buffer); otherwise the Win32 error code.

Remarks

GetLongPathNameW.

Syntax

static ErrorCode GetLongPath(
    FileName fileName,
    PathBuffer longPath,
    DWORD& longPathLength
) noexcept;

Parameters

fileNameFileName

Existing path, possibly with 8.3 short name components.

longPathPathBuffer

Receives the null-terminated long path; longPathLength characters.

longPathLengthDWORD&

In: buffer size in characters. Out: characters written, or the size needed if the buffer is too small.

Return value

Type: ErrorCode

ERROR_SUCCESS (also for a too small buffer); otherwise the Win32 error code.

Remarks

See also

GetShortPath

GetShortPathNameW.

Syntax

static ErrorCode GetShortPath(
    FileName fileName,
    PathBuffer shortPath,
    DWORD& shortPathLength
) noexcept;

Parameters

fileNameFileName

Existing path to convert.

shortPathPathBuffer

Receives the null-terminated 8.3 path; shortPathLength characters.

shortPathLengthDWORD&

In: buffer size in characters. Out: characters written, or the size needed if the buffer is too small.

Return value

Type: ErrorCode

ERROR_SUCCESS (also for a too small buffer); otherwise the Win32 error code.

Remarks

See also

GetLongPath

LockFile: locks a byte range exclusively.

Syntax

ErrorCode Lock(const FileSize& offset, const FileSize& size) const noexcept;

Parameters

offsetconst FileSize&

Start of the range in bytes.

sizeconst FileSize&

Length of the range in bytes; may extend beyond the end of the file.

Return value

Type: ErrorCode

ERROR_SUCCESS, ERROR_LOCK_VIOLATION if the range is already locked, or another Win32 error code.

Remarks

See also

Unlock

LockFileEx: locks a byte range.

Syntax

ErrorCode Lock(
    DWORD flags,
    const FileSize& size,
    OVERLAPPED& overlapped
) const noexcept;

Parameters

flagsDWORD

LOCKFILE_EXCLUSIVE_LOCK / LOCKFILE_FAIL_IMMEDIATELY.

sizeconst FileSize&

Length of the range in bytes; may extend beyond the end of the file.

overlappedOVERLAPPED&

Carries the offset of the range.

Return value

Type: ErrorCode

ERROR_SUCCESS if the lock is held, ERROR_IO_PENDING if it is still being acquired (overlapped handle), ERROR_LOCK_VIOLATION with LOCKFILE_FAIL_IMMEDIATELY, or another Win32 error code.

Remarks

See also

Unlock

UnlockFile of a range locked with Lock.

Syntax

ErrorCode Unlock(const FileSize& offset, const FileSize& size) const noexcept;

Parameters

offsetconst FileSize&

Start of the range in bytes; must match the locked range exactly.

sizeconst FileSize&

Length of the range in bytes; must match the locked range exactly.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code (e.g. ERROR_NOT_LOCKED).

UnlockFileEx: unlocks a byte range.

Syntax

ErrorCode Unlock(const FileSize& size, OVERLAPPED& overlapped) const noexcept;

Parameters

sizeconst FileSize&

Length of the range in bytes; must match the locked range exactly.

overlappedOVERLAPPED&

Carries the offset of the range.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code (e.g. ERROR_NOT_LOCKED).

See also

Lock

MoveFileW.

Syntax

static ErrorCode Move(
    const FileName& existingFileName,
    const FileName& newFileName
) noexcept;

Parameters

existingFileNameconst FileName&

Current path of the file or directory.

newFileNameconst FileName&

New path; must not exist.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

MoveFileExW (MOVEFILE_* flags).

Syntax

static ErrorCode Move(
    const FileName& existingFileName,
    const FileName& newFileName,
    DWORD flags
) noexcept;

Parameters

existingFileNameconst FileName&

Current path of the file or directory.

newFileNameconst FileName&

New path; nullptr with MOVEFILE_DELAY_UNTIL_REBOOT deletes the file at the next boot.

flagsDWORD

MOVEFILE_* values, e.g. MOVEFILE_REPLACE_EXISTING, MOVEFILE_COPY_ALLOWED, MOVEFILE_WRITE_THROUGH; 0 behaves like Move without flags.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

MoveFileWithProgressW.

Syntax

static ErrorCode Move(
    const FileName& existingFileName,
    const FileName& newFileName,
    LPPROGRESS_ROUTINE progressRoutine,
    void* data,
    DWORD flags
) noexcept;

Parameters

existingFileNameconst FileName&

Current path of the file or directory.

newFileNameconst FileName&

New path; nullptr with MOVEFILE_DELAY_UNTIL_REBOOT deletes the file at the next boot.

progressRoutineLPPROGRESS_ROUTINE

May be nullptr; called on the calling thread with data.

datavoid*

Passed unchanged to progressRoutine; may be nullptr.

flagsDWORD

MOVEFILE_* values as for the MoveFileExW overload.

Return value

Type: ErrorCode

ERROR_SUCCESS, ERROR_REQUEST_ABORTED if the progress routine cancelled, or another Win32 error code.

SetFileAttributesW.

Syntax

static ErrorCode SetAttributes(const FileName& fileName, DWORD attributes) noexcept;

Parameters

fileNameconst FileName&

Path of the file or directory.

attributesDWORD

New FILE_ATTRIBUTE_* flags (e.g. FILE_ATTRIBUTE_READONLY); replaces the settable ones, FILE_ATTRIBUTE_NORMAL clears them.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

See also

GetAttributes

SetFileCompletionNotificationModes.

Syntax

ErrorCode SetCompletionNotificationModes(UCHAR flags) const noexcept;

Parameters

flagsUCHAR

FILE_SKIP_COMPLETION_PORT_ON_SUCCESS and/or FILE_SKIP_SET_EVENT_ON_HANDLE; modes cannot be turned off again.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

Remarks

SetFileInformationByHandle(FileBasicInfo): times and attributes.

Syntax

ErrorCode SetBasicInformation(FILE_BASIC_INFO& information) const noexcept;

Parameters

informationFILE_BASIC_INFO&

New times and attributes; a time of 0 leaves it unchanged, -1 stops its automatic update.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

See also

GetBasicInformation

SetFileInformationByHandle(FileRenameInfo).

Syntax

ErrorCode SetRenameInformation(FILE_RENAME_INFO& information) const noexcept;

Parameters

informationFILE_RENAME_INFO&

New name with its length in bytes, whether to replace an existing file and an optional root directory; the handle needs DELETE access.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

Remarks

SetFileInformationByHandle(FileDispositionInfo): delete on close.

Syntax

ErrorCode SetDispositionInformation(
    FILE_DISPOSITION_INFO& information
) const noexcept;

Parameters

informationFILE_DISPOSITION_INFO&

DeleteFile member TRUE to delete the file when the last handle closes, FALSE to cancel that; the handle needs DELETE access.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

SetFileInformationByHandle(FileAllocationInfo).

Syntax

ErrorCode SetAllocationInformation(
    FILE_ALLOCATION_INFO& information
) const noexcept;

Parameters

informationFILE_ALLOCATION_INFO&

New allocation size in bytes; the file size is not changed by growing it.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

SetFileInformationByHandle(FileEndOfFileInfo): sets the size.

Syntax

ErrorCode SetEofInformation(FILE_END_OF_FILE_INFO& information) const noexcept;

Parameters

informationFILE_END_OF_FILE_INFO&

New end of file in bytes; extending fills with zeros, shrinking truncates.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

Remarks

See also

SetEof

SetFileInformationByHandle(FileIoPriorityHintInfo).

Syntax

ErrorCode SetIoPriorityHintInformation(
    FILE_IO_PRIORITY_HINT_INFO& information
) const noexcept;

Parameters

informationFILE_IO_PRIORITY_HINT_INFO&

I/O priority hint for this handle: IoPriorityHintVeryLow, IoPriorityHintLow or IoPriorityHintNormal.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

SetFileIoOverlappedRange.

Syntax

ErrorCode SetIoOverlappedRange(
    UCHAR* overlappedRangeStart,
    ULONG length
) const noexcept;

Parameters

overlappedRangeStartUCHAR*

Start of the memory that holds the OVERLAPPED structures used with this handle; must stay valid while the handle is open.

lengthULONG

Size of that memory range in bytes.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

Remarks

SetFileShortNameW.

Syntax

ErrorCode SetShortName(const FileName& shortName) const noexcept;

Parameters

shortNameconst FileName&

New 8.3 short name (name only, no path).

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

Remarks

SetFileValidData: extends the valid data without zeroing it.

Syntax

ErrorCode SetValidData(long long validDataLength) const noexcept;

Parameters

validDataLengthlong long

New valid data length in bytes; larger than the current one and not beyond the allocated size.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

Remarks

WriteFile.

Syntax

ErrorCode Write(
    const void* buffer,
    DWORD bytesToWrite,
    DWORD* bytesWritten,
    OVERLAPPED* overlapped
) const noexcept;

Parameters

bufferconst void*

The data to write; at least bytesToWrite bytes.

bytesToWriteDWORD

Number of bytes to write.

bytesWrittenDWORD*

Receives the number of bytes written; may be nullptr only with overlapped.

overlappedOVERLAPPED*

File offset and completion state for an overlapped handle; nullptr for a synchronous write at the file pointer.

Return value

Type: ErrorCode

ERROR_SUCCESS if the write completed, ERROR_IO_PENDING if it is still running (overlapped), or the Win32 error code.

Remarks

See also

Read, AsyncIo::AsyncFile::WriteAsync

WriteFileEx.

Syntax

ErrorCode Write(
    const void* buffer,
    DWORD bytesToWrite,
    OVERLAPPED* overlapped,
    LPOVERLAPPED_COMPLETION_ROUTINE completionRoutine
) const noexcept;

Parameters

bufferconst void*

The data to write; at least bytesToWrite bytes, valid until the completion routine ran.

bytesToWriteDWORD

Number of bytes to write.

overlappedOVERLAPPED*

File offset of the write; must not be nullptr and must stay valid until the completion routine ran.

completionRoutineLPOVERLAPPED_COMPLETION_ROUTINE

Runs as an APC in an alertable wait of the calling thread.

Return value

Type: ErrorCode

ERROR_SUCCESS if the write was queued (the result arrives in the completion routine); otherwise the Win32 error code.

Remarks

WriteFileGather.

Syntax

ErrorCode Write(
    FILE_SEGMENT_ELEMENT* segments,
    DWORD bytesToWrite,
    OVERLAPPED& overlapped
) const noexcept;

Parameters

segmentsFILE_SEGMENT_ELEMENT*

Array of page-sized, page-aligned buffers, terminated by a nullptr element; valid until the completion.

bytesToWriteDWORD

Total bytes to write; a multiple of the volume sector size.

overlappedOVERLAPPED&

File offset and completion state; must stay valid until the completion.

Return value

Type: ErrorCode

ERROR_SUCCESS if the write completed, ERROR_IO_PENDING if it is still running, or the Win32 error code.

Remarks

See also

Read

Null-terminated wide path (the W variants of the Win32 calls are used).

Syntax

using FileName = const wchar_t*;

Caller-owned output buffer for a path.

Syntax

using PathBuffer = wchar_t*;

File size or offset in bytes.

Syntax

using FileSize = unsigned long long;

Signed file pointer distance in bytes.

Syntax

using Distance = long long;