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;
Definition: datetime.h:231
static UniversalDateTime GetNow()
IOARCHIVESTOREMETHOD
Compression methods for files in archives.
Definition: ioarchivehandler.h:23
@ DEFLATE
Deflates the file in the archive.
IOATTRIBUTES
Attributes of Url.
Definition: ioenums.h:103
#define iferr_return
Definition: resultbase.h:1465
struct _Py_Identifier struct _Py_Identifier PyObject struct _Py_Identifier PyObject PyObject struct _Py_Identifier PyObject PyObject PyObject ** method
Definition: object.h:330

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;
PyCompilerFlags * flags
Definition: ast.h:14
Definition: resultbase.h:766
Definition: string.h:1235
Definition: url.h:942
IOARCHIVEEXTRACTFLAGS
Extract Flags used in ReadArchiveInterface::Extract() and ReadArchiveInterface::ExtractSingleFile().
Definition: ioarchivehandler.h:33
@ OVERWRITE_EXISTING_FILE
Overwrites the file silently if it already exists in the directory.

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
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;
}
return OK
Definition: apibase.h:2667
@ NONE
No flags specified.
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:176
IODETECT
Return value of IoDetect().
Definition: ioenums.h:40
@ DIRECTORY
Url is a directory, you can use GetBrowseIterator to iterate through the children.
@ FILE
Url is a file.
PyObject ** type
Definition: pycore_pyerrors.h:34
#define iferr_scope
Definition: resultbase.h:1374
// 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