Small libzip-based helpers for working with ZIP archives. More...

#include <OpenMS/FORMAT/ZipArchiveFile.h>

Static Public Member Functions
static void	zipDirectory (const String &directory_path, const String &output_zip)
	Create a store-only zip archive from a directory (no additional compression)

static String	unzipDirectory (const String &input_path, std::unique_ptr< File::TempDir > &temp_dir)
	Unpack a zip archive into a temporary directory and return the usable path.

static void	addOrReplaceFromFile (const String &archive_path, const String &entry_name, const String &source_file_path)
	Add or replace an entry inside an existing zip archive from a file on disk.

static std::vector< String >	listEntries (const String &archive_path)
	List entries in a zip archive (returns empty list if not available)

static void	writeSidecarIndex (const String &archive_path)
	Write a small JSON sidecar index for the archive listing entries and sizes.

static String	extractEntryToTempFile (const String &archive_path, const String &entry_name, std::unique_ptr< File::TempDir > &temp_dir)
	Extract a single entry from a zip archive into a temporary file and return its path.

Detailed Description

Small libzip-based helpers for working with ZIP archives.

The implementation uses libzip when available; otherwise methods will throw Exception::NotImplemented.

Zip a directory, unzip an archive to a temp directory, and add/replace an entry from a filesystem path.

Member Function Documentation

◆ addOrReplaceFromFile()

static void addOrReplaceFromFile	(	const String &	archive_path,
		const String &	entry_name,
		const String &	source_file_path
	)

static

Add or replace an entry inside an existing zip archive from a file on disk.

Streams the contents of source_file_path into archive_path as the entry entry_name using a file-backed zip source. The archive is created if it does not exist. This avoids loading the entire file into memory and is suitable for large parquet blobs.

Parameters

[in]	archive_path	Path to the zip archive to modify (created if missing).
[in]	entry_name	Relative entry name inside the archive (use '/' separators).
[in]	source_file_path	Path to the source file on disk to add or replace.

Exceptions

Exception::FileNotFound	if the source file is not readable.
Exception::InvalidValue	on libzip errors.
Exception::NotImplemented	if libzip support is unavailable.

◆ extractEntryToTempFile()

static String extractEntryToTempFile	(	const String &	archive_path,
		const String &	entry_name,
		std::unique_ptr< File::TempDir > &	temp_dir
	)

static

Extract a single entry from a zip archive into a temporary file and return its path.

The function will create the provided temp_dir (if null) and extract the requested entry into that directory, preserving any subdirectory structure present in the entry name. This is a lightweight alternative to extracting the whole archive when only a few files are needed.

Parameters

[in]	archive_path	Path to the zip archive
[in]	entry_name	Relative name of the entry to extract
[out]	temp_dir	Unique pointer to a TempDir which will be created if null and will own the extracted file(s)

Returns: The absolute path to the extracted file on disk

Exceptions

Exception::FileNotFound	if the archive or entry is not found
Exception::InvalidValue	on extraction errors

◆ listEntries()

static std::vector< String > listEntries ( const String & archive_path )

static

List entries in a zip archive (returns empty list if not available)

Parameters

[in] archive_path Path to the zip archive to inspect.

Returns: A vector of entry names contained in the archive. Returns an empty vector if the archive cannot be read or libzip is unavailable.

◆ unzipDirectory()

static String unzipDirectory	(	const String &	input_path,
		std::unique_ptr< File::TempDir > &	temp_dir
	)

static

Unpack a zip archive into a temporary directory and return the usable path.

Extracts the archive into a newly created File::TempDir and returns the path to the unpacked directory. This function protects against path traversal and absolute paths in archive entries. If the provided path already points to a directory it is returned unchanged and no TempDir is created.

Parameters

[in]	input_path	Path to the zip archive (or a directory).
[out]	temp_dir	A unique_ptr which will be set to the owned TempDir when an archive is extracted. If input_path is a directory this will remain unchanged.

Returns: The path where the archive was unpacked (or input_path if already a directory).

Exceptions

Exception::FileNotFound	if the input archive is not readable.
Exception::InvalidValue	on archive extraction errors.
Exception::NotImplemented	if libzip support is unavailable.

◆ writeSidecarIndex()

static void writeSidecarIndex ( const String & archive_path )

static

Write a small JSON sidecar index for the archive listing entries and sizes.

For zip archives this helper will write the sidecar JSON as an entry inside the archive (named 'basename.idx.json', e.g. 'results.oswpq.idx.json' for an archive named 'results.oswpq'). This keeps the archive self-contained and portable. When the provided path is a directory (an unpacked layout) the helper will still write an external 'archive_path.idx.json' file.

The JSON object maps entry name -> size in bytes and can be used by readers to implement fast index-based access.

Parameters

[in] archive_path Path to the zip archive (or directory) to index.

If libzip is unavailable this method will throw Exception::NotImplemented.

◆ zipDirectory()

static void zipDirectory	(	const String &	directory_path,
		const String &	output_zip
	)

static

Create a store-only zip archive from a directory (no additional compression)

The created archive will store files without additional compression (ZIP_CM_STORE). If libzip is not available this method will throw Exception::NotImplemented.

Parameters

[in]	directory_path	Path to the directory whose contents will be archived.
[in]	output_zip	Path to the output zip file to create (existing file will be overwritten).

Exceptions

Exception::FileNotWritable	if the archive cannot be written.
Exception::NotImplemented	if libzip support is unavailable.

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ addOrReplaceFromFile()

◆ extractEntryToTempFile()

◆ listEntries()

◆ unzipDirectory()

◆ writeSidecarIndex()

◆ zipDirectory()