Skip to content

BitFileExtractor

Jump to bottom
Oz edited this page Jun 18, 2026 · 8 revisions

Alias for BitExtractor< const tstring & >.

The BitFileExtractor alias allows extracting archives on the filesystem.

#include <bit7z/bitfileextractor.hpp>

List of all members

Public Members

Return type Name
BitExtractor( const Bit7zLibrary& lib, const BitInFormat& format = BitFormat::Auto )
void clearPassword() noexcept
void extract( const tstring& inArchive, buffer_t& outBuffer, std::uint32_t index = 0 ) const
void extract( const tstring& inArchive, BufferCallback callback, BitIndicesView indices = {} ) const
void extract( const tstring& inArchive, byte_t* outBuffer, std::size_t size, std::uint32_t index = 0 ) const
void extract( const tstring& inArchive, byte_t( &outBuffer )[N], std::uint32_t index = 0 ) const
void extract( const tstring& inArchive, const tstring& outDir, RenameCallback callback ) const
void extract( const tstring& inArchive, const tstring& outDir = {} ) const
void extract( const tstring& inArchive, std::array< byte_t, N >& outBuffer, std::uint32_t index = 0 ) const
void extract( const tstring& inArchive, std::map< tstring, buffer_t >& outMap ) const
void extract( const tstring& inArchive, std::ostream& outStream, std::uint32_t index = 0 ) const
void extractFolder( const tstring& inArchive, const tstring& outDir, const tstring& folderPath, FolderPathPolicy policy = FolderPathPolicy::Strip ) const
void extractIf( const tstring& inArchive, buffer_t& outBuffer, FilterCallback callback ) const
void extractIf( const tstring& inArchive, const tstring& outDir, FilterCallback callback ) const
const BitInFormat & extractionFormat() const noexcept
void extractItems( const tstring& inArchive, BitIndicesView indices, const tstring& outDir = {} ) const
void extractMatching( const tstring& inArchive, const tstring& itemFilter, buffer_t& outBuffer, FilterPolicy policy = FilterPolicy::Include ) const
void extractMatching( const tstring& inArchive, const tstring& itemFilter, const tstring& outDir = {}, FilterPolicy policy = FilterPolicy::Include ) const
void extractMatchingRegex( const tstring& inArchive, const tstring& regex, buffer_t& outBuffer, FilterPolicy policy = FilterPolicy::Include ) const
void extractMatchingRegex( const tstring& inArchive, const tstring& regex, const tstring& outDir = {}, FilterPolicy policy = FilterPolicy::Include ) const
void extractRootFolderContent( const tstring& inArchive, const tstring& outDir ) const
void extractTo( const tstring& inArchive, RawDataCallback callback, BitIndicesView indices = {} ) const
const FileCallback & fileCallback() const
const BitInFormat &override format() const noexcept
bool isPasswordDefined() const noexcept
const Bit7zLibrary & library() const noexcept
OverwriteMode overwriteMode() const noexcept
const tstring & password() const
const PasswordCallback & passwordCallback() const
const ProgressCallback & progressCallback() const
const RatioCallback & ratioCallback() const
bool retainDirectories() const noexcept
void setFileCallback( const FileCallback& callback )
void setOverwriteMode( OverwriteMode mode )
void setPassword( const tstring& password )
void setPasswordCallback( const PasswordCallback& callback )
void setProgressCallback( const ProgressCallback& callback )
void setRatioCallback( const RatioCallback& callback )
void setRetainDirectories( bool retain ) noexcept
void setTotalCallback( const TotalCallback& callback )
void test( const tstring& inArchive, BitIndicesView indices = {} ) const
const TotalCallback & totalCallback() const

Member Function Documentation

BitExtractor( const Bit7zLibrary& lib, const BitInFormat& format = BitFormat::Auto )

Constructs a BitExtractor object. The Bit7zLibrary parameter is needed to have access to the functionalities of the 7z DLLs. On the contrary, the BitInFormat is required to know the format of the in_file archives.

Note

When bit7z is compiled using the BIT7Z_AUTO_FORMAT macro define, the format argument has the default value BitFormat::Auto (automatic format detection of the in_file archive). Otherwise, when BIT7Z_AUTO_FORMAT is not defined (i.e., no auto format detection available), the format argument must be specified.

Parameters:

  • lib: the 7z library to use.
  • format: the in_file archive format.

void clearPassword() noexcept

Clear the current password used by the handler. Calling clearPassword() will disable the encryption/decryption of archives.

Note

This is equivalent to calling setPassword(L"").

void extract( const tstring& inArchive, buffer_t& outBuffer, std::uint32_t index = 0 ) const

Extracts a file from the given archive to the output buffer.

Parameters:

  • inArchive: the input archive to extract from.
  • outBuffer: the output buffer where the content of the extracted file will be put.
  • index: the index of the file to be extracted from the archive.

void extract( const tstring& inArchive, BufferCallback callback, BitIndicesView indices = {} ) const

Extracts the content of the given archive to the buffers provided by the given BufferCallback.

Parameters:

  • inArchive: the input archive to be extracted.
  • callback: the function providing the buffers.
  • indices: (optional) the indices of the files in the archive that must be extracted.

void extract( const tstring& inArchive, byte_t* outBuffer, std::size_t size, std::uint32_t index = 0 ) const

Extracts a file to the pre-allocated output buffer.

Parameters:

  • inArchive: the input archive to extract from.
  • outBuffer: the pre-allocated output buffer.
  • size: the size of the output buffer (it must be equal to the unpacked size of the item to be extracted).
  • index: the index of the file to be extracted.

void extract( const tstring& inArchive, byte_t(&) outBuffer, std::uint32_t index = 0 ) const

Extracts a file to the pre-allocated output buffer.

Parameters:

  • inArchive: the input archive to extract from.
  • outBuffer: the pre-allocated output buffer.
  • index: the index of the file to be extracted.

void extract( const tstring& inArchive, const tstring& outDir, RenameCallback callback ) const

Extracts the given archive to the chosen directory, renaming the extracted items using the provided RenameCallback.

Note

The callback receives the archive item being extracted and must return the path that the extracted item must have on the filesystem. If the path of the item must not change, simply return the item's path in the callback. If the item must not be extracted, return an empty string in the callback.

Parameters:

  • inArchive: the input archive to be extracted.
  • outDir: the output directory where extracted files will be put.
  • callback: the callback to be used for renaming the extracted items.

void extract( const tstring& inArchive, const tstring& outDir = {} ) const

Extracts the given archive to the chosen directory.

Parameters:

  • inArchive: the input archive to be extracted.
  • outDir: the output directory where extracted files will be put.

void extract( const tstring& inArchive, std::array< byte_t, N >& outBuffer, std::uint32_t index = 0 ) const

Extracts a file to the pre-allocated output buffer.

Parameters:

  • inArchive: the input archive to extract from.
  • outBuffer: the pre-allocated output buffer.
  • index: the index of the file to be extracted.

void extract( const tstring& inArchive, std::map< tstring, buffer_t >& outMap ) const

Extracts the content of the given archive into a map of memory buffers, where the keys are the paths of the files (inside the archive), and the values are their decompressed contents.

Parameters:

  • inArchive: the input archive to be extracted.
  • outMap: the output map.

void extract( const tstring& inArchive, std::ostream& outStream, std::uint32_t index = 0 ) const

Extracts a file from the given archive to the output stream.

Parameters:

  • inArchive: the input archive to extract from.
  • outStream: the (binary) stream where the content of the extracted file will be put.
  • index: the index of the file to be extracted from the archive.

void extractFolder( const tstring& inArchive, const tstring& outDir, const tstring& folderPath, FolderPathPolicy policy = FolderPathPolicy::Strip ) const

Extracts a folder from the archive to the chosen directory.

Parameters:

  • inArchive: the input archive to extract from.
  • outDir: the output directory where the extracted folder will be put.
  • folderPath: the path of the folder inside the archive to be extracted.
  • policy: (optional) the path policy to be used for extracting the folder.

void extractIf( const tstring& inArchive, buffer_t& outBuffer, FilterCallback callback ) const

Extracts to the output buffer the first item satisfying the given filtering criteria.

Parameters:

  • inArchive: the input archive to extract from.
  • outBuffer: the output buffer where the extracted file will be put.
  • callback: the filtering callback that specifies whether to extract an item or not.

void extractIf( const tstring& inArchive, const tstring& outDir, FilterCallback callback ) const

Extracts to the output directory all the items that satisfy the given filtering criteria.

Parameters:

  • inArchive: the input archive to extract from.
  • outDir: the output directory where extracted files will be put.
  • callback: the filtering callback that specifies whether to extract an item or not.

const BitInFormat & extractionFormat() const noexcept

Returns the archive format used by the archive opener.

void extractItems( const tstring& inArchive, BitIndicesView indices, const tstring& outDir = {} ) const

Extracts the specified items from the given archive to the chosen directory.

Parameters:

  • inArchive: the input archive to extract from.
  • indices: the indices of the files in the archive that should be extracted.
  • outDir: the output directory where the extracted files will be placed.

void extractMatching( const tstring& inArchive, const tstring& itemFilter, buffer_t& outBuffer, FilterPolicy policy = FilterPolicy::Include ) const

Extracts from the archive to the output buffer the first file whose path matches the given wildcard pattern.

Parameters:

  • inArchive: the input archive to extract from.
  • itemFilter: the wildcard pattern used for matching the paths of files inside the archive.
  • outBuffer: the output buffer where to extract the file.
  • policy: the filtering policy to be applied to the matched items.

void extractMatching( const tstring& inArchive, const tstring& itemFilter, const tstring& outDir = {}, FilterPolicy policy = FilterPolicy::Include ) const

Extracts from the archive to the output directory all the items whose paths match the given wildcard pattern.

Parameters:

  • inArchive: the input archive to extract from.
  • itemFilter: the wildcard pattern used for matching the paths of files inside the archive.
  • outDir: the output directory where extracted files will be put.
  • policy: the filtering policy to be applied to the matched items.

void extractMatchingRegex( const tstring& inArchive, const tstring& regex, buffer_t& outBuffer, FilterPolicy policy = FilterPolicy::Include ) const

Extracts from the archive to the output buffer the first file whose path matches the given regex pattern.

Note

Available only when compiling bit7z using the BIT7Z_REGEX_MATCHING preprocessor define.

Parameters:

  • inArchive: the input archive to extract from.
  • regex: the regex used for matching the paths of files inside the archive.
  • outBuffer: the output buffer where the extracted file will be put.
  • policy: the filtering policy to be applied to the matched items.

void extractMatchingRegex( const tstring& inArchive, const tstring& regex, const tstring& outDir = {}, FilterPolicy policy = FilterPolicy::Include ) const

Extracts from the archive to the output directory all the items whose paths match the given regex pattern.

Note

Available only when compiling bit7z using the BIT7Z_REGEX_MATCHING preprocessor define.

Parameters:

  • inArchive: the input archive to extract from.
  • regex: the regex used for matching the paths of files inside the archive.
  • outDir: the output directory where extracted files will be put.
  • policy: the filtering policy to be applied to the matched items.

void extractRootFolderContent( const tstring& inArchive, const tstring& outDir ) const

Extracts the content of the archive's root folder to the chosen directory. The archive's root folder is the single top-level folder shared by all the items in the archive; its name is stripped from the extracted items' paths.

Note

If the archive does not have a single root folder, a BitException is thrown.

Parameters:

  • inArchive: the input archive to extract from.
  • outDir: the output directory where the root folder's content will be put.

void extractTo( const tstring& inArchive, RawDataCallback callback, BitIndicesView indices = {} ) const

Extracts the raw content of the archive to the given callback.

Note

You can set a FileCallback to check the file being extracted.

Parameters:

  • inArchive: the input archive to be extracted.
  • callback: a function providing the extracted raw data to the user.
  • indices: (optional) the indices of the files in the archive that must be extracted.

const FileCallback & fileCallback() const

Returns the current file callback.

[virtual] const BitInFormat &override format() const noexcept

Returns the archive format used by the archive opener.

bool isPasswordDefined() const noexcept

Returns a boolean value indicating whether a password is defined or not.

const Bit7zLibrary & library() const noexcept

Returns the Bit7zLibrary object used by the handler.

OverwriteMode overwriteMode() const noexcept

Returns the current OverwriteMode.

const tstring & password() const

Returns the password used to open, extract, or encrypt the archive.

const PasswordCallback & passwordCallback() const

Returns the current password callback.

const ProgressCallback & progressCallback() const

Returns the current progress callback.

const RatioCallback & ratioCallback() const

Returns the current ratio callback.

bool retainDirectories() const noexcept

Returns a boolean value indicating whether the directory structure must be preserved while extracting or compressing the archive.

void setFileCallback( const FileCallback& callback )

Sets the function to be called when the current file being processed changes.

Parameters:

  • callback: the file callback to be used.

void setOverwriteMode( OverwriteMode mode )

Sets how the handler should behave when it tries to output to an existing file or buffer.

Parameters:

[virtual] void setPassword( const tstring& password )

Sets up a password to be used by the archive handler. The password will be used to encrypt/decrypt archives by using the default cryptographic method of the archive format.

Note

Calling setPassword when the input archive is not encrypted does not have any effect on the extraction process.

Note

Calling setPassword when the output format doesn't support archive encryption (e.g., GZip, BZip2, etc...) does not have any effects (in other words, it doesn't throw exceptions, and it has no effects on compression operations).

Note

After a password has been set, it will be used for every subsequent operation. To disable the use of the password, you need to call the clearPassword method, which is equivalent to calling setPassword(L"").

Parameters:

  • password: the password to be used.

void setPasswordCallback( const PasswordCallback& callback )

Sets the function to be called when a password is needed to complete the ongoing operation.

Parameters:

  • callback: the password callback to be used.

void setProgressCallback( const ProgressCallback& callback )

Sets the function to be called when the processed size of the ongoing operation is updated.

Note

The completion percentage of the current operation can be obtained by calculating static_cast<int>((100.0 * processed_size) / total_size).

Parameters:

  • callback: the progress callback to be used.

void setRatioCallback( const RatioCallback& callback )

Sets the function to be called when the input processed size and current output size of the ongoing operation are known.

Note

The ratio percentage of a compression operation can be obtained by calculating static_cast<int>((100.0 * output_size) / input_size).

Parameters:

  • callback: the ratio callback to be used.

void setRetainDirectories( bool retain ) noexcept

Sets whether the operations' output will preserve the input's directory structure or not.

Parameters:

  • retain: the setting for preserving or not the input directory structure

void setTotalCallback( const TotalCallback& callback )

Sets the function to be called when the total size of an operation is available.

Parameters:

  • callback: the total callback to be used.

void test( const tstring& inArchive, BitIndicesView indices = {} ) const

Tests the given archive without extracting its content. If the archive is not valid, a BitException is thrown.

Parameters:

  • inArchive: the input archive to be tested.
  • indices: (optional) the indices of the items to be tested in the archive.

const TotalCallback & totalCallback() const

Returns the current total callback.

Documentation for bit7z v4.1.0
Copyright © Riccardo Ostani (@rikyoz)

Getting Started

API Reference (v4.1.0)

main classes and type aliases
other classes
namespaces

Clone this wiki locally