Interface IArchiveProvider

Extends ICompressionProvider with operations that work on multi-file archives such as ZIP files, including folder-level compression and extraction, entry enumeration, and single-entry extraction.

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

Currently only the ZIP provider (available when SCYLLA_HAS_SHARPZIPLIB is defined) implements this interface. Check SupportsArchives before casting a provider to IArchiveProvider.

Archive operations are governed by CompressionSettings. Key settings that affect archive behavior:

  • Password - enables AES-256 encryption on all entries when creating, or decrypts entries when extracting.
  • OverwriteExisting - controls whether existing destination files are replaced during extraction.
  • IncludeEmptyDirectories - controls whether empty directory entries are written to the archive.
  • FileFilter - wildcard pattern restricting which files are added from the source folder.

All methods that can fail throw CompressionException exclusively. Async variants are provided for all operations that touch the file system. ListEntries(string) has no async variant because it typically reads only the archive's central directory, which is fast.

Methods

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

Compresses all files (and optionally empty directories) within sourceFolderPath into a new archive at archivePath. Respects FileFilter, IncludeEmptyDirectories, PreserveTimestamps, and Password.

Declaration
void CreateArchive(string sourceFolderPath, string archivePath, CompressionSettings settings, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string sourceFolderPath

Absolute or relative path to the directory whose contents will be archived. Must exist and be readable; throws CompressionException with FileNotFound otherwise.
string archivePath

The full path (including filename and extension) of the archive to create. The parent directory must already exist.
CompressionSettings settings

Settings that control compression level, password, filters, and parallelism. Must not be null.
IProgress<CompressionProgress> progress

Optional callback that receives file-level and byte-level progress updates. May be null.
CancellationToken cancellationToken

Token that cancels the operation between file additions. A CompressionException with OperationCancelled is thrown on cancellation.
Exceptions
Type Condition
CompressionException

Thrown with an appropriate CompressionErrorCode when the operation fails.

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

Asynchronously compresses all files within sourceFolderPath into a new archive at archivePath. This is the async counterpart of CreateArchive(string, string, CompressionSettings, IProgress<CompressionProgress>, CancellationToken).

Declaration
Task CreateArchiveAsync(string sourceFolderPath, string archivePath, CompressionSettings settings, IProgress<CompressionProgress> progress = null, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string sourceFolderPath

Path to the directory to archive. Must exist and be readable.
string archivePath

The full path of the archive to create.
CompressionSettings settings

Settings controlling compression, password, and filtering. Must not be null.
IProgress<CompressionProgress> progress

Optional callback for file-level and byte-level progress. May be null.
CancellationToken cancellationToken

Token that cancels the operation between file additions. On cancellation, a CompressionException with OperationCancelled is thrown.
Returns
Type Description
Task

A task that completes when the archive has been fully created.
Exceptions
Type Condition
CompressionException

Thrown with an appropriate CompressionErrorCode when the operation fails.

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

Extracts all entries in the archive at archivePath to destinationFolderPath, recreating the original directory structure. Respects OverwriteExisting and Password.

Declaration
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 existing archive file. Must exist and be a valid archive; throws CompressionException with FileNotFound or CorruptedData otherwise.
string destinationFolderPath

The root directory into which entries are extracted. Created if it does not exist.
CompressionSettings settings

Settings that control overwrite behaviour and the password for encrypted archives. Must not be null.
IProgress<CompressionProgress> progress

Optional callback that receives file-level and byte-level progress updates. May be null.
CancellationToken cancellationToken

Token that cancels the operation between file extractions. A CompressionException with OperationCancelled is thrown on cancellation.
Exceptions
Type Condition
CompressionException

Thrown with an appropriate CompressionErrorCode when extraction fails.

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

Asynchronously extracts all entries in the archive at archivePath to destinationFolderPath. This is the async counterpart of ExtractArchive(string, string, CompressionSettings, IProgress<CompressionProgress>, CancellationToken).

Declaration
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 existing archive file.
string destinationFolderPath

The root directory into which entries are extracted.
CompressionSettings settings

Settings controlling overwrite behaviour and password. Must not be null.
IProgress<CompressionProgress> progress

Optional callback for file-level and byte-level progress. May be null.
CancellationToken cancellationToken

Token that cancels the operation between file extractions. On cancellation, a CompressionException with OperationCancelled is thrown.
Returns
Type Description
Task

A task that completes when all entries have been extracted.
Exceptions
Type Condition
CompressionException

Thrown with an appropriate CompressionErrorCode when extraction fails.

ExtractEntry(string, string)

Extracts and decompresses a single entry from an archive and returns its data as a byte array, without writing anything to the file system.

Declaration
byte[] ExtractEntry(string archivePath, string entryPath)
Parameters
Type Name Description
string archivePath

The path to the archive file containing the entry.
string entryPath

The full path of the entry within the archive as returned by FullPath (e.g., "assets/textures/hero.png").
Returns
Type Description
byte[]

A byte array containing the fully decompressed entry data. The caller owns the returned buffer.
Exceptions
Type Condition
CompressionException

Thrown with EntryNotFound when the entry does not exist in the archive, or another code on other failures.

ExtractEntryAsync(string, string, CancellationToken)

Asynchronously extracts and decompresses a single entry from an archive and returns its data as a byte array. This is the async counterpart of ExtractEntry(string, string).

Declaration
Task<byte[]> ExtractEntryAsync(string archivePath, string entryPath, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string archivePath

The path to the archive file containing the entry.
string entryPath

The full path of the entry within the archive as returned by FullPath.
CancellationToken cancellationToken

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

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

Thrown with EntryNotFound when the entry does not exist, or another code on other failures.

ExtractEntryToFile(string, string, string, CompressionSettings)

Extracts and decompresses a single entry from an archive and writes it to a file on disk. Respects OverwriteExisting and Password.

Declaration
void ExtractEntryToFile(string archivePath, string entryPath, string destinationPath, CompressionSettings settings)
Parameters
Type Name Description
string archivePath

The path to the archive file containing the entry.
string entryPath

The full path of the entry within the archive as returned by FullPath.
string destinationPath

The absolute file path where the extracted data will be written. The parent directory must already exist.
CompressionSettings settings

Settings that control overwrite behaviour and the password for encrypted entries. Must not be null.
Exceptions
Type Condition
CompressionException

Thrown with EntryNotFound, FileExists, or another code on failure.

ExtractEntryToFileAsync(string, string, string, CompressionSettings, CancellationToken)

Asynchronously extracts and decompresses a single entry from an archive and writes it to a file on disk. This is the async counterpart of ExtractEntryToFile(string, string, string, CompressionSettings).

Declaration
Task ExtractEntryToFileAsync(string archivePath, string entryPath, string destinationPath, CompressionSettings settings, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string archivePath

The path to the archive file containing the entry.
string entryPath

The full path of the entry within the archive as returned by FullPath.
string destinationPath

The absolute file path where the extracted data will be written. The parent directory must already exist.
CompressionSettings settings

Settings controlling overwrite behaviour and password. Must not be null.
CancellationToken cancellationToken

Token that can cancel the write. On cancellation, a CompressionException with OperationCancelled is thrown.
Returns
Type Description
Task

A task that completes when the entry has been fully written to disk.
Exceptions
Type Condition
CompressionException

Thrown with EntryNotFound, FileExists, or another code on failure.

ListEntries(string)

Returns metadata for every entry in the specified archive without decompressing any entry data. Reads only the archive's central directory.

Declaration
IReadOnlyList<ArchiveEntryInfo> ListEntries(string archivePath)
Parameters
Type Name Description
string archivePath

The path to the archive file. Must exist and be readable.
Returns
Type Description
IReadOnlyList<ArchiveEntryInfo>

A read-only ordered list of ArchiveEntryInfo values describing every entry (both files and directories) in the archive. The order matches the archive's central-directory sequence.
Exceptions
Type Condition
CompressionException

Thrown with FileNotFound when the archive does not exist, CorruptedData when the file is not a valid archive, or another code for I/O failures.

Extension Methods

See Also