Archives Manual

Table of Contents

• About
• Writer
• Reader
• File Formats
• Further Reading

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.

• maxon::WriteArchiveInterface::Open(): Opens or creates the archive file.
• maxon::WriteArchiveInterface::Close(): Closes the archive.
• maxon::WriteArchiveInterface::SetCompressionLevel(): Sets the archive compression level.
• maxon::WriteArchiveInterface::GetCompressionLevel(): Returns the archive compression level.
• maxon::WriteArchiveInterface::CreateDirectory(): Creates a directory in the archive.
• maxon::WriteArchiveInterface::CreateFile(): Creates a file in the archive.
• maxon::WriteArchiveInterface::WriteFile(): Writes data into the created file.
• maxon::WriteArchiveInterface::CloseFile(): Closes the created file.
• maxon::WriteArchiveInterface::CopyFile(): Copies an existing file into 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
  const maxon::UniversalDateTime    time = maxon::UniversalDateTime::GetNow();
  const maxon::IOARCHIVESTOREMETHOD method = maxon::IOARCHIVESTOREMETHOD::DEFLATE;
  const maxon::IOATTRIBUTES         attributes = maxon::IOATTRIBUTES::NONE;
 
  // 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.

• maxon::ReadArchiveInterface::Open(): Opens the archive file.
• maxon::ReadArchiveInterface::Close(): Closes the archive file.
• maxon::ReadArchiveInterface::ExtractSingleFile(): Extracts a single virtual file to the given location.
• maxon::ReadArchiveInterface::Extract(): Extracts the complete archive content to the given location.

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
  const maxon::IOARCHIVEEXTRACTFLAGS flags = maxon::IOARCHIVEEXTRACTFLAGS::OVERWRITE_EXISTING_FILE;
  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)
{
  iferr_scope;
 
  // 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
  if (type == maxon::IODETECT::DIRECTORY)
  {
    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
  const maxon::IOARCHIVEEXTRACTFLAGS flags = maxon::IOARCHIVEEXTRACTFLAGS::OVERWRITE_EXISTING_FILE;
  zipArchive.Extract(targetFolder, maxon::ThreadRef(), flags, nullptr) iferr_return;
 
  // close ZIP file
  zipArchive.Close() iferr_return;

Further Reading

• Files & Media
• MAXON API Files & Media
• Url Manual