About

The ZipFile class provides means to work with ZIP archives. ZIP files can be created, modified and extracted.

Note: To create ZIP archives with the Maxon API see Archives Manual.

Allocation/Deallocation

ZipFile objects are created with the usual tools, see Entity Creation and Destruction Manual (Cinema API).

ZipFile::Alloc(): Allocates a ZipFile.
ZipFile::Free(): Destructs a ZipFile previously allocated with ZipFile::Alloc().

Opening and Closing

ZipFile::Open(): Opens a ZIP file.
ZipFile::OpenEncrypted(): Opens an AES encrypted ZIP file, see AESFile.
ZipFile::SetSpanning(): Sets the maximum size of the ZIP file. A new file is created with the same name and a consecutive number if it exceeds this size.
Note
Needs to be called immediately after opening a ZIP file for writing.
ZipFile::Close(): Closes the ZIP file.

Filename

ZipFile::CreateLocalFileName(): Creates a local file name.
ZipFile::CreateFilename(): Creates a file name.

Metadata

ZipFile::GetGlobalInfo(): Retrieves the global information (ZipFileGlobalInfo).
ZipFile::GetGlobalComment(): Retrieves the global comment.

Compression Level

ZipFile::SetCompressionLevel(): Sets the compression level of the ZIP file.
Note
Must be called before opening and initializing the file.
ZipFile::GetCompressionLevel(): Gets the compression level of the ZIP file.

CRC

ZipFile::GetFileCRC(): Gets a ZIP file CRC.
ZipFile::CalcCRC32(): Calculates the CRC from a buffer.

Extracting an Entire Archive

ZipFile::ExtractToDirectory(): Extracts all contents of the ZIP file to the specified directory.

  // This example demonstrates extracting the selected ZIP file to a given folder.
 
  Filename fnZip, fnDest;
  if (!fnZip.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::LOAD, "Choose a ZIP file to extract..."_s, "zip"_s))
    return maxon::OK;
  if (!fnDest.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::DIRECTORY, "Choose a directory to extract to..."_s))
    return maxon::OK;
 
  AutoAlloc<ZipFile> zf;
  if (zf == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  if (!zf->ExtractToDirectory(fnZip, fnDest))
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);

Current File

Internally the ZipFile class has a pointer to the "current" file inside of the archive. The following functions provide means to change the current file pointer to another file or directory.

ZipFile::LocateFile(): Locates a file by name and sets the current file pointer to this file.
ZipFile::GoToFirstFile(): Sets the current file pointer to the first file or directory.
ZipFile::GoToNextFile(): Sets the current file pointer to the next file or directory.

  // This example iterates the files in ZIP archive and finds the first C4D scene (if any).
 
  Bool   sceneFound = false;
  UInt32 fileSizeUncompressed = 0;
  if (!zf->GoToFirstFile())
    return PrintMsgAndCloseZipFile(zf, "Error: No files in ZIP archive.");  // small custom helper function
 
  do
  {
    // Break loop, as soon as the first scene file is encountered.
    ZipFileInfo zfi;
    String      sName;
    if (zf->GetCurrentFileInfo(zfi) && !(zfi.lFlags & ZIP_FLAG_DIRECTORY) && zf->GetCurrentFileInfo(&sName) && Filename(sName).CheckSuffix("c4d"_s))
    {
      fileSizeUncompressed = zfi.lUncompressedSize;
      sceneFound = true;
      break;
    }
  } while (zf->GoToNextFile());
 
  if (!sceneFound || fileSizeUncompressed == 0)
    return PrintMsgAndCloseZipFile(zf, "Error: No C4D scene found in archive.");  // small custom helper function
 

The current file can be extracted from a ZIP archive:

ZipFile::ExtractCurrentFile(): Extracts the current file to a directory (keeping its directory).

  // This example demonstrates looping through the files of a ZIP file and extract each of them separately.
 
  Filename fnZip, fnDest;
  if (!fnZip.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::LOAD, "Choose a ZIP file to extract files from..."_s))
    return maxon::OK;
  if (!fnDest.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::DIRECTORY, "Choose a destination directory for the extracted files..."_s))
    return maxon::OK;
 
  AutoAlloc<ZipFile> zf;
  if (zf == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  if (!zf->Open(fnZip, true)) // Open for reading.
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
  // Iterate files and extract one by one.
  if (!zf->GoToFirstFile())
  {
    ApplicationOutput("No files in ZIP archive.");
    zf->Close();
    return maxon::OK;
  }
 
  do
  {
    // Extract only files (just to demonstrate, that directory structure from archive will stay intact nevertheless).
    ZipFileInfo zfi;
    if (zf->GetCurrentFileInfo(zfi) && !(zfi.lFlags & ZIP_FLAG_DIRECTORY))
      zf->ExtractCurrentFile(fnDest);
  } while (zf->GoToNextFile());
 
  ShowInFinder(fnDest, false);
  zf->Close();

Comprehensive information can be retrieved for the current file:

ZipFile::GetCurrentFileInfo(): Retrieves information for the current file (there are actually two functions providing different infos, see also ZipFileInfo and ZipFileTime).

Similar to "normal" files (e.g. BaseFile) the current file can be opened for reading:

ZipFile::OpenCurrentFile(): Opens the current file (optionally with password protection).
ZipFile::CloseCurrentFile(): Closes the current file.
ZipFile::ReadCurrentFile(): Reads a buffer from the current file.
ZipFile::GetCurrentFileReadPosition(): Gets the read position in the current file.
ZipFile::EndOfCurrentFile(): Checks for the end of the current file.

  // This example reads the current file in chunks from a ZIP archive.
 
  // Open the file.
  if (!zf->OpenCurrentFile())
    return PrintMsgAndCloseZipFile(zf, "Error: Failed to open current file in archive.");   // small custom helper function
 
  // Allocate a buffer to read the file into.
  maxon::AutoMem<Char> buffer = NewMemClear(Char, fileSizeUncompressed) iferr_ignore("nullptr check next");
  if (buffer == nullptr)
    return PrintMsgAndCloseZipFile(zf, "Error: Failed to open allocate buffer.");   // small custom helper function
 
  // Reading in chunks of 4096 (0x1000) bytes, just for demonstration purposes.
  const Int32 maxChunkSize = 0x1000;
  Char*       bufferCurrentPos = buffer;
  Char* const bufferEnd = buffer.GetPointer() + fileSizeUncompressed; // Points to the first byte behind the allocated buffer.
  while (!zf->EndOfCurrentFile())
  {
    const Int32 chunkSize = ClampValue((Int32)(bufferEnd - bufferCurrentPos), 0, maxChunkSize);
    if (chunkSize <= 0)
      break;
    const Int32 numBytesRead = zf->ReadCurrentFile(bufferCurrentPos, chunkSize);
    if (numBytesRead < 0)
      break;
    bufferCurrentPos += numBytesRead;
  }
  if (!zf->EndOfCurrentFile() || (bufferCurrentPos != bufferEnd))
  {
    return PrintMsgAndCloseZipFile(zf, "Error: Something went wrong, while reading file from archive.");  // small custom helper function
  }
  zf->CloseCurrentFile();
  zf->Close();

Add to an ZIP File

ZipFile::CreateFileInZip(): Creates a file in the ZIP file.
- Parameter "method", ::ZipMethod:
  - ::ZipMethodDeflate: Deflate
  - ::ZipMethodStore: Store
ZipFile::WriteInFileInZip(): Writes a buffer in the ZIP file.
ZipFile::CopyInFileInZip(): Copies a file in the ZIP file.
ZipFile::CloseFileInZip(): Closes a file in the ZIP file.
ZipFile::CreateDirectoryInZip(): Creates a directory in the ZIP file. A slash is added if necessary.

  // This example demonstrates how a ZIP file is created and files are added.
 
  Filename fnZip;
  if (!fnZip.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::SAVE, "Save Zip File"_s))
    return maxon::OK;
 
  AutoAlloc<ZipFile> zf;
  if (zf == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  if (!zf->Open(fnZip, false, ZIP_APPEND_CREATE))
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
  Filename fnCopy;
  while (fnCopy.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::LOAD, "Select file to add to Zip File"_s))
  {
    zf->CopyInFileInZip(fnCopy, fnCopy.GetFileString());
  }
 
  zf->Close();

Table of Contents