serial/serialport.h

   1 /***************************************************************************//**
   2  * Project Name : quicksms
   3  *
   4  * \file serialport.h this file contains ISerialPort class declaration.
   5  * \package quicksms
   6  ******************************************************************************/
   7 #ifndef SERIALPORT_H
   8 #define SERIALPORT_H
   9
  10 #include "../pch.h"
  11 #include "serialdefs.h"
  12
  13 /*****************************************************************************//**
  14  * \namespace serial
  15  * \brief this namespace groups objects for manipulating data over serial ports.
  16  ********************************************************************************/
  17
  18 namespace serial{
  19
  20
  21   /***************************************************************************//**
  22   * \class CSerialPort
  23   * \brief this class represents a serial port in objective manner.
  24   *
  25   * This class helps with manipulating data over serial ports
  26   * It allows to select baudrate, parity and flow control
  27   *
  28   *******************************************************************************/
  29
  30   class ISerialPort
  31   {
  32     public:
  33       /*********************************************************************//**
  34         * \brief this CSerialPort constructor opens a port with name passed as
  35         *  parameter.
  36         *
  37         * \param[in] name name of file descriptor representing port to open.
  38         ***********************************************************************/
  39       ISerialPort(QString &name);
  40
  41
  42       /*********************************************************************//**
  43        * \brief constructor which allows to more precisely set port
  44        * parameters.
  45        *
  46        * \param[in] pName port name
  47        * \param[in] pBaudrate port baud rate
  48        * \param[in] pFlow useful when needed specific flow control
  49        * \param[in] pParity port parity control
  50        *
  51        * This constructor allows for more spohisticated port opening.
  52        * It is possible to select correct port speed, parity and
  53        * flow control instead of just choosing device name.
  54        *
  55        ***********************************************************************/
  56       ISerialPort(const QString &pName,const serial::Baudrate &pBaudrate,const serial::Parity &pParity,
  57                   const serial::FlowControl &pFlow,const bool pOpen,const ReadCallback pReadCallback);
  58
  59
  60       ~ISerialPort();
  61
  62
  63
  64       /********************************************************************//**
  65        * \brief this function opens a port
  66        * \param[in] pName port filename
  67        * \return returns port state
  68        * \retval
  69        *
  70        *  If already open return value is Status::FILE_ALREADY_OPEN
  71        * and if invalid file path is passed return value is
  72        * Status::FILE_NOT_FOUND
  73        *
  74        ************************************************************************/
  75       virtual bool open(const QString &pName) = 0;
  76
  77
  78       /********************************************************************//**
  79        * \brief this function opens a port
  80        * \return returns port state
  81        * \retval
  82        *
  83        *  If already open return value is Status::FILE_ALREADY_OPEN
  84        * and if invalid file path is passed return value is
  85        * Status::FILE_NOT_FOUND
  86        *
  87        ************************************************************************/
  88       virtual bool open() = 0;
  89
  90
  91       /*********************************************************************//**
  92        * \brief reopens an already open port.
  93        *
  94        * It is a convienience function, which allows to reopen port e.g
  95        * when an I/O error occured. It will use last settings (port name parity
  96        * speed and flow control).
  97        ************************************************************************/
  98        bool reopen();
  99
 100
 101       /*********************************************************************//**
 102        * \brief closes a port.
 103        * \param[in] pForce set to true if you want to terminate pending tasks.
 104        *
 105        * closes a port. If you forget to close, it will be done in destructor.
 106        ************************************************************************/
 107       virtual bool close( bool pForce = 0) =0;
 108
 109
 110       /*********************************************************************//**
 111        * \brief opens or closes port, depending on pState value.
 112        * \param[in] pState set true to open, close to close :-)
 113        *
 114        *
 115        ************************************************************************/
 116       virtual bool setOpened(const bool &pState) =0;
 117
 118       /*********************************************************************//**
 119        * \brief opens or closes port, depending on pState value.
 120        * \param[in] pState set true to open, close to close :-)
 121        *
 122        *
 123        ************************************************************************/
 124       virtual bool isOpened(const bool &pState);
 125
 126
 127       /*********************************************************************//**
 128        * \brief sets port blocking mode.
 129        * \param[in] pState
 130        *
 131        * if port is in blocking mode, then the readBuffer() call will block
 132        * thread until there is data to be read.
 133        ************************************************************************/
 134       virtual bool setBlocking(const bool &pState) =0;
 135
 136
 137       /*********************************************************************//**
 138        * \brief sets port blocking mode.
 139        * \param[in] pState
 140        *
 141        * if port is in blocking mode, then the readBuffer() call will block
 142        * thread until there is data to be read.
 143        ************************************************************************/
 144       virtual bool isBlocking(const bool &pState);
 145
 146
 147       /*********************************************************************//**
 148        * \brief set port baud rate.
 149        * \param[in] pBaudrate port baudrate
 150        * \todo value checks!
 151        *
 152        ************************************************************************/
 153       virtual bool setBaudrate(const serial::Baudrate &pBaudrate) =0;
 154
 155
 156       /*********************************************************************//**
 157        * \brief get port baud rate.
 158        * \param[out] pBaudrate port baudrate
 159        * \todo value checks!
 160        *
 161        ************************************************************************/
 162       bool getBaudrate(serial::Baudrate &pBaudrate);
 163
 164
 165       /*********************************************************************//**
 166        * \brief sets flow control
 167        * \param[in] pFlow new flow control
 168        *
 169        *
 170        ************************************************************************/
 171       virtual bool setFlowControl(const serial::FlowControl &pFlow) =0;
 172
 173
 174       /*********************************************************************//**
 175        * \brief sets flow control
 176        * \param[in] pFlow new flow control
 177        *
 178        *
 179        ************************************************************************/
 180       bool getFlowControl(const serial::FlowControl &pFlow);
 181
 182
 183        /*********************************************************************//**
 184        * \brief sets port parity checking mode.
 185        * \param[in] pParity port parity.
 186        *
 187        *
 188        ************************************************************************/
 189       virtual bool setParity(const serial::Parity &pParity) =0;
 190
 191        /*********************************************************************//**
 192        * \brief sets port parity checking mode.
 193        * \param[in] pParity port parity.
 194        *
 195        *
 196        ************************************************************************/
 197       bool getParity(const serial::Parity &pParity);
 198
 199
 200       /*********************************************************************//**
 201        * \brief sets port filename.
 202        * \param[in] pName port name /path
 203        *
 204        * if path is non-empty and existant, then this method setsmName = pName.
 205        ************************************************************************/
 206        virtual bool setFilename(const QString &pName) =0;
 207
 208
 209       /*********************************************************************//**
 210        * \brief sets port filename.
 211        * \param[in] pName port name /path
 212        *
 213        * if path is non-empty and existant, then mName = pName.
 214        ************************************************************************/
 215        bool getFilename(const QString &pName);
 216
 217
 218       /*********************************************************************//**
 219        * \brief sets port filename.
 220        * \param[out] pStatus target Status field.
 221        *
 222        *  Use it to retrieve information about port operating status.
 223        ************************************************************************/
 224        bool getStatus(serial::Status &status);
 225
 226
 227       /*********************************************************************//**
 228        * \brief sets read callback function.
 229        * \param[in] pCallback pointer to callback function
 230        *
 231        * Usable when you want to execute function as soon as data arrives.
 232        * If pointer is valid, it sets mReadCallback to pCallback
 233        ************************************************************************/
 234        bool setReadCallback( const serial::ReadCallback &pCallback);
 235
 236
 237       /*********************************************************************//**
 238        * \brief writes data from buffer to port.
 239        * \param[in] pBuffer location in memory where source data resides.
 240        * \param[in] pSize number of bytes to be written.
 241        *
 242        * writeBuffer writes equal pSize bytes from pBuffer to port.
 243        ************************************************************************/
 244       virtual int writeBuffer(void *pBuffer, unsigned int pSize) =0;
 245
 246
 247       /*********************************************************************//**
 248        * \brief reads data from port to buffer
 249        * \param[out] pBuffer location in memory where source data resides.
 250        * \param[in] pSize number of bytes to be read.
 251        * \param[in] pTimeout read timeout.
 252        * \return number of bytes that actually have been retrieved.
 253        *
 254        * readBuffer reads MAXIMUM pSize bytes from port and writes it into
 255        * buffer pointed by pBuffer. If timeout > 0 the function will wait
 256        * if there aren't any bytes to be read.
 257        ************************************************************************/
 258       virtual int readBuffer(void *pBuffer, unsigned int pSize = 0, unsigned int pTimeout = 0) =0;
 259
 260
 261
 262       /*********************************************************************//**
 263        * \brief writes string to port.
 264        * \param[in] pStr source string.
 265        *
 266        *  This is a convenience function handling string to byte-array conversion
 267        ************************************************************************/
 268       virtual int sendString(const QString &pStr) =0;
 269
 270
 271       /*********************************************************************//**
 272        * \brief writes QByteArray to port.
 273        * \param[in] pArr source array.
 274        *
 275        *  This is a convenience function handling Qt byte arrays.
 276        ************************************************************************/
 277       virtual int sendByteArray(const QByteArray &pArr) =0;
 278
 279
 280       /*********************************************************************//**
 281        * \brief reads string from port.
 282        * \param[in] pStr source string.
 283        * \param[in] pSize (optional) max bytes to be read.
 284        *
 285        *  This is a convenience function handling string to byte-array conversion
 286        ************************************************************************/
 287       virtual int recieveString(QString &pStr, const unsigned int &pSize = 0) =0;
 288
 289       const inline bool isOpened();
 290
 291     private:
 292
 293
 294       int mBaudrate; ///< current baudrate setting
 295
 296       bool mOpened; ///< is port opened?
 297       bool mIoError; ///< when I/O error occurs this is set to true.
 298       bool mBlocking; ///< if port is in blocking mode this is set to true.
 299       bool mIsOpened; ///< indicates whether port is in open state.
 300       bool mBusy; ///< informs whether are there any operations in progress
 301
 302       QString mName; ///< port name is saved here
 303
 304       serial::Parity mParity; ///< current parity setting
 305       serial::FlowControl mFlow;///< actual flowcontrol setting
 306       serial::Status mStatus; ///< port status
 307       serial::ReadCallback mReadCallback; ///< pointer to function which will be executed
 308       ///< everytime when there is data in buffer.
 309       int mSignalHandler(int signal);
 310   }; // ISerialPort
 311 }; //serial
 312
 313 #endif //SERIALPORT_H