Archives Manual

About

maxon::WriteArchiveInterface and maxon::ReadArchiveInterface are generic interfaces giving access to archive files. These interfaces are typically used to read and write ZIP files.

Writer

The maxon::WriteArchiveInterface allows to create archive files and to add virtual files to the archive.

Implementations of this interface are registered at the maxon::WriteArchiveClasses registry and are also accessible as published object:

  • maxon::WriteArchiveClasses::Zip: Implementation to write ZIP archives.
// This example creates a ZIP file containing two text files.
// create WriteArchiveRef for a ZIP file
const maxon::WriteArchiveRef zipArchive = maxon::WriteArchiveClasses::Zip().Create() iferr_return;
// create ZIP file
zipArchive.Open(zipFile, false) iferr_return;
zipArchive.SetCompressionLevel(2) iferr_return;
// define file settings
// create a file at the top level
zipArchive.CreateFile("text.txt"_s, time, method, attributes, 0) iferr_return;
zipArchive.WriteFile(fileData) iferr_return;
zipArchive.CloseFile() iferr_return;
// create a file in a sub-folder
zipArchive.CreateFile("exampleFolder/text.txt"_s, time, method, attributes, 0) iferr_return;
zipArchive.WriteFile(fileData) iferr_return;
zipArchive.CloseFile() iferr_return;
// close ZIP file
zipArchive.Close() iferr_return;

Reader

The maxon::ReadArchiveInterface allows to open and read archive files.

Implementations of this interface are registered at the maxon::ReadArchiveClasses registry and are also accessible as published object:

  • maxon::ReadArchiveClasses::Zip: Implementation of read ZIP archives.
// This example opens a ZIP file and extracts a sub-file from it.
// callback to check if the given file should be extracted
auto SingleFileCallback = [](const maxon::String& inputName, maxon::Url& outputName, maxon::IOATTRIBUTES& fileAttributes) -> maxon::Result<maxon::Bool>
{
// check inputName or fileAttributes if needed
return true;
};
// create new ReadArchiveRef for a ZIP file
const maxon::ReadArchiveRef zipArchive = maxon::ReadArchiveClasses::Zip().Create() iferr_return;
// open ZIP file
zipArchive.Open(zipFile) iferr_return;
// extract a single file; if the file will be extracted is controlled with the optional SingleFileCallback
zipArchive.ExtractSingleFile("text.txt"_s, targetFolder, maxon::ThreadRef(), flags, SingleFileCallback) iferr_return;
// close ZIP file
zipArchive.Close() iferr_return;

File Formats

These maxon::FileFormatHandler allow to browse an archive file or to easily read it:

  • maxon::FileFormatHandlers::ZipDirectoryBrowser: Creates a maxon::IoBrowseRef to browse the virtual files of a ZIP file.
  • maxon::FileFormatHandlers::GZipDirectoryBrowser: Creates a maxon::IoBrowseRef to browse the virtual files of a GZip file.
  • maxon::FileFormatHandlers::ZipArchiveHandler: Creates a maxon::ReadArchiveRef to read file from a ZIP file.
// This example browses the files stored in the given ZIP file.
// obtain IoBrowseRef for the top level
const maxon::FileFormatHandler& zipDirBrowser = maxon::FileFormatHandlers::ZipDirectoryBrowser();
auto handler = zipDirBrowser.CreateHandler<maxon::IoBrowseRef>(zipFile);
// browse through all files/folders on the top level
for (auto it : handler)
{
const maxon::IoBrowseRef& browseIterator = (it)iferr_return;
HandleIterator(browseIterator) iferr_return;
}
// This example shows a function that recursively iterates all files.
static maxon::Result<void> HandleIterator(const maxon::IoBrowseRef& browseIterator)
{
// get current element
const maxon::Url currentFile = browseIterator.GetCurrentPath();
const maxon::IODETECT type = currentFile.IoDetect();
// check if file
if (type == maxon::IODETECT::FILE)
DiagnosticOutput("File: @", currentFile);
// check if folder
{
DiagnosticOutput("Folder @", currentFile);
// browse files in that folder
for (auto subIt : currentFile.GetBrowseIterator(maxon::GETBROWSEITERATORFLAGS::NONE))
{
const maxon::IoBrowseRef& subIterator = (subIt)iferr_return;
HandleIterator(subIterator) iferr_return;
}
}
return maxon::OK;
}
// This example extracts all files from the given ZIP file into a target folder.
// create ReadArchiveRef handler for a ZIP file
const maxon::FileFormatHandler& handler = maxon::FileFormatHandlers::ZipArchiveHandler();
const maxon::ReadArchiveRef zipArchive = handler.CreateHandler<maxon::ReadArchiveRef>(maxon::Url()) iferr_return;
// open ZIP file
zipArchive.Open(zipFile) iferr_return;
// extract all files to the given target folder
zipArchive.Extract(targetFolder, maxon::ThreadRef(), flags, nullptr) iferr_return;
// close ZIP file
zipArchive.Close() iferr_return;

Further Reading

maxon::IOATTRIBUTES::NONE
@ NONE
maxon::IODETECT::DIRECTORY
@ DIRECTORY
Url is a directory, you can use GetBrowseIterator to iterate through the children.
maxon::String
Definition: string.h:1197
maxon::OK
return OK
Definition: apibase.h:2532
iferr_return
#define iferr_return
Definition: resultbase.h:1434
maxon::IODETECT
IODETECT
Return value of IoDetect().
Definition: ioenums.h:39
maxon::UniversalDateTime
Definition: datetime.h:231
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:166
maxon::IOARCHIVEEXTRACTFLAGS
IOARCHIVEEXTRACTFLAGS
Extract Flags used in ReadArchiveInterface::Extract() and ReadArchiveInterface::ExtractSingleFile().
Definition: ioarchivehandler.h:32
maxon::Url
Definition: url.h:819
maxon::Result
Definition: apibase.h:314
maxon::ThreadRefTemplate< ThreadInterface >
iferr_scope
#define iferr_scope
Definition: resultbase.h:1343
maxon::IOARCHIVEEXTRACTFLAGS::OVERWRITE_EXISTING_FILE
@ OVERWRITE_EXISTING_FILE
Overwrites the file silently if it already exists in the directory.
maxon::IODETECT::FILE
@ FILE
Url is a file.
maxon::UniversalDateTime::GetNow
static UniversalDateTime GetNow()
maxon::GETBROWSEITERATORFLAGS::NONE
@ NONE
No flags specified.
maxon::IOATTRIBUTES
IOATTRIBUTES
Attributes of Url.
Definition: ioenums.h:101
maxon::IOARCHIVESTOREMETHOD
IOARCHIVESTOREMETHOD
Compression methods for files in archives.
Definition: ioarchivehandler.h:22
maxon::IOARCHIVESTOREMETHOD::DEFLATE
@ DEFLATE
Deflates the file in the archive.