Interface ICompressionProvider

Defines the contract for a single-algorithm compression provider that is capable of compressing and decompressing data both in-memory (byte arrays) and through streams. Implementations in Scylla.Core.Util.Compression.Algorithms cover GZip, Deflate, and (when SCYLLA_HAS_SHARPZIPLIB is defined) BZip2 and Zip.

Namespace: Scylla.Core.Util.Compression
Assembly: ScyllaCore.dll
Syntax
public interface ICompressionProvider
Remarks

Providers are obtained by ScyllaCompression through an internal factory keyed on CompressionAlgorithm. Callers should use the ScyllaCompression static API rather than implementing or instantiating providers directly.

Providers that also support multi-file archive operations (currently only the ZIP provider) implement the extended IArchiveProvider interface. Use SupportsArchives to determine whether a provider can be cast to IArchiveProvider safely.

All methods that can fail throw CompressionException exclusively - system-level exceptions (e.g., IOException) are wrapped by the implementation using WrapIOException(Exception, string) before propagating.

Properties

Algorithm

Gets the CompressionAlgorithm value that this provider implements. Used internally by ScyllaCompression when selecting a provider for a given Algorithm value.

Declaration
CompressionAlgorithm Algorithm { get; }
Property Value
Type Description
CompressionAlgorithm

IsSupported

Gets a value indicating whether this provider can execute on the current platform and build configuration. A provider backed by an optional package (e.g., SharpZipLib) returns false when the package is not installed.

Declaration
bool IsSupported { get; }
Property Value
Type Description
bool

true if the provider is ready to use; false if calling any compression method would throw CompressionException with UnsupportedAlgorithm.

SupportsArchives

Gets a value indicating whether this provider additionally implements the IArchiveProvider interface and therefore supports multi-file archive creation and extraction.

Declaration
bool SupportsArchives { get; }
Property Value
Type Description
bool

true only for the ZIP provider. When true, this instance can be safely cast to IArchiveProvider to access folder-level operations.

Methods

Compress(byte[], CompressionLevel)

Compresses the provided byte array using this provider's algorithm and the specified compression level.

Declaration
byte[] Compress(byte[] data, CompressionLevel level)
Parameters
Type Name Description
byte[] data

The uncompressed input data. Must be non-null; an empty array is valid and returns an empty (or header-only) compressed buffer.
CompressionLevel level

The CompressionLevel controlling the speed/size trade-off.
Returns
Type Description
byte[]

A new byte array containing the compressed representation of data. The caller owns the returned buffer.
Exceptions
Type Condition
CompressionException

Thrown with an appropriate CompressionErrorCode when compression fails.

CompressAsync(byte[], CompressionLevel, CancellationToken)

Asynchronously compresses the provided byte array using this provider's algorithm and the specified compression level.

Declaration
Task<byte[]> CompressAsync(byte[] data, CompressionLevel level, CancellationToken cancellationToken = default)
Parameters
Type Name Description
byte[] data

The uncompressed input data. Must be non-null.
CompressionLevel level

The compression level.
CancellationToken cancellationToken

Token that can cancel the operation. On cancellation, a CompressionException with OperationCancelled is thrown.
Returns
Type Description
Task<byte[]>

A task whose result is a new byte array containing the compressed data.
Exceptions
Type Condition
CompressionException

Thrown with an appropriate CompressionErrorCode when compression fails.

CompressStream(Stream, Stream, CompressionLevel, int, IProgress<CompressionProgress>, CancellationToken)

Compresses data read from source and writes the compressed bytes to destination, optionally reporting progress and supporting cancellation.

Declaration
void CompressStream(Stream source, Stream destination, CompressionLevel level, int bufferSize, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
Stream source

A readable stream positioned at the first byte of uncompressed input data.
Stream destination

A writable stream that receives the compressed output. The stream is not closed by this method.
CompressionLevel level

The compression level.
int bufferSize

The I/O buffer size in bytes passed to CopyStreamWithProgress(Stream, Stream, int, long?, IProgress<CompressionProgress>, CancellationToken). Prefer values from CompressionSettings constants.
IProgress<CompressionProgress> progress

Optional callback that receives byte-level progress snapshots. May be null.
CancellationToken cancellationToken

Token checked between I/O chunks. On cancellation, a CompressionException with OperationCancelled is thrown.
Exceptions
Type Condition
CompressionException

Thrown with an appropriate CompressionErrorCode when compression fails.

CompressStreamAsync(Stream, Stream, CompressionLevel, int, IProgress<CompressionProgress>, CancellationToken)

Asynchronously compresses data read from source and writes the compressed bytes to destination.

Declaration
Task CompressStreamAsync(Stream source, Stream destination, CompressionLevel level, int bufferSize, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
Stream source

A readable stream positioned at the first byte of uncompressed input data.
Stream destination

A writable stream that receives the compressed output. Not closed by this method.
CompressionLevel level

The compression level.
int bufferSize

The I/O buffer size in bytes. Prefer values from CompressionSettings constants.
IProgress<CompressionProgress> progress

Optional callback that receives byte-level progress snapshots. May be null.
CancellationToken cancellationToken

Token checked between I/O chunks. On cancellation, a CompressionException with OperationCancelled is thrown.
Returns
Type Description
Task

A task that completes when all compressed data has been written.
Exceptions
Type Condition
CompressionException

Thrown with an appropriate CompressionErrorCode when compression fails.

Decompress(byte[])

Decompresses the provided byte array using this provider's algorithm.

Declaration
byte[] Decompress(byte[] compressedData)
Parameters
Type Name Description
byte[] compressedData

The compressed input data produced by a prior call to Compress(byte[], CompressionLevel) or by an external tool using the same algorithm. Must be non-null and well-formed.
Returns
Type Description
byte[]

A new byte array containing the decompressed (original) data. The caller owns the returned buffer.
Exceptions
Type Condition
CompressionException

Thrown with CorruptedData when the stream is malformed or truncated, or with another code for other failure conditions.

DecompressAsync(byte[], CancellationToken)

Asynchronously decompresses the provided byte array using this provider's algorithm.

Declaration
Task<byte[]> DecompressAsync(byte[] compressedData, CancellationToken cancellationToken = default)
Parameters
Type Name Description
byte[] compressedData

The compressed input data produced by a prior compression call or external tool. Must be non-null and well-formed.
CancellationToken cancellationToken

Token that can cancel the operation. On cancellation, a CompressionException with OperationCancelled is thrown.
Returns
Type Description
Task<byte[]>

A task whose result is a new byte array containing the decompressed data.
Exceptions
Type Condition
CompressionException

Thrown with an appropriate CompressionErrorCode when decompression fails.

DecompressStream(Stream, Stream, int, IProgress<CompressionProgress>, CancellationToken)

Decompresses data read from source and writes the decompressed bytes to destination, optionally reporting progress and supporting cancellation.

Declaration
void DecompressStream(Stream source, Stream destination, int bufferSize, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
Stream source

A readable stream containing compressed input data positioned at the first compressed byte.
Stream destination

A writable stream that receives the decompressed output. The stream is not closed by this method.
int bufferSize

The I/O buffer size in bytes. Prefer values from CompressionSettings constants.
IProgress<CompressionProgress> progress

Optional callback that receives byte-level progress snapshots. May be null.
CancellationToken cancellationToken

Token checked between I/O chunks. On cancellation, a CompressionException with OperationCancelled is thrown.
Exceptions
Type Condition
CompressionException

Thrown with an appropriate CompressionErrorCode when decompression fails.

DecompressStreamAsync(Stream, Stream, int, IProgress<CompressionProgress>, CancellationToken)

Asynchronously decompresses data read from source and writes the decompressed bytes to destination.

Declaration
Task DecompressStreamAsync(Stream source, Stream destination, int bufferSize, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
Stream source

A readable stream containing compressed input data positioned at the first byte.
Stream destination

A writable stream that receives the decompressed output. Not closed by this method.
int bufferSize

The I/O buffer size in bytes. Prefer values from CompressionSettings constants.
IProgress<CompressionProgress> progress

Optional callback that receives byte-level progress snapshots. May be null.
CancellationToken cancellationToken

Token checked between I/O chunks. On cancellation, a CompressionException with OperationCancelled is thrown.
Returns
Type Description
Task

A task that completes when all decompressed data has been written.
Exceptions
Type Condition
CompressionException

Thrown with an appropriate CompressionErrorCode when decompression fails.

Extension Methods

See Also