The BitExtractor template class allows extracting the content of archives from supported input types. More...

#include <bit7z/bitextractor.hpp>

Inheritance diagram for BitExtractor< Input >:

Collaboration diagram for BitExtractor< Input >:

Public Member Functions
	BitExtractor (const Bit7zLibrary &lib, const BitInFormat &format=BitFormat::Auto)
	Constructs a BitExtractor object.
void	clearPassword () noexcept
	Clear the current password used by the handler.
void	extract (Input inArchive, buffer_t &outBuffer, std::uint32_t index=0) const
	Extracts a file from the given archive to the output buffer.
void	extract (Input inArchive, BufferCallback callback, BitIndicesView indices={}) const
	Extracts the content of the given archive to the buffers provided by the given BufferCallback.
void	extract (Input inArchive, byte_t *outBuffer, std::size_t size, std::uint32_t index=0) const
	Extracts a file to the pre-allocated output buffer.
template<std::size_t N>
void	extract (Input inArchive, byte_t(&outBuffer)[N], std::uint32_t index=0) const
	Extracts a file to the pre-allocated output buffer.
void	extract (Input inArchive, const tstring &outDir, RenameCallback callback) const
	Extracts the given archive to the chosen directory, renaming the extracted items using the provided RenameCallback.
void	extract (Input inArchive, const tstring &outDir={}) const
	Extracts the given archive to the chosen directory.
template<std::size_t N>
void	extract (Input inArchive, std::array< byte_t, N > &outBuffer, std::uint32_t index=0) const
	Extracts a file to the pre-allocated output buffer.
void	extract (Input 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.
void	extract (Input inArchive, std::ostream &outStream, std::uint32_t index=0) const
	Extracts a file from the given archive to the output stream.
void	extractFolder (Input inArchive, const tstring &outDir, const tstring &folderPath, FolderPathPolicy policy=FolderPathPolicy::Strip) const
	Extracts a folder from the archive to the chosen directory.
void	extractIf (Input inArchive, buffer_t &outBuffer, FilterCallback callback) const
	Extracts to the output buffer the first item satisfying the given filtering criteria.
void	extractIf (Input inArchive, const tstring &outDir, FilterCallback callback) const
	Extracts to the output directory all the items that satisfy the given filtering criteria.
auto	extractionFormat () const noexcept -> const BitInFormat &
void	extractItems (Input inArchive, BitIndicesView indices, const tstring &outDir={}) const
	Extracts the specified items from the given archive to the chosen directory.
void	extractMatching (Input 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.
void	extractMatching (Input 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.
void	extractMatchingRegex (Input 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.
void	extractMatchingRegex (Input 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.
void	extractRootFolderContent (Input inArchive, const tstring &outDir) const
	Extracts the content of the archive's root folder to the chosen directory.
void	extractTo (Input inArchive, RawDataCallback callback, BitIndicesView indices={}) const
	Extracts the raw content of the archive to the given callback.
auto	fileCallback () const -> const FileCallback &
auto	format () const noexcept -> const BitInFormat &override
auto	isPasswordDefined () const noexcept -> bool
auto	library () const noexcept -> const Bit7zLibrary &
auto	overwriteMode () const noexcept -> OverwriteMode
auto	password () const -> const tstring &
auto	passwordCallback () const -> const PasswordCallback &
auto	progressCallback () const -> const ProgressCallback &
auto	ratioCallback () const -> const RatioCallback &
auto	retainDirectories () const noexcept -> bool
void	setFileCallback (const FileCallback &callback)
	Sets the function to be called when the current file being processed changes.
void	setOverwriteMode (OverwriteMode mode)
	Sets how the handler should behave when it tries to output to an existing file or buffer.
virtual void	setPassword (const tstring &password)
	Sets up a password to be used by the archive handler.
void	setPasswordCallback (const PasswordCallback &callback)
	Sets the function to be called when a password is needed to complete the ongoing operation.
void	setProgressCallback (const ProgressCallback &callback)
	Sets the function to be called when the processed size of the ongoing operation is updated.
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.
void	setRetainDirectories (bool retain) noexcept
	Sets whether the operations' output will preserve the input's directory structure or not.
void	setTotalCallback (const TotalCallback &callback)
	Sets the function to be called when the total size of an operation is available.
void	test (Input inArchive, BitIndicesView indices={}) const
	Tests the given archive without extracting its content.
auto	totalCallback () const -> const TotalCallback &

Detailed Description

template<typename Input>
class bit7z::BitExtractor< Input >

The BitExtractor template class allows extracting the content of archives from supported input types.

Template Parameters

Input the type of input archives that the generated extractor class supports.

Constructor & Destructor Documentation

◆ BitExtractor()

template<typename Input>

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

inlineexplicit

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.

Member Function Documentation

◆ clearPassword()

void clearPassword ( )

noexceptinherited

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"").

◆ extract() [1/9]

template<typename Input>

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

inline

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.

◆ extract() [2/9]

template<typename Input>

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

inline

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.

◆ extract() [3/9]

template<typename Input>

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

inline

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.

◆ extract() [4/9]

template<typename Input>

template<std::size_t N>

void extract	(	Input	inArchive,
		byte_t(&)	outBuffer[N],
		std::uint32_t	index = 0 ) const

inline

Extracts a file to the pre-allocated output buffer.

Template Parameters

N	the size of the output buffer (it must be equal to the unpacked size of the item to be extracted).

Parameters

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

◆ extract() [5/9]

template<typename Input>

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

inline

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.

◆ extract() [6/9]

template<typename Input>

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

inline

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.

◆ extract() [7/9]

template<typename Input>

template<std::size_t N>

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

inline

Extracts a file to the pre-allocated output buffer.

Template Parameters

N	the size of the output buffer (it must be equal to the unpacked size of the item to be extracted).

Parameters

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

◆ extract() [8/9]

template<typename Input>

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

inline

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.

◆ extract() [9/9]

template<typename Input>

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

inline

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.

◆ extractFolder()

template<typename Input>

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

inline

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.

◆ extractIf() [1/2]

template<typename Input>

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

inline

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.

◆ extractIf() [2/2]

template<typename Input>

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

inline

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.

◆ extractionFormat()

auto extractionFormat ( ) const -> const BitInFormat &

noexceptinherited

Returns: the archive format used by the archive opener.

◆ extractItems()

template<typename Input>

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

inline

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.

◆ extractMatching() [1/2]

template<typename Input>

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

inline

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.

◆ extractMatching() [2/2]

template<typename Input>

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

inline

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.

◆ extractMatchingRegex() [1/2]

template<typename Input>

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

inline

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.

◆ extractMatchingRegex() [2/2]

template<typename Input>

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

inline

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.

◆ extractRootFolderContent()

template<typename Input>

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

inline

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.

◆ extractTo()

template<typename Input>

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

inline

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.

◆ fileCallback()

auto fileCallback ( ) const -> const FileCallback &

inherited

Returns: the current file callback.

◆ format()

auto format ( ) const -> const BitInFormat &override

overridevirtualnoexceptinherited

Returns: the archive format used by the archive opener.

Implements BitAbstractArchiveHandler.

◆ isPasswordDefined()

auto isPasswordDefined ( ) const -> bool

noexceptinherited

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

◆ library()

auto library ( ) const -> const Bit7zLibrary &

noexceptinherited

Returns: the Bit7zLibrary object used by the handler.

◆ overwriteMode()

auto overwriteMode ( ) const -> OverwriteMode

noexceptinherited

Returns: the current OverwriteMode.

◆ password()

auto password ( ) const -> const tstring &

inherited

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

◆ passwordCallback()

auto passwordCallback ( ) const -> const PasswordCallback &

inherited

Returns: the current password callback.

◆ progressCallback()

auto progressCallback ( ) const -> const ProgressCallback &

inherited

Returns: the current progress callback.

◆ ratioCallback()

auto ratioCallback ( ) const -> const RatioCallback &

inherited

Returns: the current ratio callback.

◆ retainDirectories()

auto retainDirectories ( ) const -> bool

noexceptinherited

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

◆ setFileCallback()

void setFileCallback ( const FileCallback & callback )

inherited

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

Parameters

callback the file callback to be used.

◆ setOverwriteMode()

void setOverwriteMode ( OverwriteMode mode )

inherited

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

Parameters

mode	the OverwriteMode to be used by the handler.

◆ setPassword()

virtual void setPassword ( const tstring & password )

virtualinherited

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.; 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).; 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.

Reimplemented in BitAbstractArchiveCreator.

◆ setPasswordCallback()

void setPasswordCallback ( const PasswordCallback & callback )

inherited

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

Parameters

callback the password callback to be used.

◆ setProgressCallback()

void setProgressCallback ( const ProgressCallback & callback )

inherited

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.

◆ setRatioCallback()

void setRatioCallback ( const RatioCallback & callback )

inherited

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.

◆ setRetainDirectories()

void setRetainDirectories ( bool retain )

noexceptinherited

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

◆ setTotalCallback()

void setTotalCallback ( const TotalCallback & callback )

inherited

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

Parameters

callback the total callback to be used.

◆ test()

template<typename Input>

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

inline

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.

◆ totalCallback()

auto totalCallback ( ) const -> const TotalCallback &

inherited

Returns: the current total callback.

The documentation for this class was generated from the following file:

include/bit7z/bitextractor.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BitExtractor()

Member Function Documentation

◆ clearPassword()

◆ extract() [1/9]

◆ extract() [2/9]

◆ extract() [3/9]

◆ extract() [4/9]

◆ extract() [5/9]

◆ extract() [6/9]

◆ extract() [7/9]

◆ extract() [8/9]

◆ extract() [9/9]

◆ extractFolder()

◆ extractIf() [1/2]

◆ extractIf() [2/2]

◆ extractionFormat()

◆ extractItems()

◆ extractMatching() [1/2]

◆ extractMatching() [2/2]

◆ extractMatchingRegex() [1/2]

◆ extractMatchingRegex() [2/2]

◆ extractRootFolderContent()

◆ extractTo()

◆ fileCallback()

◆ format()

◆ isPasswordDefined()

◆ library()

◆ overwriteMode()

◆ password()

◆ passwordCallback()

◆ progressCallback()

◆ ratioCallback()

◆ retainDirectories()

◆ setFileCallback()

◆ setOverwriteMode()

◆ setPassword()

◆ setPasswordCallback()

◆ setProgressCallback()

◆ setRatioCallback()

◆ setRetainDirectories()

◆ setTotalCallback()

◆ test()

◆ totalCallback()