From 2a8670c0c18a8b7d049967a45e2a4cbbfd84d085 Mon Sep 17 00:00:00 2001 From: Jeffrey Walton Date: Sat, 12 Nov 2016 08:38:50 -0500 Subject: [PATCH] Updated documentation --- files.h | 79 +++++++++++++++++++++++++++++++++++++++++++++++++------ filters.h | 2 +- 2 files changed, 72 insertions(+), 9 deletions(-) diff --git a/files.h b/files.h index 554ae848..0c650f54 100644 --- a/files.h +++ b/files.h @@ -1,3 +1,9 @@ +// files.h - written and placed in the public domain by Wei Dai + +//! \file files.h +//! \brief Classes providing file-based library services +//! \since Crypto++ 1.0 + #ifndef CRYPTOPP_FILES_H #define CRYPTOPP_FILES_H @@ -11,29 +17,46 @@ NAMESPACE_BEGIN(CryptoPP) -//! file-based implementation of Store interface +//! \class FileStore +//! \brief Implementation of Store interface +//! \details file-based implementation of Store interface class CRYPTOPP_DLL FileStore : public Store, private FilterPutSpaceHelper, public NotCopyable { public: + //! \brief Exception thrown when file-based error is encountered class Err : public Exception { public: Err(const std::string &s) : Exception(IO_ERROR, s) {} }; + //! \brief Exception thrown when file-based open error is encountered class OpenErr : public Err {public: OpenErr(const std::string &filename) : Err("FileStore: error opening file for reading: " + filename) {}}; + //! \brief Exception thrown when file-based read error is encountered class ReadErr : public Err {public: ReadErr() : Err("FileStore: error reading file") {}}; + //! \brief Construct a FileStore FileStore() : m_stream(NULL), m_space(NULL), m_len(0), m_waiting(0) {} + + //! \brief Construct a FileStore + //! \param in an existing stream FileStore(std::istream &in) : m_stream(NULL), m_space(NULL), m_len(0), m_waiting(0) {StoreInitialize(MakeParameters(Name::InputStreamPointer(), &in));} + + //! \brief Construct a FileStore + //! \param filename the narrow name of the file to open FileStore(const char *filename) : m_stream(NULL), m_space(NULL), m_len(0), m_waiting(0) {StoreInitialize(MakeParameters(Name::InputFileName(), filename ? filename : ""));} -#if defined(CRYPTOPP_UNIX_AVAILABLE) || _MSC_VER >= 1400 - //! specify file with Unicode name. On non-Windows OS, this function assumes that setlocale() has been called. + +#if defined(CRYPTOPP_UNIX_AVAILABLE) || defined(CRYPTOPP_DOXYGEN_PROCESSING) || _MSC_VER >= 1400 + //! \brief Construct a FileStore + //! \param filename the Unicode name of the file to open + //! \details On non-Windows OS, this function assumes that setlocale() has been called. FileStore(const wchar_t *filename) {StoreInitialize(MakeParameters(Name::InputFileNameWide(), filename));} #endif + //! \brief Retrieves the internal stream + //! \returns the internal stream pointer std::istream* GetStream() {return m_stream;} lword MaxRetrievable() const; @@ -51,7 +74,9 @@ private: bool m_waiting; }; -//! file-based implementation of Source interface +//! \class FileSource +//! \brief Implementation of Store interface +//! \details file-based implementation of Store interface class CRYPTOPP_DLL FileSource : public SourceTemplate { public: @@ -59,44 +84,82 @@ public: typedef FileStore::OpenErr OpenErr; typedef FileStore::ReadErr ReadErr; + //! \brief Construct a FileStore FileSource(BufferedTransformation *attachment = NULL) : SourceTemplate(attachment) {} + + //! \brief Construct a FileStore + //! \param in an existing stream + //! \param pumpAll flag indicating if source data should be pumped to its attached transformation + //! \param attachment an optional attached transformation FileSource(std::istream &in, bool pumpAll, BufferedTransformation *attachment = NULL) : SourceTemplate(attachment) {SourceInitialize(pumpAll, MakeParameters(Name::InputStreamPointer(), &in));} + + //! \brief Construct a FileStore + //! \param filename the narrow name of the file to open + //! \param pumpAll flag indicating if source data should be pumped to its attached transformation + //! \param attachment an optional attached transformation + //! \param binary flag indicating if the file is binary FileSource(const char *filename, bool pumpAll, BufferedTransformation *attachment = NULL, bool binary=true) : SourceTemplate(attachment) {SourceInitialize(pumpAll, MakeParameters(Name::InputFileName(), filename)(Name::InputBinaryMode(), binary));} -#if defined(CRYPTOPP_UNIX_AVAILABLE) || _MSC_VER >= 1400 - //! specify file with Unicode name. On non-Windows OS, this function assumes that setlocale() has been called. + +#if defined(CRYPTOPP_UNIX_AVAILABLE) || defined(CRYPTOPP_DOXYGEN_PROCESSING) || _MSC_VER >= 1400 + //! \brief Construct a FileSource + //! \param filename the Unicode name of the file to open + //! \param pumpAll flag indicating if source data should be pumped to its attached transformation + //! \param attachment an optional attached transformation + //! \param binary flag indicating if the file is binary + //! \details On non-Windows OS, this function assumes that setlocale() has been called. FileSource(const wchar_t *filename, bool pumpAll, BufferedTransformation *attachment = NULL, bool binary=true) : SourceTemplate(attachment) {SourceInitialize(pumpAll, MakeParameters(Name::InputFileNameWide(), filename)(Name::InputBinaryMode(), binary));} #endif + //! \brief Retrieves the internal stream + //! \returns the internal stream pointer std::istream* GetStream() {return m_store.GetStream();} }; -//! file-based implementation of Sink interface +//! \class FileSink +//! \brief Implementation of Store interface +//! \details file-based implementation of Sink interface class CRYPTOPP_DLL FileSink : public Sink, public NotCopyable { public: + //! \brief Exception thrown when file-based error is encountered class Err : public Exception { public: Err(const std::string &s) : Exception(IO_ERROR, s) {} }; + //! \brief Exception thrown when file-based open error is encountered class OpenErr : public Err {public: OpenErr(const std::string &filename) : Err("FileSink: error opening file for writing: " + filename) {}}; + //! \brief Exception thrown when file-based write error is encountered class WriteErr : public Err {public: WriteErr() : Err("FileSink: error writing file") {}}; + //! \brief Construct a FileSink FileSink() : m_stream(NULL) {} + + //! \brief Construct a FileSink + //! \param out an existing stream FileSink(std::ostream &out) {IsolatedInitialize(MakeParameters(Name::OutputStreamPointer(), &out));} + + //! \brief Construct a FileSink + //! \param filename the narrow name of the file to open + //! \param binary flag indicating if the file is binary FileSink(const char *filename, bool binary=true) {IsolatedInitialize(MakeParameters(Name::OutputFileName(), filename)(Name::OutputBinaryMode(), binary));} + #if defined(CRYPTOPP_UNIX_AVAILABLE) || _MSC_VER >= 1400 - //! specify file with Unicode name. On non-Windows OS, this function assumes that setlocale() has been called. + //! \brief Construct a FileSink + //! \param filename the Unicode name of the file to open + //! \details On non-Windows OS, this function assumes that setlocale() has been called. FileSink(const wchar_t *filename, bool binary=true) {IsolatedInitialize(MakeParameters(Name::OutputFileNameWide(), filename)(Name::OutputBinaryMode(), binary));} #endif + //! \brief Retrieves the internal stream + //! \returns the internal stream pointer std::ostream* GetStream() {return m_stream;} void IsolatedInitialize(const NameValuePairs ¶meters); diff --git a/filters.h b/filters.h index a97c5a17..5c8657e7 100644 --- a/filters.h +++ b/filters.h @@ -487,7 +487,7 @@ struct BlockPaddingSchemeDef //! \class StreamTransformationFilter //! \brief Filter wrapper for StreamTransformation -//! \details Filter wrapper for StreamTransformation. The filter will optionally handle padding/unpadding when needed +//! \details StreamTransformationFilter is a filter wrapper for StreamTransformation. The filter will optionally handle padding/unpadding when needed class CRYPTOPP_DLL StreamTransformationFilter : public FilterWithBufferedInput, public BlockPaddingSchemeDef, private FilterPutSpaceHelper { public: