Struct FileProgress

An immutable, value-type snapshot of progress for an in-flight file I/O operation. Instances of this struct are passed to IProgress<FileProgress> callbacks by ScyllaFileUtil async methods to report how many bytes have been transferred.

Inherited Members
Namespace: Scylla.Core.Util.File
Assembly: ScyllaCore.dll
Syntax
public readonly struct FileProgress
Remarks

Because FileProgress is a readonly struct, it is safe to capture or store callbacks without defensive copies. Each report is a self-contained snapshot; fields do not change after construction.

When the total byte count is not known in advance (for example, when reading from a stream that does not expose its length), TotalBytes is set to -1 and PercentComplete returns -1. Always check PercentComplete before using its value in progress bar calculations.

Constructors

FileProgress(long, long)

Initializes a new instance of the FileProgress struct with byte counts only. Both FilePath and Operation are set to null. Use this minimal overload for simple single-file transfers where the path and operation label are already known to the callback consumer.

Declaration
public FileProgress(long bytesProcessed, long totalBytes)
Parameters
Type Name Description
long bytesProcessed

The cumulative number of bytes transferred so far. Must be zero or greater.
long totalBytes

The total number of bytes to transfer, or -1 when the total is not known. Passing 0 or a negative value other than -1 also causes PercentComplete to return -1.

FileProgress(long, long, string)

Initializes a new instance of the FileProgress struct with byte counts and the path of the file being processed. Operation is set to null. Use this overload in multi-file operations where the callback must identify which file is currently active.

Declaration
public FileProgress(long bytesProcessed, long totalBytes, string filePath)
Parameters
Type Name Description
long bytesProcessed

The cumulative number of bytes transferred so far. Must be zero or greater.
long totalBytes

The total number of bytes to transfer, or -1 when the total is not known.
string filePath

The file system path of the file being processed. May be null if not applicable; the value is stored as-is in FilePath.

FileProgress(long, long, string, string)

Initializes a new instance of the FileProgress struct with full details, including byte counts, file path, and operation label. This is the most complete overload and is typically used by ScyllaFileUtil internally when reporting progress to caller-supplied IProgress<FileProgress> instances.

Declaration
public FileProgress(long bytesProcessed, long totalBytes, string filePath, string operation)
Parameters
Type Name Description
long bytesProcessed

The cumulative number of bytes transferred so far. Must be zero or greater.
long totalBytes

The total number of bytes to transfer, or -1 when the total is not known.
string filePath

The file system path of the file being processed, or null if not applicable.
string operation

A short label for the current operation phase, such as "Reading", "Writing", or "Copying". Pass null to suppress the label; ToString() will substitute "Progress" in that case.

Properties

BytesProcessed

Gets the cumulative number of bytes that have been transferred by the operation at the point this snapshot was captured. The value is always zero or greater.

Declaration
public long BytesProcessed { get; }
Property Value
Type Description
long

A non-negative long representing the bytes transferred so far. On the final progress report this value equals TotalBytes when TotalBytes is known.

FilePath

Gets the file system path of the file currently being processed, or null if the path was not provided when this snapshot was created.

Declaration
public string FilePath { get; }
Property Value
Type Description
string

An absolute or relative path string, or null. Useful for multi-file operations where the callback must identify which file is progressing.

IsComplete

Gets a value indicating whether the operation has finished transferring all bytes. Returns false when TotalBytes is unknown, since completion cannot be confirmed without a known total.

Declaration
public bool IsComplete { get; }
Property Value
Type Description
bool

true if TotalBytes is greater than zero and BytesProcessed has reached or exceeded it; false otherwise.

Operation

Gets a short human-readable label for the current operation phase, or null if not specified. Typical values are "Reading", "Writing", and "Copying", as used internally by ScyllaFileUtil.

Declaration
public string Operation { get; }
Property Value
Type Description
string

A non-empty operation name string, or null when the two-parameter constructors are used. ToString() substitutes "Progress" when this value is null.

PercentComplete

Gets the completion percentage in the range [0, 100], or -1 when TotalBytes is unknown (-1 or zero).

Declaration
public double PercentComplete { get; }
Property Value
Type Description
double

A double in the range 0.0 to 100.0 inclusive, or -1.0 when no total is available. Use -1 as a sentinel to display an indeterminate progress bar rather than a percentage.

TotalBytes

Gets the total number of bytes to be transferred during the entire operation. Set to -1 when the total size cannot be determined in advance (for example, when reading from a non-seekable stream).

Declaration
public long TotalBytes { get; }
Property Value
Type Description
long

A positive long representing the expected total, or -1 if the total is unknown. Always verify this value is positive before computing a fraction or percentage.

Methods

ToString()

Returns a human-readable summary of the current progress state. The format varies depending on whether TotalBytes is known.

Declaration
public override string ToString()
Returns
Type Description
string

When TotalBytes is greater than zero, a string of the form "Reading: 65,536 / 1,048,576 bytes (6.3%)". When the total is unknown, a string of the form "Reading: 65,536 bytes". The operation label is substituted with "Progress" when Operation is null.
Overrides

See Also