diff --git a/gzip.h b/gzip.h index 98d6e26b..8850cf60 100644 --- a/gzip.h +++ b/gzip.h @@ -1,3 +1,8 @@ +// gzip.h - written and placed in the public domain by Wei Dai + +//! \file gzip.h +//! \brief GZIP compression and decompression (RFC 1952) + #ifndef CRYPTOPP_GZIP_H #define CRYPTOPP_GZIP_H @@ -8,12 +13,25 @@ NAMESPACE_BEGIN(CryptoPP) -/// GZIP Compression (RFC 1952) +//! \class Gzip +//! \brief GZIP Compression (RFC 1952) class Gzip : public Deflator { public: + //! \brief Construct a Gzip compressor + //! \param attachment an attached transformation + //! \param deflateLevel the deflate level + //! \param log2WindowSize the window size + //! \param detectUncompressible flag to detect if data is compressible + //! \details detectUncompressible makes it faster to process uncompressible files, but + //! if a file has both compressible and uncompressible parts, it may fail to compress + //! some of the compressible parts. Gzip(BufferedTransformation *attachment=NULL, unsigned int deflateLevel=DEFAULT_DEFLATE_LEVEL, unsigned int log2WindowSize=DEFAULT_LOG2_WINDOW_SIZE, bool detectUncompressible=true) : Deflator(attachment, deflateLevel, log2WindowSize, detectUncompressible), m_totalLen(0) {} + //! \brief Construct a Gzip compressor + //! \param parameters a set of NameValuePairs to initialize this object + //! \param attachment an attached transformation + //! \details Possible parameter names: Log2WindowSize, DeflateLevel, DetectUncompressible Gzip(const NameValuePairs ¶meters, BufferedTransformation *attachment=NULL) : Deflator(parameters, attachment), m_totalLen(0) {} @@ -35,13 +53,22 @@ class Gunzip : public Inflator { public: typedef Inflator::Err Err; + + //! \class HeaderErr + //! \brief Exception thrown when a header decoding error occurs class HeaderErr : public Err {public: HeaderErr() : Err(INVALID_DATA_FORMAT, "Gunzip: header decoding error") {}}; + //! \class TailErr + //! \brief Exception thrown when the tail is too short class TailErr : public Err {public: TailErr() : Err(INVALID_DATA_FORMAT, "Gunzip: tail too short") {}}; + //! \class CrcErr + //! \brief Exception thrown when a CRC error occurs class CrcErr : public Err {public: CrcErr() : Err(DATA_INTEGRITY_CHECK_FAILED, "Gunzip: CRC check error") {}}; + //! \class LengthErr + //! \brief Exception thrown when a length error occurs class LengthErr : public Err {public: LengthErr() : Err(DATA_INTEGRITY_CHECK_FAILED, "Gunzip: length check error") {}}; - //! \brief Construct a Gunzip - //! \param attachment a \ BufferedTransformation to attach to this object + //! \brief Construct a Gunzip decompressor + //! \param attachment an attached transformation //! \param repeat decompress multiple compressed streams in series //! \param autoSignalPropagation 0 to turn off MessageEnd signal Gunzip(BufferedTransformation *attachment = NULL, bool repeat = false, int autoSignalPropagation = -1); diff --git a/zdeflate.h b/zdeflate.h index 2d1b9be9..de221668 100644 --- a/zdeflate.h +++ b/zdeflate.h @@ -1,3 +1,8 @@ +// zdeflate.h - written and placed in the public domain by Wei Dai + +//! \file zdeflate.h +//! \brief DEFLATE compression and decompression (RFC 1951) + #ifndef CRYPTOPP_ZDEFLATE_H #define CRYPTOPP_ZDEFLATE_H @@ -7,11 +12,14 @@ NAMESPACE_BEGIN(CryptoPP) -//! _ +//! \brief Encoding table writer class LowFirstBitWriter : public Filter { public: + //! \brief Construct a LowFirstBitWriter + //! \param attachment an attached transformation LowFirstBitWriter(BufferedTransformation *attachment); + void PutBits(unsigned long value, unsigned int length); void FlushBitBuffer(); void ClearBitBuffer(); @@ -60,23 +68,55 @@ public: SecBlock m_valueToCode; }; -//! DEFLATE (RFC 1951) compressor - +//! \class Deflator +//! \brief DEFLATE compressor (RFC 1951) class Deflator : public LowFirstBitWriter { public: - enum {MIN_DEFLATE_LEVEL = 0, DEFAULT_DEFLATE_LEVEL = 6, MAX_DEFLATE_LEVEL = 9}; - enum {MIN_LOG2_WINDOW_SIZE = 9, DEFAULT_LOG2_WINDOW_SIZE = 15, MAX_LOG2_WINDOW_SIZE = 15}; - /*! \note detectUncompressible makes it faster to process uncompressible files, but - if a file has both compressible and uncompressible parts, it may fail to compress some of the - compressible parts. */ + //! \brief Deflate level as enumerated values. + enum { + //! \brief Minimum deflation level, fastest speed (0) + MIN_DEFLATE_LEVEL = 0, + //! \brief Default deflation level, compromise between speed (6) + DEFAULT_DEFLATE_LEVEL = 6, + //! \brief Minimum deflation level, slowest speed (9) + MAX_DEFLATE_LEVEL = 9}; + + //! \brief Windows size as enumerated values. + enum { + //! \brief Minimum window size, smallest table (9) + MIN_LOG2_WINDOW_SIZE = 9, + //! \brief Default window size (15) + DEFAULT_LOG2_WINDOW_SIZE = 15, + //! \brief Maximum window size, largest table (15) + MAX_LOG2_WINDOW_SIZE = 15}; + + //! \brief Construct a Deflator compressor + //! \param attachment an attached transformation + //! \param deflateLevel the deflate level + //! \param log2WindowSize the window size + //! \param detectUncompressible flag to detect if data is compressible + //! \details detectUncompressible makes it faster to process uncompressible files, but + //! if a file has both compressible and uncompressible parts, it may fail to compress + //! some of the compressible parts. Deflator(BufferedTransformation *attachment=NULL, int deflateLevel=DEFAULT_DEFLATE_LEVEL, int log2WindowSize=DEFAULT_LOG2_WINDOW_SIZE, bool detectUncompressible=true); - //! possible parameter names: Log2WindowSize, DeflateLevel, DetectUncompressible + //! \brief Construct a Deflator compressor + //! \param parameters a set of NameValuePairs to initialize this object + //! \param attachment an attached transformation + //! \details Possible parameter names: Log2WindowSize, DeflateLevel, DetectUncompressible Deflator(const NameValuePairs ¶meters, BufferedTransformation *attachment=NULL); - //! this function can be used to set the deflate level in the middle of compression + //! \brief Sets the deflation level + //! \param deflateLevel the level of deflation + //! \details SetDeflateLevel can be used to set the deflate level in the middle of compression void SetDeflateLevel(int deflateLevel); + + //! \brief Retrieves the deflation level + //! \returns the level of deflation int GetDeflateLevel() const {return m_deflateLevel;} + + //! \brief Retrieves the window size + //! \returns the windows size int GetLog2WindowSize() const {return m_log2WindowSize;} void IsolatedInitialize(const NameValuePairs ¶meters);