diff --git a/cryptlib.h b/cryptlib.h index 7e105a3c..445cd9b2 100644 --- a/cryptlib.h +++ b/cryptlib.h @@ -202,6 +202,9 @@ private: class CRYPTOPP_DLL InvalidArgument : public Exception { public: + /// \brief Construct an InvalidArgument + /// \param s the message for the exception + /// \details The member function what() returns s. explicit InvalidArgument(const std::string &s) : Exception(INVALID_ARGUMENT, s) {} }; @@ -209,6 +212,9 @@ public: class CRYPTOPP_DLL InvalidDataFormat : public Exception { public: + /// \brief Construct an InvalidDataFormat + /// \param s the message for the exception + /// \details The member function what() returns s. explicit InvalidDataFormat(const std::string &s) : Exception(INVALID_DATA_FORMAT, s) {} }; @@ -216,6 +222,9 @@ public: class CRYPTOPP_DLL InvalidCiphertext : public InvalidDataFormat { public: + /// \brief Construct an InvalidCiphertext + /// \param s the message for the exception + /// \details The member function what() returns s. explicit InvalidCiphertext(const std::string &s) : InvalidDataFormat(s) {} }; @@ -223,6 +232,9 @@ public: class CRYPTOPP_DLL NotImplemented : public Exception { public: + /// \brief Construct an NotImplemented + /// \param s the message for the exception + /// \details The member function what() returns s. explicit NotImplemented(const std::string &s) : Exception(NOT_IMPLEMENTED, s) {} }; @@ -230,6 +242,9 @@ public: class CRYPTOPP_DLL CannotFlush : public Exception { public: + /// \brief Construct an CannotFlush + /// \param s the message for the exception + /// \details The member function what() returns s. explicit CannotFlush(const std::string &s) : Exception(CANNOT_FLUSH, s) {} }; @@ -238,6 +253,13 @@ class CRYPTOPP_DLL OS_Error : public Exception { public: virtual ~OS_Error() throw() {} + + /// \brief Construct an OS_Error + /// \param errorType the error type + /// \param s the message for the exception + /// \param operation the operation for the exception + /// \param errorCode the error code + /// \details The member function what() returns s. OS_Error(ErrorType errorType, const std::string &s, const std::string& operation, int errorCode) : Exception(errorType, s), m_operation(operation), m_errorCode(errorCode) {} @@ -255,7 +277,8 @@ protected: struct CRYPTOPP_DLL DecodingResult { /// \brief Constructs a DecodingResult - /// \details isValidCoding is initialized to false and messageLength is initialized to 0. + /// \details isValidCoding is initialized to false and messageLength is + /// initialized to 0. explicit DecodingResult() : isValidCoding(false), messageLength(0) {} /// \brief Constructs a DecodingResult /// \param len the message length @@ -264,11 +287,13 @@ struct CRYPTOPP_DLL DecodingResult /// \brief Compare two DecodingResult /// \param rhs the other DecodingResult - /// \return true if both isValidCoding and messageLength are equal, false otherwise + /// \return true if either isValidCoding or messageLength is \a not equal, + /// false otherwise bool operator==(const DecodingResult &rhs) const {return isValidCoding == rhs.isValidCoding && messageLength == rhs.messageLength;} /// \brief Compare two DecodingResult /// \param rhs the other DecodingResult - /// \return true if either isValidCoding or messageLength is \a not equal, false otherwise + /// \return true if either isValidCoding or messageLength is \a not equal, + /// false otherwise /// \details Returns !operator==(rhs). bool operator!=(const DecodingResult &rhs) const {return !operator==(rhs);} @@ -279,24 +304,28 @@ struct CRYPTOPP_DLL DecodingResult }; /// \brief Interface for retrieving values given their names -/// \details This class is used to safely pass a variable number of arbitrarily typed arguments to functions -/// and to read values from keys and crypto parameters. -/// \details To obtain an object that implements NameValuePairs for the purpose of parameter -/// passing, use the MakeParameters() function. -/// \details To get a value from NameValuePairs, you need to know the name and the type of the value. -/// Call GetValueNames() on a NameValuePairs object to obtain a list of value names that it supports. -/// then look at the Name namespace documentation to see what the type of each value is, or -/// alternatively, call GetIntValue() with the value name, and if the type is not int, a -/// ValueTypeMismatch exception will be thrown and you can get the actual type from the exception object. +/// \details This class is used to safely pass a variable number of arbitrarily +/// typed arguments to functions and to read values from keys and crypto parameters. +/// \details To obtain an object that implements NameValuePairs for the purpose of +/// parameter passing, use the MakeParameters() function. +/// \details To get a value from NameValuePairs, you need to know the name and the +/// type of the value. Call GetValueNames() on a NameValuePairs object to obtain a +/// list of value names that it supports. then look at the Name namespace +/// documentation to see what the type of each value is, or alternatively, call +/// GetIntValue() with the value name, and if the type is not int, a +/// ValueTypeMismatch exception will be thrown and you can get the actual type from +/// the exception object. /// \sa NullNameValuePairs, g_nullNameValuePairs, -/// NameValuePairs on the Crypto++ wiki +/// NameValuePairs on the +/// Crypto++ wiki class NameValuePairs { public: virtual ~NameValuePairs() {} /// \brief Thrown when an unexpected type is encountered - /// \details Exception thrown when trying to retrieve a value using a different type than expected + /// \details Exception thrown when trying to retrieve a value using a different + /// type than expected class CRYPTOPP_DLL ValueTypeMismatch : public InvalidArgument { public: @@ -1789,18 +1818,23 @@ public: /// \brief Flush buffered input and/or output, with signal propagation /// \param hardFlush is used to indicate whether all data should be flushed - /// \param propagation the number of attached transformations the Flush() signal should be passed - /// \param blocking specifies whether the object should block when processing input - /// \details propagation count includes this object. Setting propagation to 1 means this - /// object only. Setting propagation to -1 means unlimited propagation. - /// \note Hard flushes must be used with care. It means try to process and output everything, even if - /// there may not be enough data to complete the action. For example, hard flushing a HexDecoder - /// would cause an error if you do it after inputing an odd number of hex encoded characters. - /// \note For some types of filters, like ZlibDecompressor, hard flushes can only - /// be done at "synchronization points". These synchronization points are positions in the data - /// stream that are created by hard flushes on the corresponding reverse filters, in this - /// example ZlibCompressor. This is useful when zlib compressed data is moved across a - /// network in packets and compression state is preserved across packets, as in the SSH2 protocol. + /// \param propagation the number of attached transformations the Flush() + /// signal should be passed + /// \param blocking specifies whether the object should block when processing + /// input + /// \details propagation count includes this object. Setting propagation to + /// 1 means this object only. Setting propagation to -1 + /// means unlimited propagation. + /// \note Hard flushes must be used with care. It means try to process and + /// output everything, even if there may not be enough data to complete the + /// action. For example, hard flushing a HexDecoder would cause an error if + /// you do it after inputing an odd number of hex encoded characters. + /// \note For some types of filters, like ZlibDecompressor, hard flushes can + /// only be done at "synchronization points". These synchronization points + /// are positions in the data stream that are created by hard flushes on the + /// corresponding reverse filters, in this example ZlibCompressor. This is + /// useful when zlib compressed data is moved across a network in packets + /// and compression state is preserved across packets, as in the SSH2 protocol. virtual bool Flush(bool hardFlush, int propagation=-1, bool blocking=true); /// \brief Marks the end of a series of messages, with signal propagation diff --git a/simple.h b/simple.h index f14cf2ba..37eeca85 100644 --- a/simple.h +++ b/simple.h @@ -25,6 +25,9 @@ template class CRYPTOPP_NO_VTABLE ClonableImpl : public BASE { public: + /// \brief Create a copy of this object + /// \returns a copy of this object + /// \details The caller is responsible for freeing the object. Clonable * Clone() const {return new DERIVED(*static_cast(this));} }; @@ -52,6 +55,9 @@ public: class CRYPTOPP_DLL InvalidKeyLength : public InvalidArgument { public: + /// \brief Construct an InvalidKeyLength + /// \param algorithm the Algorithm associated with the exception + /// \param length the key size associated with the exception explicit InvalidKeyLength(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid key length") {} }; @@ -59,6 +65,9 @@ public: class CRYPTOPP_DLL InvalidRounds : public InvalidArgument { public: + /// \brief Construct an InvalidRounds + /// \param algorithm the Algorithm associated with the exception + /// \param rounds the number of rounds associated with the exception explicit InvalidRounds(const std::string &algorithm, unsigned int rounds) : InvalidArgument(algorithm + ": " + IntToString(rounds) + " is not a valid number of rounds") {} }; @@ -66,6 +75,9 @@ public: class CRYPTOPP_DLL InvalidBlockSize : public InvalidArgument { public: + /// \brief Construct an InvalidBlockSize + /// \param algorithm the Algorithm associated with the exception + /// \param length the block size associated with the exception explicit InvalidBlockSize(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid block size") {} }; @@ -73,6 +85,9 @@ public: class CRYPTOPP_DLL InvalidDerivedKeyLength : public InvalidArgument { public: + /// \brief Construct an InvalidDerivedKeyLength + /// \param algorithm the Algorithm associated with the exception + /// \param length the size associated with the exception explicit InvalidDerivedKeyLength(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid derived key length") {} }; @@ -80,6 +95,9 @@ public: class CRYPTOPP_DLL InvalidPersonalizationLength : public InvalidArgument { public: + /// \brief Construct an InvalidPersonalizationLength + /// \param algorithm the Algorithm associated with the exception + /// \param length the personalization size associated with the exception explicit InvalidPersonalizationLength(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid salt length") {} }; @@ -87,6 +105,9 @@ public: class CRYPTOPP_DLL InvalidSaltLength : public InvalidArgument { public: + /// \brief Construct an InvalidSaltLength + /// \param algorithm the Algorithm associated with the exception + /// \param length the salt size associated with the exception explicit InvalidSaltLength(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid salt length") {} }; @@ -98,6 +119,10 @@ template class CRYPTOPP_NO_VTABLE Bufferless : public T { public: + /// \brief Flushes data buffered by this object, without signal propagation + /// \param hardFlush indicates whether all data should be flushed + /// \param blocking specifies whether the object should block when processing input + /// \note hardFlush must be used with care bool IsolatedFlush(bool hardFlush, bool blocking) {CRYPTOPP_UNUSED(hardFlush); CRYPTOPP_UNUSED(blocking); return false;} }; @@ -108,10 +133,45 @@ template class CRYPTOPP_NO_VTABLE Unflushable : public T { public: + /// \brief Flush buffered input and/or output, with signal propagation + /// \param hardFlush is used to indicate whether all data should be flushed + /// \param propagation the number of attached transformations the Flush() + /// signal should be passed + /// \param blocking specifies whether the object should block when processing + /// input + /// \details propagation count includes this object. Setting propagation to + /// 1 means this object only. Setting propagation to -1 + /// means unlimited propagation. + /// \note Hard flushes must be used with care. It means try to process and + /// output everything, even if there may not be enough data to complete the + /// action. For example, hard flushing a HexDecoder would cause an error if + /// you do it after inputing an odd number of hex encoded characters. + /// \note For some types of filters, like ZlibDecompressor, hard flushes can + /// only be done at "synchronization points". These synchronization points + /// are positions in the data stream that are created by hard flushes on the + /// corresponding reverse filters, in this example ZlibCompressor. This is + /// useful when zlib compressed data is moved across a network in packets + /// and compression state is preserved across packets, as in the SSH2 protocol. bool Flush(bool completeFlush, int propagation=-1, bool blocking=true) {return ChannelFlush(DEFAULT_CHANNEL, completeFlush, propagation, blocking);} + + /// \brief Flushes data buffered by this object, without signal propagation + /// \param hardFlush indicates whether all data should be flushed + /// \param blocking specifies whether the object should block when processing input + /// \note hardFlush must be used with care bool IsolatedFlush(bool hardFlush, bool blocking) {CRYPTOPP_UNUSED(hardFlush); CRYPTOPP_UNUSED(blocking); CRYPTOPP_ASSERT(false); return false;} + + /// \brief Flush buffered input and/or output on a channel + /// \param channel the channel to flush the data + /// \param hardFlush is used to indicate whether all data should be flushed + /// \param propagation the number of attached transformations the ChannelFlush() + /// signal should be passed + /// \param blocking specifies whether the object should block when processing input + /// \return true of the Flush was successful + /// \details propagation count includes this object. Setting propagation to + /// 1 means this object only. Setting propagation to -1 means + /// unlimited propagation. bool ChannelFlush(const std::string &channel, bool hardFlush, int propagation=-1, bool blocking=true) { if (hardFlush && !InputBufferIsEmpty())