SerialPortClass.h

Go to the documentation of this file.

/**
\file    SerialPortClass.h 
\brief   A class for handling serial port communications. \n
         The intention is for this class to handle WIN32 serial port
         communications and eventually also linux serial port 
         communications. A preprocessor directive will be used
         to distinguish the build.

\author  Glenn D. MacGougan (GDM)
\date    2008-11-26
\since   2008-11-26

\b "LICENSE INFORMATION" \n
Copyright (c) 2008, refer to 'author' doxygen tags \n
All rights reserved. \n

Redistribution and use in source and binary forms, with or without
modification, are permitted provided the following conditions are met: \n

- Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer. \n
- Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution. \n
- The name(s) of the contributor(s) may not be used to endorse or promote 
  products derived from this software without specific prior written 
  permission. \n

THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND ANY EXPRESS 
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 
SUCH DAMAGE.
*/

#ifndef _SERIALPORT_H_
#define _SERIALPORT_H_

#include "serialport.h" // 'C' functions for serial communications


class SerialPort
{
public: // Lifecycle

  /// \brief    SerialPort destructor
  virtual ~SerialPort(); 

  /// \brief    The default constructor.
  SerialPort();

  /// \brief    The disabled copy constructor.
  SerialPort( SerialPort& rhs ) {} ;

public: // Assignment

  /// \brief    operator= overload (GDM_TODO should be disabled)
  const SerialPort& operator=( const SerialPort& src ) { return *this; }

public: // Usage

  /**
  \brief  Open the serial port with the settings specified

  \return true if succesful, false otherwise.
  */
  bool Open(
    const unsigned short              portnumber,    //!< The COM port number [1-N].
    const SERIALPORT_enumBaudRate     baudrate,      //!< The port baud rate [bps].
    const SERIALPORT_enumParity       parity = SERIALPORT_PARITY_NONE,  //!< The port parity setting.
    const SERIALPORT_enumDataBits     databits = SERIALPORT_DATABITS_8, //!< The port data bits setting.
    const SERIALPORT_enumStopBits     stopbits = SERIALPORT_STOPBITS_1, //!< The port stop bits setting.
    const SERIALPORT_enumFlowControl  flowcontrol = SERIALPORT_FLOWCONTROL_NONE, //!< The port flow control setting.
    const SERIALPORT_enumBehaviour    behaviour = SERIALPORT_BEHAVIOUR_RETURN_IMMEDIATELY, //!< The port's read behaviour (settings for waiting on the read timeout).
    const unsigned                    timeout_in_ms = 0 //!< The read function's timeout [ms]. Not used if behaviour == SERIALPORT_BEHAVIOUR_RETURN_IMMEDIATELY.
    );

  /**
  \brief  Read data from the serial port.

  \pre  Open must have been called.

  \return true if succesful, false otherwise.
  */
  bool Read( 
    unsigned char* buffer,     //!< A valid buffer (!NULL) in which to place data. 
    const unsigned bufferSize, //!< The size of the buffer [bytes].
    unsigned& nrBytesRead      //!< The number of bytes read [bytes].
    );

  /**
  \brief  Write data to the serial port.

  \pre  Open must have been called.

  \return true if succesful, false otherwise.
  */
  bool Write( 
    unsigned char* buffer,        //!< A valid buffer (!NULL) with data to be written to the port. 
    const unsigned nrBytesToWrite //!< The number of bytes in the buffer to write [bytes].    
    );

  
  /**
  \brief  Wait for the Ring Indicator pin to signal an event.

  \pre  Open must have been called.

  \return true if succesful, false otherwise.
  */
  bool WaitOnRingIndicator( unsigned short timeout_ms, bool& ring_detected );


  /**
  \brief  Close the serial port.

  \pre  Open must have been called.

  \return true if succesful, false otherwise.
  */
  bool Close();

  /// Get the current serial port number used.
  unsigned short GetPortNumber() { return m_serialport.port; }

protected: // Member Variables

  /// \brief  The serial port 'c' container.
  SERIALPORT_structObject m_serialport;

};


#endif // _SERIALPORT_H_