ScyllaCompression abstracts over multiple compression algorithms behind a unified, settings-driven API. It selects the appropriate internal provider based on the Algorithm value and delegates all work to that provider.

Available algorithms:

Algorithm	Availability and notes
GZip	Always available. Detectable magic header. Built-in CRC32 integrity check on decompression. Good general-purpose choice for single-data payloads.
Deflate	Always available. No header or integrity trailer - lowest overhead per payload. Not detectable by DetectAlgorithm(byte[]).
Zip	Requires `com.unity.sharp-zip-lib` (`SCYLLA_HAS_SHARPZIPLIB`). The only algorithm that supports multi-file archives and AES-256 encryption per entry.
BZip2	Requires `com.unity.sharp-zip-lib` (`SCYLLA_HAS_SHARPZIPLIB`). Better compression ratio than GZip, but slower. Good for archival payloads.

API surface categories:

Byte array: Compress, Decompress, TryDecompress and async variants - the simplest form for in-memory data.
Stream: CompressStream, DecompressStream and async variants - for large data that should not be fully buffered.
File: CompressFile, DecompressFile and async variants - convenience wrappers around the stream API.
Archive: CreateArchive, ExtractArchive, ListArchiveEntries, ExtractEntry and async variants - requires SCYLLA_HAS_SHARPZIPLIB.
Batch: CompressBatch, DecompressBatch and async variants - compresses or decompresses many byte arrays in parallel.
Crypto integration: CompressAndEncrypt, DecryptAndDecompress and async variants - combines compression with ScyllaCrypto encryption.

Global defaults: DefaultAlgorithm and DefaultLevel control which algorithm and level are used when null is passed as the CompressionSettings parameter. Overriding these affects all subsequent calls that rely on defaults, so they are best set once during application initialisation.

All methods that accept a CompressionSettings argument treat a null value as equivalent to constructing a new instance with DefaultAlgorithm and DefaultLevel.

Fields

DEFAULT_MAX_DECOMPRESSED_SIZE

The default ceiling applied to MaxDecompressedSize, equal to 268,435,456 bytes (256 MB).

Declaration

public const long DEFAULT_MAX_DECOMPRESSED_SIZE = 268435456

Field Value

Type	Description
long

Remarks

Chosen to sit far above any plausible single in-memory payload for a game (save data, a music log, a texture blob) while still bounding what a hostile input can allocate. A single decompressed buffer larger than this is unusual enough that opting in explicitly is the safer default.

Properties

DefaultAlgorithm

Gets or sets the compression algorithm used when null is passed as the CompressionSettings argument to any Compress or Decompress method. Defaults to GZip.

Declaration

public static CompressionAlgorithm DefaultAlgorithm { get; set; }

Property Value

Type	Description
CompressionAlgorithm

Remarks

Changing this property affects all subsequent calls that rely on the default settings. Set it once during application initialisation if a different algorithm is preferred throughout the project.

DefaultLevel

Gets or sets the compression level used when null is passed as the CompressionSettings argument to any Compress method. Defaults to Normal.

Declaration

public static CompressionLevel DefaultLevel { get; set; }

Property Value

Type	Description
CompressionLevel

Remarks

Changing this property affects all subsequent calls that rely on the default settings. Set it once during application initialisation if a different level is preferred throughout the project.

MaxDecompressedSize

Gets or sets the maximum number of bytes that any in-memory Decompress call may produce before it is aborted with DecompressedSizeExceeded. Defaults to DEFAULT_MAX_DECOMPRESSED_SIZE (256 MB).

Declaration

public static long MaxDecompressedSize { get; set; }

Property Value

Type	Description
long

Remarks

Compressed formats expand by design, and crafted input maximises that. A single GZip or Deflate layer tops out near 1030:1, so a few megabytes of hostile input decompresses to gigabytes; BZip2 reaches considerably higher ratios still. Without a ceiling, decompressing untrusted data (a downloaded archive, a user-supplied file, a network payload) can exhaust memory and terminate the process. The limit is enforced while the data streams out, so a hostile input is rejected long before it can be fully materialised.

The limit applies to every path that materialises decompressed data in memory: the byte-array Decompress family, ExtractEntry, and the per-entry buffering inside ExtractArchive. Pure stream-to-stream paths (DecompressStream and the file APIs built on it) write straight to a caller-supplied destination and are bounded by that destination instead.

Set to 0 or a negative value to disable the limit entirely. Do this only for data whose origin is trusted.

Methods

Compress(byte[])

Compresses byte array data using the default algorithm and settings.

Declaration

public static byte[] Compress(byte[] data)

Parameters

Type	Name	Description
byte[]	data	The data to compress.

Returns

Type	Description
byte[]	The compressed data.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

Compress(byte[], CompressionSettings)

Compresses byte array data using the specified settings.

Declaration

public static byte[] Compress(byte[] data, CompressionSettings settings)

Parameters

Type	Name	Description
byte[]	data	The data to compress.
CompressionSettings	settings	The compression settings. Uses defaults if null.

Returns

Type	Description
byte[]	The compressed data.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CompressAndEncrypt(byte[], string)

Compresses the data with default settings and then encrypts the compressed bytes using the given password via ScyllaCrypto. Compressing before encrypting yields better results because encrypted data is effectively random and incompressible.

Declaration

public static byte[] CompressAndEncrypt(byte[] data, string password)

Parameters

Type	Name	Description
byte[]	data	The plaintext data to compress and encrypt. Must not be `null`.
string	password	The encryption password. Must not be `null` or empty; an empty password throws CompressionException with InvalidPassword.

Returns

Type	Description
byte[]	The compressed-then-encrypted byte array.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails or `password` is `null`/empty.
CryptoException	Thrown when encryption fails.

CompressAndEncrypt(byte[], string, CompressionSettings, CryptoSettings)

Compresses the data with custom settings and then encrypts the compressed bytes using the given password. The intermediate compressed buffer is securely zeroed after encryption to limit its exposure in memory.

Declaration

public static byte[] CompressAndEncrypt(byte[] data, string password, CompressionSettings compressionSettings, CryptoSettings cryptoSettings)

Parameters

Type	Name	Description
byte[]	data	The plaintext data to compress and encrypt. Must not be `null`.
string	password	The encryption password. Must not be `null` or empty; an empty password throws CompressionException with InvalidPassword.
CompressionSettings	compressionSettings	Compression settings that control the algorithm and level. Pass `null` to use DefaultAlgorithm and DefaultLevel.
CryptoSettings	cryptoSettings	Encryption settings passed through to `ScyllaCrypto.Encrypt`. Pass `null` to use the crypto subsystem's own defaults.

Returns

Type	Description
byte[]	The compressed-then-encrypted byte array.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails or `password` is `null`/empty.
CryptoException	Thrown when encryption fails.

CompressAndEncryptAsync(byte[], string, CompressionSettings, CryptoSettings, CancellationToken)

Asynchronously compresses the data with custom settings and then encrypts the compressed bytes. The intermediate compressed buffer is securely zeroed after encryption.

Declaration

public static Task<byte[]> CompressAndEncryptAsync(byte[] data, string password, CompressionSettings compressionSettings, CryptoSettings cryptoSettings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
byte[]	data	The plaintext data to compress and encrypt. Must not be `null`.
string	password	The encryption password. Must not be `null` or empty.
CompressionSettings	compressionSettings	Compression settings. Pass `null` to use DefaultAlgorithm and DefaultLevel.
CryptoSettings	cryptoSettings	Encryption settings passed to `ScyllaCrypto.Encrypt`. Pass `null` for crypto defaults.
CancellationToken	cancellationToken	Optional token to cancel the compression step.

Returns

Type	Description
Task<byte[]>	A task that resolves to the compressed-then-encrypted byte array.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails or the password is empty.
CryptoException	Thrown when encryption fails.

CompressAndEncryptAsync(byte[], string, CancellationToken)

Asynchronously compresses the data using default settings and then encrypts the result using the given password. Equivalent to the synchronous CompressAndEncrypt(byte[], string) but offloads compression to the thread pool for BZip2 and ZIP providers.

Declaration

public static Task<byte[]> CompressAndEncryptAsync(byte[] data, string password, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
byte[]	data	The plaintext data to compress and encrypt. Must not be `null`.
string	password	The encryption password. Must not be `null` or empty.
CancellationToken	cancellationToken	Optional token to cancel the compression step.

Returns

Type	Description
Task<byte[]>	A task that resolves to the compressed-then-encrypted byte array.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails or the password is empty.
CryptoException	Thrown when encryption fails.

CompressAsync(byte[], CompressionSettings, CancellationToken)

Asynchronously compresses byte array data using the specified settings.

Declaration

public static Task<byte[]> CompressAsync(byte[] data, CompressionSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
byte[]	data	The data to compress.
CompressionSettings	settings	The compression settings. Uses defaults if null.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task<byte[]>	A task that represents the asynchronous operation containing the compressed data.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CompressAsync(byte[], CancellationToken)

Asynchronously compresses byte array data using the default algorithm and settings.

Declaration

public static Task<byte[]> CompressAsync(byte[] data, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
byte[]	data	The data to compress.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task<byte[]>	A task that represents the asynchronous operation containing the compressed data.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CompressBatch(byte[][])

Compresses multiple byte arrays in parallel. Useful for compressing many small assets simultaneously.

Declaration

public static byte[][] CompressBatch(byte[][] dataArrays)

Parameters

Type	Name	Description
byte[][]	dataArrays	The array of data arrays to compress.

Returns

Type	Description
byte[][]	An array of compressed data arrays in the same order as input.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CompressBatch(byte[][], CompressionSettings)

Compresses multiple byte arrays in parallel using the specified settings.

Declaration

public static byte[][] CompressBatch(byte[][] dataArrays, CompressionSettings settings)

Parameters

Type	Name	Description
byte[][]	dataArrays	The array of data arrays to compress.
CompressionSettings	settings	The compression settings. Uses defaults if null.

Returns

Type	Description
byte[][]	An array of compressed data arrays in the same order as input.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CompressBatchAsync(byte[][], CompressionSettings, CancellationToken)

Asynchronously compresses multiple byte arrays in parallel using the specified settings.

Declaration

public static Task<byte[][]> CompressBatchAsync(byte[][] dataArrays, CompressionSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
byte[][]	dataArrays	The array of data arrays to compress.
CompressionSettings	settings	The compression settings. Uses defaults if null.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task<byte[][]>	A task that represents the asynchronous operation containing the compressed data arrays.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CompressBatchAsync(byte[][], CancellationToken)

Asynchronously compresses multiple byte arrays in parallel. Useful for compressing many small assets simultaneously.

Declaration

public static Task<byte[][]> CompressBatchAsync(byte[][] dataArrays, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
byte[][]	dataArrays	The array of data arrays to compress.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task<byte[][]>	A task that represents the asynchronous operation containing the compressed data arrays.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CompressFile(string, string)

Compresses a file to a new file path.

Declaration

public static void CompressFile(string sourcePath, string destinationPath)

Parameters

Type	Name	Description
string	sourcePath	The path to the source file.
string	destinationPath	The path for the compressed file.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CompressFile(string, string, CompressionSettings, IProgress<CompressionProgress>, CancellationToken)

Compresses a file to a new file path with progress reporting.

Declaration

public static void CompressFile(string sourcePath, string destinationPath, CompressionSettings settings, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	sourcePath	The path to the source file.
string	destinationPath	The path for the compressed file.
CompressionSettings	settings	The compression settings. Uses defaults if null.
IProgress<CompressionProgress>	progress	Optional progress callback.
CancellationToken	cancellationToken	Optional cancellation token.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CompressFileAsync(string, string, CompressionSettings, IProgress<CompressionProgress>, CancellationToken)

Asynchronously compresses a file to a new file path with progress reporting.

Declaration

public static Task CompressFileAsync(string sourcePath, string destinationPath, CompressionSettings settings, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	sourcePath	The path to the source file.
string	destinationPath	The path for the compressed file.
CompressionSettings	settings	The compression settings. Uses defaults if null.
IProgress<CompressionProgress>	progress	Optional progress callback.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CompressFileAsync(string, string, CancellationToken)

Asynchronously compresses a file to a new file path.

Declaration

public static Task CompressFileAsync(string sourcePath, string destinationPath, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	sourcePath	The path to the source file.
string	destinationPath	The path for the compressed file.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CompressStream(Stream, Stream)

Compresses data from source stream to destination stream.

Declaration

public static void CompressStream(Stream source, Stream destination)

Parameters

Type	Name	Description
Stream	source	The source stream containing uncompressed data.
Stream	destination	The destination stream for compressed data.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CompressStream(Stream, Stream, CompressionSettings, IProgress<CompressionProgress>, CancellationToken)

Compresses data from source stream to destination stream with progress reporting.

Declaration

public static void CompressStream(Stream source, Stream destination, CompressionSettings settings, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Stream	source	The source stream containing uncompressed data.
Stream	destination	The destination stream for compressed data.
CompressionSettings	settings	The compression settings. Uses defaults if null.
IProgress<CompressionProgress>	progress	Optional progress callback.
CancellationToken	cancellationToken	Optional cancellation token.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CompressStreamAsync(Stream, Stream, CompressionSettings, IProgress<CompressionProgress>, CancellationToken)

Asynchronously compresses data from source stream to destination stream with progress reporting.

Declaration

public static Task CompressStreamAsync(Stream source, Stream destination, CompressionSettings settings, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Stream	source	The source stream containing uncompressed data.
Stream	destination	The destination stream for compressed data.
CompressionSettings	settings	The compression settings. Uses defaults if null.
IProgress<CompressionProgress>	progress	Optional progress callback.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CompressStreamAsync(Stream, Stream, CancellationToken)

Asynchronously compresses data from source stream to destination stream.

Declaration

public static Task CompressStreamAsync(Stream source, Stream destination, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Stream	source	The source stream containing uncompressed data.
Stream	destination	The destination stream for compressed data.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Exceptions

Type	Condition
CompressionException	Thrown when compression fails.

CreateArchive(string, string)

Creates a ZIP archive from a folder.

Declaration

public static void CreateArchive(string sourceFolderPath, string archivePath)

Parameters

Type	Name	Description
string	sourceFolderPath	The path to the folder to compress.
string	archivePath	The path where the archive will be created.

Exceptions

Type	Condition
CompressionException	Thrown when archive creation fails.

CreateArchive(string, string, CompressionSettings, IProgress<CompressionProgress>, CancellationToken)

Creates a ZIP archive from a folder with progress reporting.

Declaration

public static void CreateArchive(string sourceFolderPath, string archivePath, CompressionSettings settings, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	sourceFolderPath	The path to the folder to compress.
string	archivePath	The path where the archive will be created.
CompressionSettings	settings	The compression settings. Uses defaults if null.
IProgress<CompressionProgress>	progress	Optional progress callback.
CancellationToken	cancellationToken	Optional cancellation token.

Exceptions

Type	Condition
CompressionException	Thrown when archive creation fails.

CreateArchiveAsync(string, string, CompressionSettings, IProgress<CompressionProgress>, CancellationToken)

Asynchronously creates a ZIP archive from a folder with progress reporting.

Declaration

public static Task CreateArchiveAsync(string sourceFolderPath, string archivePath, CompressionSettings settings, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	sourceFolderPath	The path to the folder to compress.
string	archivePath	The path where the archive will be created.
CompressionSettings	settings	The compression settings. Uses defaults if null.
IProgress<CompressionProgress>	progress	Optional progress callback.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Exceptions

Type	Condition
CompressionException	Thrown when archive creation fails.

CreateArchiveAsync(string, string, CancellationToken)

Asynchronously creates a ZIP archive from a folder.

Declaration

public static Task CreateArchiveAsync(string sourceFolderPath, string archivePath, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	sourceFolderPath	The path to the folder to compress.
string	archivePath	The path where the archive will be created.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Exceptions

Type	Condition
CompressionException	Thrown when archive creation fails.

Decompress(byte[])

Decompresses byte array data using the default algorithm.

Declaration

public static byte[] Decompress(byte[] compressedData)

Parameters

Type	Name	Description
byte[]	compressedData	The compressed data to decompress.

Returns

Type	Description
byte[]	The decompressed data.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

Decompress(byte[], CompressionSettings)

Decompresses byte array data using the specified settings.

Declaration

public static byte[] Decompress(byte[] compressedData, CompressionSettings settings)

Parameters

Type	Name	Description
byte[]	compressedData	The compressed data to decompress.
CompressionSettings	settings	The compression settings. Uses defaults if null.

Returns

Type	Description
byte[]	The decompressed data.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

DecompressAsync(byte[], CompressionSettings, CancellationToken)

Asynchronously decompresses byte array data using the specified settings.

Declaration

public static Task<byte[]> DecompressAsync(byte[] compressedData, CompressionSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
byte[]	compressedData	The compressed data to decompress.
CompressionSettings	settings	The compression settings. Uses defaults if null.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task<byte[]>	A task that represents the asynchronous operation containing the decompressed data.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

DecompressAsync(byte[], CancellationToken)

Asynchronously decompresses byte array data using the default algorithm.

Declaration

public static Task<byte[]> DecompressAsync(byte[] compressedData, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
byte[]	compressedData	The compressed data to decompress.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task<byte[]>	A task that represents the asynchronous operation containing the decompressed data.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

DecompressBatch(byte[][])

Decompresses multiple byte arrays in parallel.

Declaration

public static byte[][] DecompressBatch(byte[][] compressedArrays)

Parameters

Type	Name	Description
byte[][]	compressedArrays	The array of compressed data arrays to decompress.

Returns

Type	Description
byte[][]	An array of decompressed data arrays in the same order as input.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

DecompressBatch(byte[][], CompressionSettings)

Decompresses multiple byte arrays in parallel using the specified settings.

Declaration

public static byte[][] DecompressBatch(byte[][] compressedArrays, CompressionSettings settings)

Parameters

Type	Name	Description
byte[][]	compressedArrays	The array of compressed data arrays to decompress.
CompressionSettings	settings	The compression settings. Uses defaults if null.

Returns

Type	Description
byte[][]	An array of decompressed data arrays in the same order as input.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

DecompressBatchAsync(byte[][], CompressionSettings, CancellationToken)

Asynchronously decompresses multiple byte arrays in parallel using the specified settings.

Declaration

public static Task<byte[][]> DecompressBatchAsync(byte[][] compressedArrays, CompressionSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
byte[][]	compressedArrays	The array of compressed data arrays to decompress.
CompressionSettings	settings	The compression settings. Uses defaults if null.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task<byte[][]>	A task that represents the asynchronous operation containing the decompressed data arrays.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

DecompressBatchAsync(byte[][], CancellationToken)

Asynchronously decompresses multiple byte arrays in parallel.

Declaration

public static Task<byte[][]> DecompressBatchAsync(byte[][] compressedArrays, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
byte[][]	compressedArrays	The array of compressed data arrays to decompress.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task<byte[][]>	A task that represents the asynchronous operation containing the decompressed data arrays.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

DecompressFile(string, string)

Decompresses a file to a new file path.

Declaration

public static void DecompressFile(string sourcePath, string destinationPath)

Parameters

Type	Name	Description
string	sourcePath	The path to the compressed file.
string	destinationPath	The path for the decompressed file.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

DecompressFile(string, string, CompressionSettings, IProgress<CompressionProgress>, CancellationToken)

Decompresses a file to a new file path with progress reporting.

Declaration

public static void DecompressFile(string sourcePath, string destinationPath, CompressionSettings settings, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	sourcePath	The path to the compressed file.
string	destinationPath	The path for the decompressed file.
CompressionSettings	settings	The compression settings. Uses defaults if null.
IProgress<CompressionProgress>	progress	Optional progress callback.
CancellationToken	cancellationToken	Optional cancellation token.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

DecompressFileAsync(string, string, CompressionSettings, IProgress<CompressionProgress>, CancellationToken)

Asynchronously decompresses a file to a new file path with progress reporting.

Declaration

public static Task DecompressFileAsync(string sourcePath, string destinationPath, CompressionSettings settings, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	sourcePath	The path to the compressed file.
string	destinationPath	The path for the decompressed file.
CompressionSettings	settings	The compression settings. Uses defaults if null.
IProgress<CompressionProgress>	progress	Optional progress callback.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

DecompressFileAsync(string, string, CancellationToken)

Asynchronously decompresses a file to a new file path.

Declaration

public static Task DecompressFileAsync(string sourcePath, string destinationPath, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	sourcePath	The path to the compressed file.
string	destinationPath	The path for the decompressed file.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

DecompressStream(Stream, Stream)

Decompresses data from source stream to destination stream.

Declaration

public static void DecompressStream(Stream source, Stream destination)

Parameters

Type	Name	Description
Stream	source	The source stream containing compressed data.
Stream	destination	The destination stream for decompressed data.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

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

Decompresses data from source stream to destination stream with progress reporting.

Declaration

public static void DecompressStream(Stream source, Stream destination, CompressionSettings settings, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Stream	source	The source stream containing compressed data.
Stream	destination	The destination stream for decompressed data.
CompressionSettings	settings	The compression settings. Uses defaults if null.
IProgress<CompressionProgress>	progress	Optional progress callback.
CancellationToken	cancellationToken	Optional cancellation token.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

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

Asynchronously decompresses data from source stream to destination stream with progress reporting.

Declaration

public static Task DecompressStreamAsync(Stream source, Stream destination, CompressionSettings settings, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Stream	source	The source stream containing compressed data.
Stream	destination	The destination stream for decompressed data.
CompressionSettings	settings	The compression settings. Uses defaults if null.
IProgress<CompressionProgress>	progress	Optional progress callback.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

DecompressStreamAsync(Stream, Stream, CancellationToken)

Asynchronously decompresses data from source stream to destination stream.

Declaration

public static Task DecompressStreamAsync(Stream source, Stream destination, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Stream	source	The source stream containing compressed data.
Stream	destination	The destination stream for decompressed data.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Exceptions

Type	Condition
CompressionException	Thrown when decompression fails.

DecryptAndDecompress(byte[], string)

Decrypts the data using the given password and then decompresses the result. This is the exact reverse of CompressAndEncrypt(byte[], string).

Declaration

public static byte[] DecryptAndDecompress(byte[] data, string password)

Parameters

Type	Name	Description
byte[]	data	The encrypted and compressed data to process. Must not be `null`.
string	password	The decryption password. Must not be `null` or empty; an empty password throws CompressionException with InvalidPassword.

Returns

Type	Description
byte[]	The decrypted and decompressed plaintext byte array.

Exceptions

Type	Condition
CryptoException	Thrown when decryption fails (e.g., wrong password).
CompressionException	Thrown when decompression of the decrypted bytes fails.

DecryptAndDecompress(byte[], string, CompressionSettings, CryptoSettings)

Decrypts the data using custom settings and then decompresses the plaintext. The intermediate decrypted buffer is securely zeroed after decompression to limit its exposure in memory.

Declaration

public static byte[] DecryptAndDecompress(byte[] data, string password, CompressionSettings compressionSettings, CryptoSettings cryptoSettings)

Parameters

Type	Name	Description
byte[]	data	The encrypted and compressed data to process. Must not be `null`.
string	password	The decryption password. Must not be `null` or empty; an empty password throws CompressionException with InvalidPassword.
CompressionSettings	compressionSettings	Compression settings that determine the algorithm used for decompression. Must match the settings used when the data was originally compressed. Pass `null` to use DefaultAlgorithm.
CryptoSettings	cryptoSettings	Decryption settings passed through to `ScyllaCrypto.Decrypt`. Pass `null` to use the crypto subsystem's own defaults.

Returns

Type	Description
byte[]	The decrypted and decompressed plaintext byte array.

Exceptions

Type	Condition
CryptoException	Thrown when decryption fails (e.g., wrong password).
CompressionException	Thrown when decompression of the decrypted bytes fails.

DecryptAndDecompressAsync(byte[], string, CompressionSettings, CryptoSettings, CancellationToken)

Asynchronously decrypts the data with custom settings and then decompresses the plaintext. The intermediate decrypted buffer is securely zeroed after decompression.

Declaration

public static Task<byte[]> DecryptAndDecompressAsync(byte[] data, string password, CompressionSettings compressionSettings, CryptoSettings cryptoSettings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
byte[]	data	The encrypted and compressed data. Must not be `null`.
string	password	The decryption password. Must not be `null` or empty.
CompressionSettings	compressionSettings	Compression settings that determine the algorithm used for decompression. Must match the settings used when the data was originally compressed. Pass `null` to use DefaultAlgorithm.
CryptoSettings	cryptoSettings	Decryption settings passed to `ScyllaCrypto.Decrypt`. Pass `null` for crypto defaults.
CancellationToken	cancellationToken	Optional token to cancel the decompression step.

Returns

Type	Description
Task<byte[]>	A task that resolves to the decrypted and decompressed plaintext byte array.

Exceptions

Type	Condition
CryptoException	Thrown when decryption fails.
CompressionException	Thrown when decompression fails or the password is empty.

DecryptAndDecompressAsync(byte[], string, CancellationToken)

Asynchronously decrypts the data using the given password and then decompresses the result using default settings. Equivalent to DecryptAndDecompress(byte[], string) but offloads decompression to the thread pool for BZip2 and ZIP providers.

Declaration

public static Task<byte[]> DecryptAndDecompressAsync(byte[] data, string password, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
byte[]	data	The encrypted and compressed data. Must not be `null`.
string	password	The decryption password. Must not be `null` or empty.
CancellationToken	cancellationToken	Optional token to cancel the decompression step.

Returns

Type	Description
Task<byte[]>	A task that resolves to the decrypted and decompressed plaintext byte array.

Exceptions

Type	Condition
CryptoException	Thrown when decryption fails.
CompressionException	Thrown when decompression fails or the password is empty.

DetectAlgorithm(byte[])

Attempts to identify the compression algorithm of the given byte array by inspecting its magic-number header bytes.

Declaration

public static CompressionAlgorithm? DetectAlgorithm(byte[] compressedData)

Parameters

Type	Name	Description
byte[]	compressedData	The compressed data to analyse. May be `null` or shorter than expected.

Returns

Type Description

CompressionAlgorithm?

The detected CompressionAlgorithm, or null when the algorithm cannot be determined. Specifically:

GZip - when the first two bytes are 0x1F 0x8B.
Zip - when the first four bytes are 0x50 0x4B 0x03 0x04 (requires SCYLLA_HAS_SHARPZIPLIB).
BZip2 - when the first three bytes are 0x42 0x5A 0x68 (requires SCYLLA_HAS_SHARPZIPLIB).
null - for raw Deflate (no magic number), null/empty input, or any unrecognised byte sequence.

ExtractArchive(string, string)

Extracts a ZIP archive to a folder.

Declaration

public static void ExtractArchive(string archivePath, string destinationFolderPath)

Parameters

Type	Name	Description
string	archivePath	The path to the archive to extract.
string	destinationFolderPath	The path where files will be extracted.

Exceptions

Type	Condition
CompressionException	Thrown when extraction fails.

ExtractArchive(string, string, CompressionSettings, IProgress<CompressionProgress>, CancellationToken)

Extracts a ZIP archive to a folder with progress reporting.

Declaration

public static void ExtractArchive(string archivePath, string destinationFolderPath, CompressionSettings settings, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	archivePath	The path to the archive to extract.
string	destinationFolderPath	The path where files will be extracted.
CompressionSettings	settings	The compression settings. Uses defaults if null.
IProgress<CompressionProgress>	progress	Optional progress callback.
CancellationToken	cancellationToken	Optional cancellation token.

Exceptions

Type	Condition
CompressionException	Thrown when extraction fails.

ExtractArchiveAsync(string, string, CompressionSettings, IProgress<CompressionProgress>, CancellationToken)

Asynchronously extracts a ZIP archive to a folder with progress reporting.

Declaration

public static Task ExtractArchiveAsync(string archivePath, string destinationFolderPath, CompressionSettings settings, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	archivePath	The path to the archive to extract.
string	destinationFolderPath	The path where files will be extracted.
CompressionSettings	settings	The compression settings. Uses defaults if null.
IProgress<CompressionProgress>	progress	Optional progress callback.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Exceptions

Type	Condition
CompressionException	Thrown when extraction fails.

ExtractArchiveAsync(string, string, CancellationToken)

Asynchronously extracts a ZIP archive to a folder.

Declaration

public static Task ExtractArchiveAsync(string archivePath, string destinationFolderPath, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	archivePath	The path to the archive to extract.
string	destinationFolderPath	The path where files will be extracted.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Exceptions

Type	Condition
CompressionException	Thrown when extraction fails.

ExtractEntry(string, string)

Extracts a single entry from a ZIP archive to a byte array.

Declaration

public static byte[] ExtractEntry(string archivePath, string entryPath)

Parameters

Type	Name	Description
string	archivePath	The path to the archive.
string	entryPath	The path of the entry within the archive.

Returns

Type	Description
byte[]	The decompressed entry data.

Exceptions

Type	Condition
CompressionException	Thrown when extraction fails.

ExtractEntry(string, string, string)

Extracts a single entry from a ZIP archive to a file.

Declaration

public static void ExtractEntry(string archivePath, string entryPath, string destinationPath)

Parameters

Type	Name	Description
string	archivePath	The path to the archive.
string	entryPath	The path of the entry within the archive.
string	destinationPath	The destination file path.

Exceptions

Type	Condition
CompressionException	Thrown when extraction fails.

ExtractEntry(string, string, string, CompressionSettings)

Extracts a single entry from a ZIP archive to a file with settings.

Declaration

public static void ExtractEntry(string archivePath, string entryPath, string destinationPath, CompressionSettings settings)

Parameters

Type	Name	Description
string	archivePath	The path to the archive.
string	entryPath	The path of the entry within the archive.
string	destinationPath	The destination file path.
CompressionSettings	settings	The compression settings. Uses defaults if null.

Exceptions

Type	Condition
CompressionException	Thrown when extraction fails.

ExtractEntryAsync(string, string, string, CompressionSettings, CancellationToken)

Asynchronously extracts a single entry from a ZIP archive to a file with settings.

Declaration

public static Task ExtractEntryAsync(string archivePath, string entryPath, string destinationPath, CompressionSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	archivePath	The path to the archive.
string	entryPath	The path of the entry within the archive.
string	destinationPath	The destination file path.
CompressionSettings	settings	The compression settings. Uses defaults if null.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Exceptions

Type	Condition
CompressionException	Thrown when extraction fails.

ExtractEntryAsync(string, string, string, CancellationToken)

Asynchronously extracts a single entry from a ZIP archive to a file.

Declaration

public static Task ExtractEntryAsync(string archivePath, string entryPath, string destinationPath, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	archivePath	The path to the archive.
string	entryPath	The path of the entry within the archive.
string	destinationPath	The destination file path.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task	A task that represents the asynchronous operation.

Exceptions

Type	Condition
CompressionException	Thrown when extraction fails.

ExtractEntryAsync(string, string, CancellationToken)

Asynchronously extracts a single entry from a ZIP archive to a byte array.

Declaration

public static Task<byte[]> ExtractEntryAsync(string archivePath, string entryPath, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	archivePath	The path to the archive.
string	entryPath	The path of the entry within the archive.
CancellationToken	cancellationToken	Optional cancellation token.

Returns

Type	Description
Task<byte[]>	A task that represents the asynchronous operation containing the decompressed entry data.

Exceptions

Type	Condition
CompressionException	Thrown when extraction fails.

GetFileExtension(CompressionAlgorithm)

Returns the conventional file extension associated with the given compression algorithm, including the leading dot.

Declaration

public static string GetFileExtension(CompressionAlgorithm algorithm)

Parameters

Type	Name	Description
CompressionAlgorithm	algorithm	The compression algorithm for which to retrieve the extension.

Returns

Type Description

string

Algorithm	Extension returned
GZip	`".gz"`
Deflate	`".deflate"`
Zip	`".zip"`
BZip2	`".bz2"`
(unknown)	`".compressed"`

IsAlgorithmSupported(CompressionAlgorithm)

Returns a value indicating whether the given compression algorithm is available and can be used on the current platform and package configuration.

Declaration

public static bool IsAlgorithmSupported(CompressionAlgorithm algorithm)

Parameters

Type	Name	Description
CompressionAlgorithm	algorithm	The algorithm to check.

Returns

Type	Description
bool	`true` if a provider for `algorithm` exists and its IsSupported property returns `true`; `false` if the algorithm is unknown or requires an optional package (e.g., `SCYLLA_HAS_SHARPZIPLIB`) that is not installed.

ListArchiveEntries(string)

Lists all entries in a ZIP archive.

Declaration

public static IReadOnlyList<ArchiveEntryInfo> ListArchiveEntries(string archivePath)

Parameters

Type	Name	Description
string	archivePath	The path to the archive.

Returns

Type	Description
IReadOnlyList<ArchiveEntryInfo>	A read-only list of archive entry information.

Exceptions

Type	Condition
CompressionException	Thrown when reading the archive fails.

TryDecompress(byte[], CompressionSettings, out byte[])

Attempts to decompress the given data using the provided settings, returning false instead of throwing a CompressionException if decompression fails.

Declaration

public static bool TryDecompress(byte[] compressedData, CompressionSettings settings, out byte[] data)

Parameters

Type	Name	Description
byte[]	compressedData	The compressed data to decompress. May be `null`.
CompressionSettings	settings	The compression settings that determine the algorithm. Pass `null` to use DefaultAlgorithm and DefaultLevel.
byte[]	data	When this method returns `true`, contains the decompressed byte array. When this method returns `false`, the value is `null`.

Returns

Type	Description
bool	`true` if decompression succeeded and `data` holds the result; `false` if any CompressionException was caught.

TryDecompress(byte[], out byte[])

Attempts to decompress the given data using default settings, returning false instead of throwing a CompressionException if decompression fails.

Declaration

public static bool TryDecompress(byte[] compressedData, out byte[] data)

Parameters

Type	Name	Description
byte[]	compressedData	The compressed data to decompress. May be `null`.
byte[]	data	When this method returns `true`, contains the decompressed byte array. When this method returns `false`, the value is `null`.

Returns

Type	Description
bool	`true` if decompression succeeded and `data` holds the result; `false` if any CompressionException was caught, for example because the data is corrupted, `null`, or was compressed with a different algorithm.