bit7z 4.0.0
A C++ library for interfacing with the 7-zip shared libs.
Loading...
Searching...
No Matches
BitArchiveWriter Class Reference

The BitArchiveWriter class allows creating new archives or updating old ones with new items. More...

#include <bit7z/bitarchivewriter.hpp>

+ Inheritance diagram for BitArchiveWriter:
+ Collaboration diagram for BitArchiveWriter:

Public Member Functions

 BitArchiveWriter (const Bit7zLibrary &lib, const BitInOutFormat &format)
 Constructs an empty BitArchiveWriter object that can write archives of the specified format.
 
 BitArchiveWriter (const Bit7zLibrary &lib, const std::vector< byte_t > &inArchive, const BitInOutFormat &format, const tstring &password={})
 Constructs a BitArchiveWriter object, reading the archive in the given buffer.
 
 BitArchiveWriter (const Bit7zLibrary &lib, const tstring &inArchive, const BitInOutFormat &format, const tstring &password={})
 Constructs a BitArchiveWriter object, reading the given archive file path.
 
 BitArchiveWriter (const Bit7zLibrary &lib, std::istream &inArchive, const BitInOutFormat &format, const tstring &password={})
 Constructs a BitArchiveWriter object, reading the archive from the given standard input stream.
 
void addDirectory (const tstring &inDir)
 Adds all the items inside the given directory path.
 
void addFile (const std::vector< byte_t > &inBuffer, const tstring &name)
 Adds the given buffer file, using the given name as a path when compressed in the output archive.
 
void addFile (const tstring &inFile, const tstring &name={})
 Adds the given file path, with an optional user-defined path to be used in the output archive.
 
void addFile (std::istream &inStream, const tstring &name)
 Adds the given standard input stream, using the given name as a path when compressed in the output archive.
 
void addFiles (const std::vector< tstring > &inFiles)
 Adds all the files in the given vector of filesystem paths.
 
void addFiles (const tstring &inDir, const tstring &filter="*", bool recursive=true)
 Adds all the files inside the given directory path that match the given wildcard filter.
 
void addFiles (const tstring &inDir, const tstring &filter="*", FilterPolicy policy=FilterPolicy::Include, bool recursive=true)
 Adds all the files inside the given directory path that match the given wildcard filter.
 
void addItems (const std::map< tstring, tstring > &inPaths)
 Adds all the items that can be found by indexing the keys of the given map of filesystem paths; the corresponding mapped values are the user-defined paths wanted inside the output archive.
 
void addItems (const std::vector< tstring > &inPaths)
 Adds all the items that can be found by indexing the given vector of filesystem paths.
 
void clearPassword () noexcept
 Clear the current password used by the handler.
 
auto compressionFormat () const noexcept -> const BitInOutFormat &
 
auto compressionLevel () const noexcept -> BitCompressionLevel
 
auto compressionMethod () const noexcept -> BitCompressionMethod
 
void compressTo (const tstring &outFile)
 Compresses all the items added to this object to the specified archive file path.
 
void compressTo (std::ostream &outStream)
 Compresses all the items added to this object to the specified buffer.
 
void compressTo (std::vector< byte_t > &outBuffer)
 Compresses all the items added to this object to the specified buffer.
 
auto creator () const noexcept -> const BitAbstractArchiveCreator &
 
auto cryptHeaders () const noexcept -> bool
 
auto dictionarySize () const noexcept -> uint32_t
 
auto fileCallback () const -> FileCallback
 
auto format () const noexcept -> const BitInFormat &override
 
auto handler () const noexcept -> const BitAbstractArchiveHandler &
 
auto isPasswordDefined () const noexcept -> bool
 
auto itemsCount () const -> uint32_t
 
auto library () const noexcept -> const Bit7zLibrary &
 
auto overwriteMode () const -> OverwriteMode
 
auto password () const -> tstring
 
auto passwordCallback () const -> PasswordCallback
 
auto progressCallback () const -> ProgressCallback
 
auto ratioCallback () const -> RatioCallback
 
auto retainDirectories () const noexcept -> bool
 
void setCompressionLevel (BitCompressionLevel level) noexcept
 Sets the compression level to be used when creating/updating an archive.
 
void setCompressionMethod (BitCompressionMethod method)
 Sets the compression method to be used when creating/updating an archive.
 
void setDictionarySize (uint32_t dictionarySize)
 Sets the dictionary size to be used when creating/updating an archive.
 
void setFileCallback (const FileCallback &callback)
 Sets the function to be called when the current file being processed changes.
 
template<std::size_t N, typename T , typename = typename std::enable_if< !std::is_integral< T >::value >::type>
void setFormatProperty (const wchar_t(&name)[N], const T &value) noexcept
 Sets a property for the output archive format as described by the 7-zip documentation (e.g., https://sevenzip.osdn.jp/chm/cmdline/switches/method.htm).
 
template<std::size_t N, typename T , typename = typename std::enable_if< std::is_integral< T >::value >::type>
void setFormatProperty (const wchar_t(&name)[N], T value) noexcept
 Sets a property for the output archive format as described by the 7-zip documentation (e.g., https://sevenzip.osdn.jp/chm/cmdline/switches/method.htm).
 
void setOverwriteMode (OverwriteMode mode)
 Sets how the handler should behave when it tries to output to an existing file or buffer.
 
void setPassword (const tstring &password) override
 Sets up a password for the output archives.
 
void setPassword (const tstring &password, bool cryptHeaders)
 Sets up a password for the output archive.
 
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 setSolidMode (bool solidMode) noexcept
 Sets whether to use solid compression or not.
 
void setStoreSymbolicLinks (bool storeSymlinks) noexcept
 Sets whether the creator will store symbolic links as links in the output archive.
 
void setThreadsCount (uint32_t threadsCount) noexcept
 Sets the number of threads to be used when creating/updating an archive.
 
void setTotalCallback (const TotalCallback &callback)
 Sets the function to be called when the total size of an operation is available.
 
void setUpdateMode (bool canUpdate)
 Sets whether the creator can update existing archives or not.
 
virtual void setUpdateMode (UpdateMode mode)
 Sets whether and how the creator can update existing archives or not.
 
void setVolumeSize (uint64_t volumeSize) noexcept
 Sets the volumeSize (in bytes) of the output archive volumes.
 
void setWordSize (uint32_t wordSize)
 Sets the word size to be used when creating/updating an archive.
 
auto solidMode () const noexcept -> bool
 
auto storeSymbolicLinks () const noexcept -> bool
 
auto threadsCount () const noexcept -> uint32_t
 
auto totalCallback () const -> TotalCallback
 
auto updateMode () const noexcept -> UpdateMode
 
auto volumeSize () const noexcept -> uint64_t
 
auto wordSize () const noexcept -> uint32_t
 

Detailed Description

The BitArchiveWriter class allows creating new archives or updating old ones with new items.

Constructor & Destructor Documentation

◆ BitArchiveWriter() [1/4]

BitArchiveWriter ( const Bit7zLibrary lib,
const BitInOutFormat format 
)

Constructs an empty BitArchiveWriter object that can write archives of the specified format.

Parameters
libthe 7z library to use.
formatthe output archive format.

◆ BitArchiveWriter() [2/4]

BitArchiveWriter ( const Bit7zLibrary lib,
const tstring inArchive,
const BitInOutFormat format,
const tstring password = {} 
)

Constructs a BitArchiveWriter object, reading the given archive file path.

Parameters
libthe 7z library to use.
inArchivethe path to an input archive file.
formatthe input/output archive format.
password(optional) the password needed to read the input archive.

◆ BitArchiveWriter() [3/4]

BitArchiveWriter ( const Bit7zLibrary lib,
const std::vector< byte_t > &  inArchive,
const BitInOutFormat format,
const tstring password = {} 
)

Constructs a BitArchiveWriter object, reading the archive in the given buffer.

Parameters
libthe 7z library to use.
inArchivethe buffer containing the input archive.
formatthe input/output archive format.
password(optional) the password needed to read the input archive.

◆ BitArchiveWriter() [4/4]

BitArchiveWriter ( const Bit7zLibrary lib,
std::istream inArchive,
const BitInOutFormat format,
const tstring password = {} 
)

Constructs a BitArchiveWriter object, reading the archive from the given standard input stream.

Parameters
libthe 7z library to use.
inArchivethe standard stream of the input archive.
formatthe input/output archive format.
password(optional) the password needed to read the input archive.

Member Function Documentation

◆ addDirectory()

void addDirectory ( const tstring inDir)
inherited

Adds all the items inside the given directory path.

Parameters
inDirthe directory where to search for items to be added to the output archive.

◆ addFile() [1/3]

void addFile ( const std::vector< byte_t > &  inBuffer,
const tstring name 
)
inherited

Adds the given buffer file, using the given name as a path when compressed in the output archive.

Parameters
inBufferthe buffer containing the file to be added to the output archive.
nameuser-defined path to be used inside the output archive.

◆ addFile() [2/3]

void addFile ( const tstring inFile,
const tstring name = {} 
)
inherited

Adds the given file path, with an optional user-defined path to be used in the output archive.

Note
If a directory path is given, a BitException is thrown.
Parameters
inFilethe path to the filesystem file to be added to the output archive.
name(optional) user-defined path to be used inside the output archive.

◆ addFile() [3/3]

void addFile ( std::istream inStream,
const tstring name 
)
inherited

Adds the given standard input stream, using the given name as a path when compressed in the output archive.

Parameters
inStreamthe input stream to be added.
namethe name of the file inside the output archive.

◆ addFiles() [1/3]

void addFiles ( const std::vector< tstring > &  inFiles)
inherited

Adds all the files in the given vector of filesystem paths.

Note
Paths to directories are ignored.
Parameters
inFilesthe vector of paths to files.

◆ addFiles() [2/3]

void addFiles ( const tstring inDir,
const tstring filter = "*",
bool  recursive = true 
)
inherited

Adds all the files inside the given directory path that match the given wildcard filter.

Parameters
inDirthe directory where to search for files to be added to the output archive.
filter(optional) the wildcard filter to be used for searching the files.
recursive(optional) recursively search the files in the given directory and all of its subdirectories.

◆ addFiles() [3/3]

void addFiles ( const tstring inDir,
const tstring filter = "*",
FilterPolicy  policy = FilterPolicy::Include,
bool  recursive = true 
)
inherited

Adds all the files inside the given directory path that match the given wildcard filter.

Parameters
inDirthe directory where to search for files to be added to the output archive.
filter(optional) the wildcard filter to be used for searching the files.
recursive(optional) recursively search the files in the given directory and all of its subdirectories.
policy(optional) the filtering policy to be applied to the matched items.

◆ addItems() [1/2]

void addItems ( const std::map< tstring, tstring > &  inPaths)
inherited

Adds all the items that can be found by indexing the keys of the given map of filesystem paths; the corresponding mapped values are the user-defined paths wanted inside the output archive.

Parameters
inPathsmap of filesystem paths with the corresponding user-defined path desired inside the output archive.

◆ addItems() [2/2]

void addItems ( const std::vector< tstring > &  inPaths)
inherited

Adds all the items that can be found by indexing the given vector of filesystem paths.

Parameters
inPathsthe vector of filesystem paths.

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

◆ compressionFormat()

auto compressionFormat ( ) const -> const BitInOutFormat &
noexceptinherited
Returns
the format used for creating/updating an archive.

◆ compressionLevel()

auto compressionLevel ( ) const -> BitCompressionLevel
noexceptinherited
Returns
the compression level used for creating/updating an archive.

◆ compressionMethod()

auto compressionMethod ( ) const -> BitCompressionMethod
noexceptinherited
Returns
the compression method used for creating/updating an archive.

◆ compressTo() [1/3]

void compressTo ( const tstring outFile)
inherited

Compresses all the items added to this object to the specified archive file path.

Note
If this object was created by passing an input archive file path, and this latter is the same as the outFile path parameter, the file will be updated.
Parameters
outFilethe output archive file path.

◆ compressTo() [2/3]

void compressTo ( std::ostream outStream)
inherited

Compresses all the items added to this object to the specified buffer.

Parameters
outStreamthe output standard stream.

◆ compressTo() [3/3]

void compressTo ( std::vector< byte_t > &  outBuffer)
inherited

Compresses all the items added to this object to the specified buffer.

Parameters
outBufferthe output buffer.

◆ creator()

auto creator ( ) const -> const BitAbstractArchiveCreator &
noexceptinherited
Returns
a constant reference to the BitAbstractArchiveHandler object containing the settings for writing the output archive.

◆ cryptHeaders()

auto cryptHeaders ( ) const -> bool
noexceptinherited
Returns
whether the creator crypts also the headers of archives or not.

◆ dictionarySize()

auto dictionarySize ( ) const -> uint32_t
noexceptinherited
Returns
the dictionary size used for creating/updating an archive.

◆ fileCallback()

auto fileCallback ( ) const -> FileCallback
inherited
Returns
the current file callback.

◆ format()

auto format ( ) const -> const BitInFormat &override
overridevirtualnoexceptinherited
Returns
the format used for creating/updating an archive.

Implements BitAbstractArchiveHandler.

◆ handler()

auto handler ( ) const -> const BitAbstractArchiveHandler &
noexceptinherited
Returns
a constant reference to the BitAbstractArchiveHandler object containing the settings for writing the output archive.

◆ isPasswordDefined()

auto isPasswordDefined ( ) const -> bool
noexceptinherited
Returns
a boolean value indicating whether a password is defined or not.

◆ itemsCount()

auto itemsCount ( ) const -> uint32_t
inherited
Returns
the total number of items added to the output archive object.

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

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

◆ setCompressionLevel()

void setCompressionLevel ( BitCompressionLevel  level)
noexceptinherited

Sets the compression level to be used when creating/updating an archive.

Parameters
levelthe compression level desired.

◆ setCompressionMethod()

void setCompressionMethod ( BitCompressionMethod  method)
inherited

Sets the compression method to be used when creating/updating an archive.

Parameters
methodthe compression method desired.

◆ setDictionarySize()

void setDictionarySize ( uint32_t  dictionarySize)
inherited

Sets the dictionary size to be used when creating/updating an archive.

Parameters
dictionarySizethe dictionary size desired.

◆ setFileCallback()

void setFileCallback ( const FileCallback callback)
inherited

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

Parameters
callbackthe file callback to be used.

◆ setFormatProperty() [1/2]

template<std::size_t N, typename T , typename = typename std::enable_if< !std::is_integral< T >::value >::type>
void setFormatProperty ( const wchar_t(&)  name[N],
const T &  value 
)
inlinenoexceptinherited

Sets a property for the output archive format as described by the 7-zip documentation (e.g., https://sevenzip.osdn.jp/chm/cmdline/switches/method.htm).

For example, passing the string L"tm" with a false value while creating a .7z archive will disable storing the last modified timestamps of the compressed files.

Template Parameters
TA non-integral type (i.e., a string).
Parameters
nameThe string name of the property to be set.
valueThe value to be used for the property.

◆ setFormatProperty() [2/2]

template<std::size_t N, typename T , typename = typename std::enable_if< std::is_integral< T >::value >::type>
void setFormatProperty ( const wchar_t(&)  name[N],
value 
)
inlinenoexceptinherited

Sets a property for the output archive format as described by the 7-zip documentation (e.g., https://sevenzip.osdn.jp/chm/cmdline/switches/method.htm).

Template Parameters
TAn integral type (i.e., a bool or an integer type).
Parameters
nameThe string name of the property to be set.
valueThe value to be used for the property.

◆ setOverwriteMode()

void setOverwriteMode ( OverwriteMode  mode)
inherited

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

Parameters
modethe OverwriteMode to be used by the handler.

◆ setPassword() [1/2]

void setPassword ( const tstring password)
overridevirtualinherited

Sets up a password for the output archives.

When setting a password, the produced archives will be encrypted using the default cryptographic method of the output format. The option "crypt headers" remains unchanged, in contrast with what happens when calling the setPassword(tstring, bool) method.

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).
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 (inherited from BitAbstractArchiveHandler), which is equivalent to setPassword(L"").
Parameters
passwordthe password to be used when creating/updating archives.

Reimplemented from BitAbstractArchiveHandler.

◆ setPassword() [2/2]

void setPassword ( const tstring password,
bool  cryptHeaders 
)
inherited

Sets up a password for the output archive.

When setting a password, the produced archive will be encrypted using the default cryptographic method of the output format. If the format is 7z, and the option "cryptHeaders" is set to true, the headers of the archive will be encrypted, resulting in a password request every time the output file will be opened.

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).
Calling setPassword with "cryptHeaders" set to true does not have effects on formats different from 7z.
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 (inherited from BitAbstractArchiveHandler), which is equivalent to setPassword(L"").
Parameters
passwordthe password to be used when creating/updating archives.
cryptHeadersif true, the headers of the output archives will be encrypted (valid only when using the 7z format).

◆ setPasswordCallback()

void setPasswordCallback ( const PasswordCallback callback)
inherited

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

Parameters
callbackthe 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
callbackthe 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
callbackthe 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
retainthe setting for preserving or not the input directory structure

◆ setSolidMode()

void setSolidMode ( bool  solidMode)
noexceptinherited

Sets whether to use solid compression or not.

Note
Setting the solid compression mode to true has effect only when using the 7z format with multiple input files.
Parameters
solidModeif true, it will be used the "solid compression" method.

◆ setStoreSymbolicLinks()

void setStoreSymbolicLinks ( bool  storeSymlinks)
noexceptinherited

Sets whether the creator will store symbolic links as links in the output archive.

Parameters
storeSymlinksif true, symbolic links will be stored as links.

◆ setThreadsCount()

void setThreadsCount ( uint32_t  threadsCount)
noexceptinherited

Sets the number of threads to be used when creating/updating an archive.

Parameters
threadsCountthe number of threads desired.

◆ setTotalCallback()

void setTotalCallback ( const TotalCallback callback)
inherited

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

Parameters
callbackthe total callback to be used.

◆ setUpdateMode() [1/2]

void setUpdateMode ( bool  canUpdate)
inherited

Sets whether the creator can update existing archives or not.

Deprecated:
since v4.0; it is provided just for an easier transition from the old v3 API.
Note
If set to false, a subsequent compression operation may throw an exception if it targets an existing archive.
Parameters
canUpdateif true, compressing operations will update existing archives.

◆ setUpdateMode() [2/2]

virtual void setUpdateMode ( UpdateMode  mode)
virtualinherited

Sets whether and how the creator can update existing archives or not.

Note
If set to UpdateMode::None, a subsequent compression operation may throw an exception if it targets an existing archive.
Parameters
modethe desired update mode.

Reimplemented in BitArchiveEditor.

◆ setVolumeSize()

void setVolumeSize ( uint64_t  volumeSize)
noexceptinherited

Sets the volumeSize (in bytes) of the output archive volumes.

Note
This setting has effects only when the destination archive is on the filesystem.
Parameters
volumeSizeThe dimension of a volume.

◆ setWordSize()

void setWordSize ( uint32_t  wordSize)
inherited

Sets the word size to be used when creating/updating an archive.

Parameters
wordSizethe word size desired.

◆ solidMode()

auto solidMode ( ) const -> bool
noexceptinherited
Returns
whether the archive creator uses solid compression or not.

◆ storeSymbolicLinks()

auto storeSymbolicLinks ( ) const -> bool
noexceptinherited
Returns
whether the archive creator stores symbolic links as links in the output archive.

◆ threadsCount()

auto threadsCount ( ) const -> uint32_t
noexceptinherited
Returns
the number of threads used when creating/updating an archive (a 0 value means that it will use the 7-zip default value).

◆ totalCallback()

auto totalCallback ( ) const -> TotalCallback
inherited
Returns
the current total callback.

◆ updateMode()

auto updateMode ( ) const -> UpdateMode
noexceptinherited
Returns
the update mode used when updating existing archives.

◆ volumeSize()

auto volumeSize ( ) const -> uint64_t
noexceptinherited
Returns
the volume size (in bytes) used when creating multi-volume archives (a 0 value means that all files are going in a single archive).

◆ wordSize()

auto wordSize ( ) const -> uint32_t
noexceptinherited
Returns
the word size used for creating/updating an archive.

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