diff options
Diffstat (limited to 'src/include')
| -rw-r--r-- | src/include/iodevice.h | 439 |
1 files changed, 214 insertions, 225 deletions
diff --git a/src/include/iodevice.h b/src/include/iodevice.h index 8b1314e..3e3330d 100644 --- a/src/include/iodevice.h +++ b/src/include/iodevice.h @@ -1,8 +1,8 @@ /** - * @file iodevice.h - * @brief Declaration of the IODevice class. - * @author Andreas Aardal Hanssen - * @date 2002, 2003 + * @file iodevice.h + * @brief Declaration of the IODevice class. + * @author Andreas Aardal Hanssen + * @date 2002, 2003 */ #ifndef iodevice_h_included @@ -17,24 +17,22 @@ const char CMS_END_OF_LINE[4] = {0x0d, '\n', 0x00, 0x00}; namespace Binc { - /*! - \class IODevice - \brief The IODevice class provides a framework for reading and - writing to device. - Implement new devices by inheriting this class and overloading all - virtual methods. - - service() returns the service that the specific device is used - for. Two values are "log" and "client". - - \sa IOFactory, MultilogDevice, SyslogDevice, StdIODevice, SSLDevice - */ + /** + * @class IODevice + * @brief The IODevice class provides a framework for reading and writing to device. + * + * Implement new devices by inheriting this class and overloading all + * virtual methods. + * + * service() returns the service that the specific device is used + * for. Two values are "log" and "client". + * + * @sa IOFactory, MultilogDevice, SyslogDevice, StdIODevice, SSLDevice + */ class IODevice { public: - /*! - Standard options for an IODevice. - */ + /// Standard options for an IODevice. enum Flags { None = 0, FlushesOnEndl = 1 << 0, @@ -44,196 +42,190 @@ namespace Binc { HasTimeout = 1 << 4 }; - /*! - Errors from when an operation returned false. - */ + /// Errors from when an operation returned false. enum Error { Unknown, Timeout }; - /*! - Constructs an invalid IODevice. - - Instances of IODevice perform no operations, and all boolean - functions always return false. This constructor is only useful - if called from a subclass that reimplements all virtual methods. - */ + /** + * Constructs an invalid IODevice. + * + * Instances of IODevice perform no operations, and all boolean + * functions always return false. This constructor is only useful + * if called from a subclass that reimplements all virtual methods. + */ IODevice(int f = 0); - /*! - Destructs an IODevice; does nothing. - */ + /// Destructs an IODevice; does nothing. virtual ~IODevice(); - /*! - Clears all data in the input and output buffers. - */ + /// Clears all data in the input and output buffers. void clear(); - /*! - Sets one or more flags. - \param f A bitwise OR of flags from the Flags enum. - */ + /** + * Sets one or more flags. + * @param f A bitwise OR of flags from the Flags enum. + */ void setFlags(unsigned int f); /*! - Clears one or more flags. - \param f A bitwise OR of flags from the Flags enum. - */ + * Clears one or more flags. + * @param f A bitwise OR of flags from the Flags enum. + */ void clearFlags(unsigned int f); - /*! - Sets the maximum allowed input buffer size. If this size is - non-zero and exceeded, reading from the device will fail. This - functionality is used to prevent clients from forcing this class - to consume so much memory that the program crashes. - - Setting the max input buffer size to 0 disables the input size - limit. - - \param max The maximum input buffer size in bytes. - */ + /** + * Sets the maximum allowed input buffer size. If this size is + * non-zero and exceeded, reading from the device will fail. This + * functionality is used to prevent clients from forcing this class + * to consume so much memory that the program crashes. + * + * Setting the max input buffer size to 0 disables the input size + * limit. + * + * @param max The maximum input buffer size in bytes. + */ void setMaxInputBufferSize(unsigned int max); - /*! - Sets the maximum allowed output buffer size. If this size is - non-zero and exceeded, flush() is called implicitly. - - Setting the max output buffer size to 0 disables the output size - limit. This is generally discouraged. - - As a contrast to setMaxInputBufferSize(), this function is used - to bundle up consequent write calls, allowing more efficient use - of the underlying device as larger blocks of data are written at - a time. - - \param max The maximum output buffer size in bytes. - */ + /** + * Sets the maximum allowed output buffer size. If this size is + * non-zero and exceeded, flush() is called implicitly. + * + * Setting the max output buffer size to 0 disables the output size + * limit. This is generally discouraged. + * + * As a contrast to setMaxInputBufferSize(), this function is used + * to bundle up consequent write calls, allowing more efficient use + * of the underlying device as larger blocks of data are written at + * a time. + * + * @param max The maximum output buffer size in bytes. + */ void setMaxOutputBufferSize(unsigned int max); - /*! - Sets the device's internal timeout in seconds. This timeout is - used both when waiting for data to read and for waiting for the - ability to write. - - If this timeout is exceeded, the read or write function that - triggered the timeout will fail. - - Setting the timeout to 0 disables the timeout. - - \param t The timeout in seconds. - \sa getTimeout() - */ + /** + * Sets the device's internal timeout in seconds. This timeout is + * used both when waiting for data to read and for waiting for the + * ability to write. + * + * If this timeout is exceeded, the read or write function that + * triggered the timeout will fail. + * + * Setting the timeout to 0 disables the timeout. + * + * @param t The timeout in seconds. + * @sa getTimeout() + */ void setTimeout(unsigned int t); - /*! - Returns the timeout in seconds, or 0 if there is no timeout. - - \sa setTimeout() - */ + /** + * Returns the timeout in seconds, or 0 if there is no timeout. + * + * @sa setTimeout() + */ unsigned int getTimeout() const; enum LogLevel { ErrorLevel, InfoLevel, WarningLevel, DebugLevel }; - /*! - Sets the output level for the following write operations on this - device. - - The output level is a number which gives the following write - operations a priority. You can use setOutputLevelLimit() to - filter the write operations valid for different operating modes. - This enables you to have certain write operations ignored. - - For instance, if the output level is set to 0, then "Hello" is - written, and the output level is set to 1, followed by writing - "Daisy", the output level limit value will decide whether only - "Hello" is written, or if also "Daisy" is written. - - A low value of the level gives higher priority, and a high level - will give low priority. The default value is 0, and write - operations that are done with output level 0 are never ignored. - - \param level The output level - \sa getOutputLevel(), setOutputLevelLimit() - */ + /** + * Sets the output level for the following write operations on this + * device. + * + * The output level is a number which gives the following write + * operations a priority. You can use setOutputLevelLimit() to + * filter the write operations valid for different operating modes. + * This enables you to have certain write operations ignored. + * + * For instance, if the output level is set to 0, then "Hello" is + * written, and the output level is set to 1, followed by writing + * "Daisy", the output level limit value will decide whether only + * "Hello" is written, or if also "Daisy" is written. + * + * A low value of the level gives higher priority, and a high level + * will give low priority. The default value is 0, and write + * operations that are done with output level 0 are never ignored. + * + * @param level The output level + * @sa getOutputLevel(), setOutputLevelLimit() + */ void setOutputLevel(LogLevel level); - /*! - Returns the current output level. - - \sa setOutputLevel() - */ + /** + * Returns the current output level. + * + * @sa setOutputLevel() + */ LogLevel getOutputLevel() const; - /*! - Sets the current output level limit. Write operations with a - level higher than the output level limit are ignored. - - \param level The output level limit - \sa setOutputLevel() - */ + /** + * Sets the current output level limit. Write operations with a + * level higher than the output level limit are ignored. + * + * @param level The output level limit + * @sa setOutputLevel() + */ void setOutputLevelLimit(LogLevel level); - /*! - Returns the current output level limit. - - \sa setOutputLevelLimit() - */ + /** + * Returns the current output level limit. + * + * @sa setOutputLevelLimit() + */ LogLevel getOutputLevelLimit() const; - /*! - Returns the number of bytes that have been read from this device - since it was created. - */ + /** + * Returns the number of bytes that have been read from this device + * since it was created. + */ unsigned int getReadCount() const; - /*! - Returns the number of bytes that have been written to this - device since it was created. - */ + /** + * Returns the number of bytes that have been written to this + * device since it was created. + */ unsigned int getWriteCount() const; - /*! - Calling this function enables the built-in protocol dumping feature in - the device. All input and output to this device will be dumped to a file - in /tmp. - */ + /** + * Calling this function enables the built-in protocol dumping feature in + * the device. All input and output to this device will be dumped to a file + * in /tmp. + */ void enableProtocolDumping(); - /*! - Writes data to the device. Depending on the value of the max - output buffer size, the data may not be written immediately. - - \sa setMaxOutputBufferSize() - */ + /** + * Writes data to the device. Depending on the value of the max + * output buffer size, the data may not be written immediately. + * + * @sa setMaxOutputBufferSize() + */ template<class T> IODevice &operator<<(const T &source); - /*! - Writes data to the device. This function specializes on standard - ostream derivates, such as std::endl. + /** + * Writes data to the device. This function specializes on standard + * ostream derivatives, such as std::endl. */ IODevice &operator<<(std::ostream &(*source)(std::ostream &)); - /*! - Returns true if data can be read from the device; otherwise - returns false. - */ + /** + * Returns true if data can be read from the device; otherwise + * returns false. + */ virtual bool canRead() const; - /*! - Reads data from the device, and stores this in a string. Returns - true on success; otherwise returns false. - - \param dest The incoming data is stored in this string. - \param max No more than this number of bytes is read from the - device. - */ + /** + * Reads data from the device, and stores this in a string. Returns + * true on success; otherwise returns false. + * + * @param dest The incoming data is stored in this string. + * @param max No more than this number of bytes is read from the + * device. + */ bool readStr(std::string *dest, unsigned int max = 0); - /*! - Reads exactly one byte from the device and stores this in a - char. Returns true on success; otherwise returns false. - - \param dest The incoming byte is stored in this char. - */ + /** + * Reads exactly one byte from the device and stores this in a + * char. Returns true on success; otherwise returns false. + * + * @param dest The incoming byte is stored in this char. + */ bool readChar(char *dest = nullptr); /*! @@ -246,98 +238,95 @@ namespace Binc { */ void unreadStr(const std::string &s); - /*! - Reads characters from the device, until and including one - certain character is found. All read characters are discarded. - - This function can be used to skip to the beginning of a line, - with the terminating character being '\n'. - - \param The certain character. - */ + /** + * Reads characters from the device, until and including one + * certain character is found. All read characters are discarded. + * + * This function can be used to skip to the beginning of a line, + * with the terminating character being '\n'. + * + * @param The certain character. + */ bool skipTo(char c); - /*! - Flushes the output buffer. Writes all data in the output buffer - to the device. - */ + /** + * Flushes the output buffer. Writes all data in the output buffer + * to the device. + */ bool flush(); - /*! - Returns the type of error that most recently occurred. - */ + /** + * Returns the type of error that most recently occurred. + */ Error getLastError() const; - /*! - Returns a human readable description of the error that most - recently occurred. If no known error has occurred, this method - returns "Unknown error". - */ + /** + * Returns a human readable description of the error that most + * recently occurred. If no known error has occurred, this method + * returns "Unknown error". + */ std::string getLastErrorString() const; - /*! - Returns the type of service provided by this device. Two valid - return values are "client" and "log". - */ + /** + * Returns the type of service provided by this device. Two valid + * return values are "client" and "log". + */ virtual std::string service() const; protected: - /*! - Waits until data can be written to the device. If the timeout is - 0, this function waits indefinitely. Otherwise, it waits until - the timeout has expired. - - If this function returns true, data can be written to the - device; otherwise, getLastError() must be checked to determine - whether a timeout occurred or whether an error with the device - prevents further writing. - */ + /** + * Waits until data can be written to the device. If the timeout is + * 0, this function waits indefinitely. Otherwise, it waits until + * the timeout has expired. + * + * If this function returns true, data can be written to the + * device; otherwise, getLastError() must be checked to determine + * whether a timeout occurred or whether an error with the device + * prevents further writing. + */ virtual bool waitForWrite() const; - /*! - Waits until data can be read from the device. - - \sa waitForWrite() - */ + /** + * Waits until data can be read from the device. + * + * \sa waitForWrite() + */ virtual bool waitForRead() const; - /*! - Types of results from a write. - */ + /// Types of results from a write. enum WriteResult { WriteWait = 0, WriteDone = 1 << 0, WriteError = 1 << 1 }; - /*! - Writes as much data as possible to the device. If some but not - all data was written, returns WriteWait. If all data was - written, returns WriteDone. If an error occurred, returns - WriteError. - */ + /** + * Writes as much data as possible to the device. If some but not + * all data was written, returns WriteWait. If all data was + * written, returns WriteDone. If an error occurred, returns + * WriteError. + */ virtual WriteResult write(); - /*! - Reads data from the device, and stores it in the input buffer. - Returns true on success; otherwise returns false. - - This method will fail if there is no more data available, if a - timeout occurred or if an error with the device prevents more - data from being read. - - The number of bytes read from the device is undefined. - */ + /** + * Reads data from the device, and stores it in the input buffer. + * Returns true on success; otherwise returns false. + * + * This method will fail if there is no more data available, if a + * timeout occurred or if an error with the device prevents more + * data from being read. + * + * The number of bytes read from the device is undefined. + */ virtual bool fillInputBuffer(); BincStream inputBuffer; BincStream outputBuffer; - protected: unsigned int flags; unsigned int maxInputBufferSize; unsigned int maxOutputBufferSize; unsigned int timeout; - unsigned int readCount; - unsigned int writeCount; + size_t readCount; + size_t writeCount; LogLevel outputLevel; LogLevel outputLevelLimit; |