pospelove / bit7z

A C++ static library offering a clean and simple interface to the 7-zip shared libraries.

bit7z

A C++ static library offering a clean and simple interface to the 7-zip shared libraries

Supported Features • Getting Started • Download • Requirements • Building & Using • Donate • License

        
     

⚡️ Introduction

bit7z is a cross-platform C++ static library that allows the compression/extraction of archive files through a clean and simple wrapper interface to the dynamic libraries from the 7-zip project.
It supports compression and extraction to and from the filesystem or the memory, reading archives metadata, updating existing ones, creating multi-volume archives, operation progress callbacks, and many other functionalities.

🎯 Supported Features

• Compression using the following archive formats: 7z, XZ, BZIP2, GZIP, TAR, ZIP, and WIM.
• Extraction of many archive formats: 7z, AR, ARJ, BZIP2, CAB, CHM, CPIO, CramFS, DEB, DMG, EXT, FAT, GPT, GZIP, HFS, HXS, IHEX, ISO, LZH, LZMA, MBR, MSI, NSIS, NTFS, QCOW2, RAR, RAR5, RPM, SquashFS, TAR, UDF, UEFI, VDI, VHD, VMDK, WIM, XAR, XZ, Z, and ZIP.
• Reading metadata of archives and their content.
• Testing archives for errors.
• Updating existing file archives with new files.
• Renaming, updating, or deleting old items in existing file archives.
• Compression and extraction to and from memory and C++ standard streams.
• Compression using custom path aliases for the items in the output archives.
• Selective extraction of only specified files/folders using wildcards and regular expressions.
• Creation of encrypted archives (strong AES-256 encryption — only for 7z and ZIP formats).
• Archive header encryption (only for 7z format).
• Possibility to choose the compression level (if supported by the archive format), the compression method (supported methods), the dictionary size, and the word size.
• Automatic input archive format detection.
• Solid archives (only for 7z).
• Multi-volume archives.
• Operation callbacks for obtaining real-time information about ongoing operations.
• Canceling or pausing the current operation.

Notes

The presence or not of some of the above features depends on the particular shared library used along with bit7z.
For example, 7z.dll should support all these features, 7za.dll should work only with the 7z file format, and 7zxa.dll can only extract 7z files. For more information about the 7-zip DLLs, please check this wiki page.

In the end, some other features (e.g., automatic format detection and selective extraction using regular expressions) are disabled by default, and macro definitions must be used during compilation to have them available (wiki).

🔥 Getting Started (Library Usage)

Below are a few examples that show how to use some of the main features of bit7z.

📂 Extracting files from an archive

#include <bit7z/bitfileextractor.hpp>

try { // bit7z classes can throw BitException objects
    using namespace bit7z;

    Bit7zLibrary lib{ "7za.dll" };
    BitFileExtractor extractor{ lib, BitFormat::SevenZip };

    // Extracting a simple archive
    extractor.extract( "path/to/archive.7z", "out/dir/" );

    // Extracting a specific file
    extractor.extractMatching( "path/to/archive.7z", "file.pdf", "out/dir/" );

    // Extracting the first file of an archive to a buffer
    std::vector< byte_t > buffer;
    extractor.extract( "path/to/archive.7z", buffer );

    // Extracting an encrypted archive
    extractor.setPassword( "password" );
    extractor.extract( "path/to/another/archive.7z", "out/dir/" );
} catch ( const bit7z::BitException& ex ) { /* Do something with ex.what()...*/ }

Alternatively, if you only need to work on a single archive:

#include <bit7z/bitarchivereader.hpp>

try { // bit7z classes can throw BitException objects
    using namespace bit7z;

    Bit7zLibrary lib{ "7z.dll" };

    // Opening the archive
    BitArchiveReader reader{lib, "path/to/archive.gz", BitFormat::GZip };

    // Testing the archive
    reader.test();

    // Extracting the archive
    reader.extract( "out/dir/" );
} catch ( const bit7z::BitException& ex ) { /* Do something with ex.what()...*/ }

💼 Compressing files into an archive

#include <bit7z/bitfilecompressor.hpp>

try { // bit7z classes can throw BitException objects
    using namespace bit7z;

    Bit7zLibrary lib{ "7z.dll" };
    BitFileCompressor compressor{ lib, BitFormat::Zip };

    std::vector< std::string > files = { "path/to/file1.jpg", "path/to/file2.pdf" };

    // Creating a simple zip archive
    compressor.compress( files, "output_archive.zip" );

    // Creating a zip archive with a custom directory structure
    std::map< std::string, std::string > files_map = {
        { "path/to/file1.jpg", "alias/path/file1.jpg" },
        { "path/to/file2.pdf", "alias/path/file2.pdf" }
    };
    compressor.compress( files_map, "output_archive2.zip" );

    // Compressing a directory
    compressor.compressDirectory( "dir/path/", "dir_archive.zip" );

    // Creating an encrypted zip archive of two files
    compressor.setPassword( "password" );
    compressor.compressFiles( files, "protected_archive.zip" );

    // Updating an existing zip archive
    compressor.setUpdateMode( UpdateMode::Append );
    compressor.compressFiles( files, "existing_archive.zip" );

    // Compressing a single file into a buffer
    std::vector< bit7z::byte_t > buffer;
    BitFileCompressor compressor2{ lib, BitFormat::BZip2 };
    compressor2.compressFile( files[0], buffer );
} catch ( const bit7z::BitException& ex ) { /* Do something with ex.what()...*/ }

Alternatively, if you only need to work on a single archive:

#include <bit7z/bitarchivewriter.hpp>

try { // bit7z classes can throw BitException objects
    using namespace bit7z;

    Bit7zLibrary lib{ "7z.dll" };
    BitArchiveWriter writer{lib, BitFormat::SevenZip };

    // Adding the items to be compressed (no compression is performed here)
    writer.addFile( "path/to/file.txt" );
    writer.addDirectory( "path/to/dir/" );

    // Compressing the added items to the output archive
    writer.compressTo( "output.7z" );
} catch ( const bit7z::BitException& ex ) { /* Do something with ex.what()...*/ }

📑 Reading archive metadata

#include <bit7z/bitarchivereader.hpp>

try { // bit7z classes can throw BitException objects
    using namespace bit7z;

    Bit7zLibrary lib{ "7za.dll" };
    BitArchiveReader arc{ lib, "archive.7z", BitFormat::SevenZip };

    // Printing archive metadata
    std::cout << "Archive properties" << std::endl;
    std::cout << "  Items count: "   << arc.itemsCount() << std::endl;
    std::cout << "  Folders count: " << arc.foldersCount() << std::endl;
    std::cout << "  Files count: "   << arc.filesCount() << std::endl;
    std::cout << "  Size: "          << arc.size() << std::endl;
    std::cout << "  Packed size: "   << arc.packSize() << std::endl;
    std::cout << std::endl;

    // Printing the metadata of the archived items
    std::cout << "Archived items";
    auto arc_items = arc.items();
    for ( auto& item : arc_items ) {
        std::cout << std::endl;
        std::cout << "  Item index: "   << item.index() << std::endl;
        std::cout << "    Name: "        << item.name() << std::endl;
        std::cout << "    Extension: "   << item.extension() << std::endl;
        std::cout << "    Path: "        << item.path() << std::endl;
        std::cout << "    IsDir: "       << item.isDir() << std::endl;
        std::cout << "    Size: "        << item.size() << std::endl;
        std::cout << "    Packed size: " << item.packSize() << std::endl;
        std::cout << "    CRC: "         << item.crc() << std::endl;
    }
} catch ( const bit7z::BitException& ex ) { /* Do something with ex.what()...*/ }

A complete API reference is available in the wiki section.

🚀 Upgrading from bit7z v3 to v4

Expand for more details!

The newest bit7z v4 introduced some significant breaking changes to the API. In particular:

• By default, the project now follows the UTF-8 Everywhere Manifesto:
  • The default string type is std::string (instead of std::wstring), so users can use the library in cross-platform projects more easily (v4 introduced Linux/macOS support too).
  • Input std::strings will be considered as UTF-8 encoded.
  • You can still achieve the old behavior on Windows using the -DBIT7Z_USE_NATIVE_STRING CMake option.
• The old BitExtractor class is now called BitFileExtractor.
  • Now BitExtractor is just the name of a template class for all the extraction classes.
• The old BitCompressor class is now called BitFileCompressor.
  • Now BitCompressor is just the name of a template class for all the compression classes.
• The ProgressCallback now must return a bool value indicating whether the current operation can continue (true) or not (false).

💾 Download

  

Each released package contains:

• A pre-compiled version of bit7z (both in debug and release mode);
• The public API headers needed to use the library in your program;

Packages are available for both x86 and x64 architectures.

You can also clone/download this repository and build the library by yourself (please, read the wiki).

🧰 Requirements

• Operating System: Windows, Linux, macOS¹.
• Architecture: x86, x86_64.
• Compiler: MSVC 2015 or later², MinGW v6.4 or later, GCC v4.9 or later, Clang 3.5 or later.
• Shared Library: a 7-zip .dll library on Windows, a 7-zip/p7zip .so library on Unix³.

⚙️ Building and using bit7z

For building the library:

cd <bit7z folder>
mkdir build && cd build
cmake ../ -DCMAKE_BUILD_TYPE=Release
cmake --build . -j --config Release

A more detailed guide on how to build this library is available here.

You can directly integrate the library into your project via CMake:

• Download bit7z and copy it into a sub-directory of your project (e.g., third_party), or add it as a git submodule of your repository.
• You can then use the command add_subdirectory() in your CMakeLists.txt to include bit7z.
• Finally, add the bit7z64 target (just bit7z on x86) using the target_link_libraries() command.

For example:

add_subdirectory( ${CMAKE_SOURCE_DIR}/third_party/bit7z )
target_link_libraries( ${TARGET_NAME} PRIVATE bit7z64 ) # or bit7z on x86

☕️ Donate

If you have found this project helpful, please consider supporting me with a small donation so that I can keep improving it! Thank you! 🙏

  

📜 License

This project is licensed under the terms of the Mozilla Public License v2.0.
For more details, please check:

• The LICENSE file.
• Mozilla's MPL-2.0 FAQ

Older versions (v3.x and earlier) of bit7z were released under the GNU General Public License v2.

Copyright © 2014 - 2023 Riccardo Ostani (@rikyoz)

Footnotes

1. On Windows, you should link your program also with oleaut32 (e.g., -lbit7z -loleaut32).
   On Linux and macOS, you should link your program also with dl (e.g., -lbit7z -ldl).
   If you are using the library via CMake, these dependencies will be linked automatically to your project. ↩

2. MSVC 2010 was supported until v2.x, MSVC 2012/2013 until v3.x. ↩

3. bit7z doesn't ship with the 7-zip shared libraries. You can build them from the source code available at 7-zip.org. ↩