The BitArchiveReader class allows reading metadata of archives, as well as extracting them. More...

#include <bit7z/bitarchivereader.hpp>

Inheritance diagram for BitArchiveReader:

Collaboration diagram for BitArchiveReader:

Public Member Functions
	BitArchiveReader (const Bit7zLibrary &lib, const std::vector< byte_t > &inArchive, const BitInFormat &format=BitFormat::Auto, const tstring &password={})
	Constructs a BitArchiveReader object, opening the archive in the input buffer.

	BitArchiveReader (const Bit7zLibrary &lib, const tstring &inArchive, const BitInFormat &format=BitFormat::Auto, const tstring &password={})
	Constructs a BitArchiveReader object, opening the input file archive.

	BitArchiveReader (const Bit7zLibrary &lib, std::istream &inArchive, const BitInFormat &format=BitFormat::Auto, const tstring &password={})
	Constructs a BitArchiveReader object, opening the archive from the standard input stream.

	~BitArchiveReader () override=default
	BitArchiveReader destructor.

auto	archivePath () const noexcept -> const tstring &

auto	archiveProperties () const -> map< BitProperty, BitPropVariant >

auto	archiveProperty (BitProperty property) const -> BitPropVariant
	Gets the specified archive property.

auto	begin () const noexcept -> BitInputArchive::ConstIterator

auto	cbegin () const noexcept -> BitInputArchive::ConstIterator

auto	cend () const noexcept -> BitInputArchive::ConstIterator

void	clearPassword () noexcept
	Clear the current password used by the handler.

auto	contains (const tstring &path) const noexcept -> bool
	Find if there is an item in the archive that has the given path.

auto	detectedFormat () const noexcept -> const BitInFormat &

auto	end () const noexcept -> BitInputArchive::ConstIterator

auto	extractionFormat () const noexcept -> const BitInFormat &

void	extractTo (byte_t *buffer, std::size_t size, uint32_t index=0) const
	Extracts a file to the pre-allocated output buffer.

template<std::size_t N>
void	extractTo (byte_t(&buffer)[N], uint32_t index=0) const
	Extracts a file to the pre-allocated output buffer.

void	extractTo (const tstring &outDir, const std::vector< uint32_t > &indices={}) const
	Extracts the specified items to the chosen directory.

template<std::size_t N>
void	extractTo (std::array< byte_t, N > &buffer, uint32_t index=0) const
	Extracts a file to the pre-allocated output buffer.

void	extractTo (std::map< tstring, std::vector< byte_t > > &outMap) const
	Extracts the content of the archive to 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	extractTo (std::ostream &outStream, uint32_t index=0) const
	Extracts a file to the output stream.

void	extractTo (std::vector< byte_t > &outBuffer, uint32_t index=0) const
	Extracts a file to the output buffer.

auto	fileCallback () const -> FileCallback

auto	filesCount () const -> uint32_t

auto	find (const tstring &path) const noexcept -> BitInputArchive::ConstIterator
	Find an item in the archive that has the given path.

auto	foldersCount () const -> uint32_t

auto	format () const noexcept -> const BitInFormat &override

auto	handler () const noexcept -> const BitAbstractArchiveHandler &

auto	hasEncryptedItems () const -> bool

auto	isEncrypted () const -> bool

auto	isItemEncrypted (uint32_t index) const -> bool

auto	isItemFolder (uint32_t index) const -> bool

auto	isMultiVolume () const -> bool

auto	isPasswordDefined () const noexcept -> bool

auto	isSolid () const -> bool

auto	itemAt (uint32_t index) const -> BitArchiveItemOffset
	Retrieve the item at the given index.

auto	itemProperty (uint32_t index, BitProperty property) const -> BitPropVariant
	Gets the specified property of an item in the archive.

auto	items () const -> vector< BitArchiveItemInfo >

auto	itemsCount () const -> uint32_t

auto	library () const noexcept -> const Bit7zLibrary &

auto	overwriteMode () const -> OverwriteMode

auto	packSize () const -> uint64_t

auto	password () const -> tstring

auto	passwordCallback () const -> PasswordCallback

auto	progressCallback () const -> ProgressCallback

auto	ratioCallback () 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.

auto	size () const -> uint64_t

void	test () const
	Tests the archive without extracting its content.

void	testItem (uint32_t index) const
	Tests the item at the given index inside the archive without extracting it.

auto	totalCallback () const -> TotalCallback

auto	volumesCount () const -> uint32_t

Static Public Member Functions
template<typename T >
static auto	isEncrypted (const Bit7zLibrary &lib, T &&inArchive, const BitInFormat &format=BitFormat::Auto) -> bool
	Checks if the given archive contains only encrypted items.

template<typename T >
static auto	isHeaderEncrypted (const Bit7zLibrary &lib, T &&inArchive, const BitInFormat &format=BitFormat::Auto) -> bool
	Checks if the given archive is header-encrypted or not.

Detailed Description

The BitArchiveReader class allows reading metadata of archives, as well as extracting them.

Constructor & Destructor Documentation

◆ BitArchiveReader() [1/3]

BitArchiveReader	(	const Bit7zLibrary &	lib,
		const tstring &	inArchive,
		const BitInFormat &	format = `BitFormat::Auto`,
		const tstring &	password = `{}`
	)

Constructs a BitArchiveReader object, opening the input file archive.

Note: When bit7z is compiled using the BIT7Z_AUTO_FORMAT option, the format argument has the default value BitFormat::Auto (automatic format detection of the input archive). On the contrary, 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 used.
inArchive	the path to the archive to be read.
format	the format of the input archive.
password	the password needed for opening the input archive.

◆ BitArchiveReader() [2/3]

BitArchiveReader	(	const Bit7zLibrary &	lib,
		const std::vector< byte_t > &	inArchive,
		const BitInFormat &	format = `BitFormat::Auto`,
		const tstring &	password = `{}`
	)

Constructs a BitArchiveReader object, opening the archive in the input buffer.

Note: When bit7z is compiled using the BIT7Z_AUTO_FORMAT option, the format argument has the default value BitFormat::Auto (automatic format detection of the input archive). On the contrary, 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 used.
inArchive	the input buffer containing the archive to be read.
format	the format of the input archive.
password	the password needed for opening the input archive.

◆ BitArchiveReader() [3/3]

BitArchiveReader	(	const Bit7zLibrary &	lib,
		std::istream &	inArchive,
		const BitInFormat &	format = `BitFormat::Auto`,
		const tstring &	password = `{}`
	)

Constructs a BitArchiveReader object, opening the archive from the standard input stream.

Note: When bit7z is compiled using the BIT7Z_AUTO_FORMAT option, the format argument has the default value BitFormat::Auto (automatic format detection of the input archive). On the contrary, 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 used.
inArchive	the standard input stream of the archive to be read.
format	the format of the input archive.
password	the password needed for opening the input archive.

◆ ~BitArchiveReader()

~BitArchiveReader ( )

overridedefault

BitArchiveReader destructor.

Note: It releases the input archive file.

Member Function Documentation

◆ archivePath()

auto archivePath ( ) const -> const tstring &

noexceptinherited

Returns: the path to the archive (the empty string for buffer/stream archives).

◆ archiveProperties()

auto archiveProperties ( ) const -> map< BitProperty, BitPropVariant >

Returns: a map of all the available (i.e., non-empty) archive properties and their respective values.

◆ archiveProperty()

auto archiveProperty ( BitProperty property ) const -> BitPropVariant

inherited

Gets the specified archive property.

Parameters

property the property to be retrieved.

Returns: the current value of the archive property or an empty BitPropVariant if no value is specified.

◆ begin()

auto begin ( ) const -> BitInputArchive::ConstIterator

noexceptinherited

Returns: an iterator to the first element of the archive; if the archive is empty, the returned iterator will be equal to the end() iterator.

◆ cbegin()

auto cbegin ( ) const -> BitInputArchive::ConstIterator

noexceptinherited

Returns: an iterator to the first element of the archive; if the archive is empty, the returned iterator will be equal to the end() iterator.

◆ cend()

auto cend ( ) const -> BitInputArchive::ConstIterator

noexceptinherited

Returns: an iterator to the element following the last element of the archive; this element acts as a placeholder: attempting to access it results in undefined behavior.

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

◆ contains()

auto contains ( const tstring & path ) const -> bool

noexceptinherited

Find if there is an item in the archive that has the given path.

Parameters

path	the path to be searched in the archive.

Returns: true if and only if an item with the given path exists in the archive.

◆ detectedFormat()

auto detectedFormat ( ) const -> const BitInFormat &

noexceptinherited

Returns: the detected format of the file.

◆ end()

auto end ( ) const -> BitInputArchive::ConstIterator

noexceptinherited

Returns: an iterator to the element following the last element of the archive; this element acts as a placeholder: attempting to access it results in undefined behavior.

◆ extractionFormat()

auto extractionFormat ( ) const -> const BitInFormat &

noexceptinherited

Returns: the archive format used by the archive opener.

◆ extractTo() [1/7]

void extractTo	(	byte_t *	buffer,
		std::size_t	size,
		uint32_t	index = `0`
	)		const

inherited

Extracts a file to the pre-allocated output buffer.

Parameters

buffer	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.

◆ extractTo() [2/7]

template<std::size_t N>

void extractTo	(	byte_t(&)	buffer[N],
		uint32_t	index = `0`
	)		const

inlineinherited

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

buffer	the pre-allocated output buffer.
index	the index of the file to be extracted.

◆ extractTo() [3/7]

void extractTo	(	const tstring &	outDir,
		const std::vector< uint32_t > &	indices = `{}`
	)		const

inherited

Extracts the specified items to the chosen directory.

Parameters

outDir	the output directory where the extracted files will be put.
indices	the array of indices of the files in the archive that must be extracted.

◆ extractTo() [4/7]

template<std::size_t N>

void extractTo	(	std::array< byte_t, N > &	buffer,
		uint32_t	index = `0`
	)		const

inlineinherited

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

buffer	the pre-allocated output buffer.
index	the index of the file to be extracted.

◆ extractTo() [5/7]

void extractTo ( std::map< tstring, std::vector< byte_t > > & outMap ) const

inherited

Extracts the content of the archive to 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

outMap the output map.

◆ extractTo() [6/7]

void extractTo	(	std::ostream &	outStream,
		uint32_t	index = `0`
	)		const

inherited

Extracts a file to the output stream.

Parameters

outStream	the (binary) stream where the content of the archive will be put.
index	the index of the file to be extracted.

◆ extractTo() [7/7]

void extractTo	(	std::vector< byte_t > &	outBuffer,
		uint32_t	index = `0`
	)		const

inherited

Extracts a file to the output buffer.

Parameters

outBuffer	the output buffer where the content of the archive will be put.
index	the index of the file to be extracted.

◆ fileCallback()

auto fileCallback ( ) const -> FileCallback

inherited

Returns: the current file callback.

◆ filesCount()

auto filesCount ( ) const -> uint32_t

Returns: the number of files contained in the archive.

◆ find()

auto find ( const tstring & path ) const -> BitInputArchive::ConstIterator

noexceptinherited

Find an item in the archive that has the given path.

Parameters

path	the path to be searched in the archive.

Returns: an iterator to the item with the given path, or an iterator equal to the end() iterator if no item is found.

◆ foldersCount()

auto foldersCount ( ) const -> uint32_t

Returns: the number of folders contained in the archive.

◆ format()

auto format ( ) const -> const BitInFormat &override

overridevirtualnoexceptinherited

Returns: the archive format used by the archive opener.

Implements BitAbstractArchiveHandler.

◆ handler()

auto handler ( ) const -> const BitAbstractArchiveHandler &

noexceptinherited

Returns: the BitAbstractArchiveHandler object containing the settings for reading the archive.

◆ hasEncryptedItems()

auto hasEncryptedItems ( ) const -> bool

Returns: true if and only if the archive has at least one encrypted item.

◆ isEncrypted() [1/2]

auto isEncrypted ( ) const -> bool

Returns: true if and only if the archive has only encrypted items.

◆ isEncrypted() [2/2]

template<typename T >

static auto isEncrypted	(	const Bit7zLibrary &	lib,
		T &&	inArchive,
		const BitInFormat &	format = `BitFormat::Auto`
	)		-> bool

inlinestatic

Checks if the given archive contains only encrypted items.

Note: A header-encrypted archive is also encrypted, but the contrary is not generally true.; An archive might contain both plain and encrypted files; in this case, this function will return false.

Template Parameters

T	The input type of the archive (i.e., file path, buffer, or standard stream).

Parameters

lib	the 7z library used.
inArchive	the archive to be read.
format	the format of the input archive.

Returns: true if and only if the archive has only encrypted items.

◆ isHeaderEncrypted()

template<typename T >

static auto isHeaderEncrypted	(	const Bit7zLibrary &	lib,
		T &&	inArchive,
		const BitInFormat &	format = `BitFormat::Auto`
	)		-> bool

inlinestatic

Checks if the given archive is header-encrypted or not.

Template Parameters

T	The input type of the archive (i.e., file path, buffer, or standard stream).

Parameters

lib	the 7z library used.
inArchive	the archive to be read.
format	the format of the input archive.

Returns: true if and only if the archive has at least one encrypted item.

◆ isItemEncrypted()

auto isItemEncrypted ( uint32_t index ) const -> bool

inherited

Parameters

index the index of an item in the archive.

Returns: true if and only if the item at the given index is encrypted.

◆ isItemFolder()

auto isItemFolder ( uint32_t index ) const -> bool

inherited

Parameters

index the index of an item in the archive.

Returns: true if and only if the item at the given index is a folder.

◆ isMultiVolume()

auto isMultiVolume ( ) const -> bool

Returns: true if and only if the archive is composed by multiple volumes.

◆ isPasswordDefined()

auto isPasswordDefined ( ) const -> bool

noexceptinherited

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

◆ isSolid()

auto isSolid ( ) const -> bool

Returns: true if and only if the archive was created using solid compression.

◆ itemAt()

auto itemAt ( uint32_t index ) const -> BitArchiveItemOffset

inherited

Retrieve the item at the given index.

Parameters

index the index of the item to be retrieved.

Returns: the item at the given index within the archive.

◆ itemProperty()

auto itemProperty	(	uint32_t	index,
		BitProperty	property
	)		const -> BitPropVariant

inherited

Gets the specified property of an item in the archive.

Parameters

index	the index (in the archive) of the item.
property	the property to be retrieved.

Returns: the current value of the item property or an empty BitPropVariant if the item has no value for the property.

◆ items()

auto items ( ) const -> vector< BitArchiveItemInfo >

Returns: a vector of all the archive items as BitArchiveItem objects.

◆ itemsCount()

auto itemsCount ( ) const -> uint32_t

inherited

Returns: the number of items contained in the archive.

◆ library()

auto library ( ) const -> const Bit7zLibrary &

noexceptinherited

Returns: the Bit7zLibrary object used by the handler.

◆ overwriteMode()

auto overwriteMode ( ) const -> OverwriteMode

inherited

Returns: the current OverwriteMode.

◆ packSize()

auto packSize ( ) const -> uint64_t

Returns: the total compressed size of the archive content.

◆ password()

auto password ( ) const -> tstring

inherited

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

◆ passwordCallback()

auto passwordCallback ( ) const -> PasswordCallback

inherited

Returns: the current password callback.

◆ progressCallback()

auto progressCallback ( ) const -> ProgressCallback

inherited

Returns: the current progress callback.

◆ ratioCallback()

auto ratioCallback ( ) 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.

◆ size()

auto size ( ) const -> uint64_t

Returns: the total uncompressed size of the archive content.

◆ test()

void test ( ) const

inherited

Tests the archive without extracting its content.

If the archive is not valid, a BitException is thrown!

◆ testItem()

void testItem ( uint32_t index ) const

inherited

Tests the item at the given index inside the archive without extracting it.

If the archive is not valid, or there's no item at the given index, a BitException is thrown!

Parameters

index the index of the file to be tested.

◆ totalCallback()

auto totalCallback ( ) const -> TotalCallback

inherited

Returns: the current total callback.

◆ volumesCount()

auto volumesCount ( ) const -> uint32_t

Returns: the number of volumes composing the archive.

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

include/bit7z/bitarchivereader.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BitArchiveReader() [1/3]

◆ BitArchiveReader() [2/3]

◆ BitArchiveReader() [3/3]

◆ ~BitArchiveReader()

Member Function Documentation

◆ archivePath()

◆ archiveProperties()

◆ archiveProperty()

◆ begin()

◆ cbegin()

◆ cend()

◆ clearPassword()

◆ contains()

◆ detectedFormat()

◆ end()

◆ extractionFormat()

◆ extractTo() [1/7]

◆ extractTo() [2/7]

◆ extractTo() [3/7]

◆ extractTo() [4/7]

◆ extractTo() [5/7]

◆ extractTo() [6/7]

◆ extractTo() [7/7]

◆ fileCallback()

◆ filesCount()

◆ find()

◆ foldersCount()

◆ format()

◆ handler()

◆ hasEncryptedItems()

◆ isEncrypted() [1/2]

◆ isEncrypted() [2/2]

◆ isHeaderEncrypted()

◆ isItemEncrypted()

◆ isItemFolder()

◆ isMultiVolume()

◆ isPasswordDefined()

◆ isSolid()

◆ itemAt()

◆ itemProperty()

◆ items()

◆ itemsCount()

◆ library()

◆ overwriteMode()

◆ packSize()

◆ password()

◆ passwordCallback()

◆ progressCallback()

◆ ratioCallback()

◆ retainDirectories()

◆ setFileCallback()

◆ setOverwriteMode()

◆ setPassword()

◆ setPasswordCallback()

◆ setProgressCallback()

◆ setRatioCallback()

◆ setRetainDirectories()

◆ setTotalCallback()

◆ size()

◆ test()

◆ testItem()

◆ totalCallback()

◆ volumesCount()