From 194169e5e63b29a24187d758d4891b1de878ec8f Mon Sep 17 00:00:00 2001 From: William Woodall Date: Wed, 2 May 2012 21:49:09 -0500 Subject: [PATCH] More updates to the documentation and new api after comments from john and michael. --- include/serial/impl/unix.h | 6 ++-- include/serial/serial.h | 70 ++++++++++++++++++++++++-------------- src/impl/unix.cc | 4 +-- src/serial.cc | 7 ++-- 4 files changed, 54 insertions(+), 33 deletions(-) diff --git a/include/serial/impl/unix.h b/include/serial/impl/unix.h index 2e134df..ff8b4d1 100644 --- a/include/serial/impl/unix.h +++ b/include/serial/impl/unix.h @@ -122,9 +122,9 @@ public: getPort () const; void - setTimeout (timeout_t &timeout); + setTimeout (Timeout &timeout); - timeout_t + Timeout getTimeout () const; void @@ -180,7 +180,7 @@ private: bool xonxoff_; bool rtscts_; - timeout_t timeout_; // Timeout for read operations + Timeout timeout_; // Timeout for read operations unsigned long baudrate_; // Baudrate parity_t parity_; // Parity diff --git a/include/serial/serial.h b/include/serial/serial.h index ad29bab..3f2c60c 100644 --- a/include/serial/serial.h +++ b/include/serial/serial.h @@ -38,7 +38,7 @@ #include #include -#include +#include #include #include #include @@ -88,8 +88,8 @@ typedef enum { * Structure for setting the timeout of the serial port, times are * in milliseconds. */ -struct timeout_t { - timeout_t (long inter_byte_timeout_=0, long read_timeout_constant_=0, +struct Timeout { + Timeout (long inter_byte_timeout_=0, long read_timeout_constant_=0, long read_timeout_multiplier_=0, long write_timeout_constant_=0, long write_timeout_multiplier_=0) : inter_byte_timeout(inter_byte_timeout_), @@ -129,6 +129,9 @@ public: * * \param baudrate An integer that represents the baudrate * + * \param timeout A serial::Timeout struct that defines the timeout + * conditions for the serial port. \see serial::Timeout + * * \param bytesize Size of each byte in the serial transmission of data, * default is eightbits, possible values are: fivebits, sixbits, sevenbits, * eightbits @@ -147,6 +150,7 @@ public: */ Serial (const std::string &port = "", unsigned long baudrate = 9600, + Timeout timeout = Timeout(), bytesize_t bytesize = eightbits, parity_t parity = parity_none, stopbits_t stopbits = stopbits_one, @@ -341,29 +345,42 @@ public: std::string getPort () const; - /*! Sets the timeout for reads and writes using the timeout_t struct. + /*! Sets the timeout for reads and writes using the Timeout struct. * - * There are two basic conditions for timeout described here, the inter byte - * timeout is the maximum amount of time in milliseconds allowed between - * receiving bytes from the serial port. The second condition is where the - * total timeout expires during a read or write. The total timeout can be - * calculated as the multiplier times the number of requested bytes plus the - * constant. In this way a single constant time timeout can be specified - * with zero for the inter byte timeout and zero for the multiplier. - * Alternatively, you could have only an inter byte timeout and zero for - * both the constant and multiplier to prevent a total time timeout from - * occurring.You can use the multiplier to increase the total time timeout - * based on the number of bytes requested. The user can combine any of - * these timeout metrics in order to achieve the desired trade-off between - * efficiency and responsiveness. + * There are two timeout conditions described here: + * * The inter byte timeout: + * * The inter_byte_timeout component of serial::Timeout defines the + * maximum amount of time, in milliseconds, between receiving bytes on + * the serial port that can pass before a timeout occurs. Setting this + * to zero will prevent inter byte timeouts from occurring. + * * Total time timeout: + * * The the constant and multiplier component of this timeout condition, + * for both read and write, are defined in serial::Timeout. This + * timeout occurs if the total time since the read or write call was + * made exceeds the specified time in milliseconds. + * * The limit is defined by multiplying the multiplier component by the + * number of requested bytes and adding that product to the constant + * component. In this way if you want a read call, for example, to + * timeout after exactly one second regardless of the number of bytes + * you asked for then set the read_timeout_constant component of + * serial::Timeout to 1000 and the read_timeout_multiplier to zero. + * This timeout condition can be used in conjunction with the inter + * byte timeout condition with out any problems, timeout will simply + * occur when one of the two timeout conditions is met. This allows + * users to have maximum control over the trade-off between + * responsiveness and efficiency. * - * \param timeout A timeout_t struct containing the inter byte timeout, and - * the read and write timeout constants and multipliers. + * Read and write functions will return in one of three cases. When the + * reading or writing is complete, when a timeout occurs, or when an + * exception occurs. * - * \see serial::timeout_t + * \param timeout A serial::Timeout struct containing the inter byte + * timeout, and the read and write timeout constants and multipliers. + * + * \see serial::Timeout */ void - setTimeout (timeout_t &timeout); + setTimeout (Timeout &timeout); /*! Sets the timeout for reads and writes. */ void @@ -371,7 +388,7 @@ public: long read_timeout_multiplier, long write_timeout_constant, long write_timeout_multiplier) { - timeout_t timeout(inter_byte_timeout, read_timeout_constant, + Timeout timeout(inter_byte_timeout, read_timeout_constant, read_timeout_multiplier, write_timeout_constant, write_timeout_multiplier); return setTimeout(timeout); @@ -379,12 +396,12 @@ public: /*! Gets the timeout for reads in seconds. * - * \return A timeout_t struct containing the inter_byte_timeout, and read + * \return A Timeout struct containing the inter_byte_timeout, and read * and write timeout constants and multipliers. * * \see Serial::setTimeout */ - timeout_t + Timeout getTimeout () const; /*! Sets the baudrate for the serial port. @@ -520,7 +537,7 @@ public: setDTR (bool level = true); /*! - * Returns true on CTS, DSR, RI, or CD changing. + * Blocks until CTS, DSR, RI, CD changes or something interrupts it. * * Can throw an exception if an error occurs while waiting. * You can check the status of CTS, DSR, RI, and CD once this returns. @@ -528,6 +545,9 @@ public: * resolution of less than +-1ms and as good as +-0.2ms. Otherwise a * polling method is used which can give +-2ms. * + * \return Returns true if one of the lines changed, false if something else + * occurred. + * * \throw SerialException */ bool diff --git a/src/impl/unix.cc b/src/impl/unix.cc index e8d0f4c..d34d7aa 100644 --- a/src/impl/unix.cc +++ b/src/impl/unix.cc @@ -491,12 +491,12 @@ Serial::SerialImpl::getPort () const } void -Serial::SerialImpl::setTimeout (serial::timeout_t &timeout) +Serial::SerialImpl::setTimeout (serial::Timeout &timeout) { timeout_ = timeout; } -serial::timeout_t +serial::Timeout Serial::SerialImpl::getTimeout () const { return timeout_; diff --git a/src/serial.cc b/src/serial.cc index c2e1eaa..d391202 100644 --- a/src/serial.cc +++ b/src/serial.cc @@ -48,13 +48,14 @@ private: SerialImpl *pimpl_; }; -Serial::Serial (const string &port, unsigned long baudrate, +Serial::Serial (const string &port, unsigned long baudrate, Timeout timeout, bytesize_t bytesize, parity_t parity, stopbits_t stopbits, flowcontrol_t flowcontrol) : read_cache_("") { pimpl_ = new SerialImpl (port, baudrate, bytesize, parity, stopbits, flowcontrol); + pimpl_->setTimeout(timeout); } Serial::~Serial () @@ -230,12 +231,12 @@ Serial::getPort () const } void -Serial::setTimeout (serial::timeout_t &timeout) +Serial::setTimeout (serial::Timeout &timeout) { pimpl_->setTimeout (timeout); } -serial::timeout_t +serial::Timeout Serial::getTimeout () const { return pimpl_->getTimeout (); }