serialport.h

Go to the documentation of this file.

/**
\file    serialport.h
\brief   serial port communications 'c' function library.
\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 _C_SERIALPORT_H_
#define _C_SERIALPORT_H_

#ifdef __cplusplus
extern "C" {
#endif

#include "basictypes.h"

#define SERIALPORT_ERROR_MSG( msg )  { const char *themsg = msg; if( themsg != NULL ){ printf( "\n%s,\n%s, %d,\n%s\n", __FILE__, __FUNCTION__, __LINE__, themsg ); }else{ printf( "\n%s,\n%s, %d,\nUnknown Error\n", __FILE__, __FUNCTION__, __LINE__ ); } }

#ifdef WIN32
#include <windows.h>
#endif


/// \brief  baud rate enumeration
typedef enum 
{
  SERIALPORT_BAUD_110    = 110,
  SERIALPORT_BAUD_300    = 300,
  SERIALPORT_BAUD_600    = 600,
  SERIALPORT_BAUD_1200   = 1200,
  SERIALPORT_BAUD_2400   = 2400,
  SERIALPORT_BAUD_4800   = 4800,
  SERIALPORT_BAUD_9600   = 9600,
  SERIALPORT_BAUD_19200  = 19200,
  SERIALPORT_BAUD_38400  = 38400,
  SERIALPORT_BAUD_57600  = 57600,
  SERIALPORT_BAUD_115200 = 115200,
  SERIALPORT_BAUD_INVALID
} SERIALPORT_enumBaudRate;

/// \brief serial port parity enumeration.
/// refer  http://msdn.microsoft.com/en-us/library/aa363214(VS.85).aspx
typedef enum 
{
  SERIALPORT_PARITY_NONE  = 0,
  SERIALPORT_PARITY_ODD   = 1,
  SERIALPORT_PARITY_EVEN  = 2,
  SERIALPORT_PARITY_MARK  = 3,
  SERIALPORT_PARITY_SPACE = 4,
  SERIALPORT_PARITY_INVALID
} SERIALPORT_enumParity;


/// \brief serial port data bits enumeration.
typedef enum 
{
  SERIALPORT_DATABITS_4 = 4,
  SERIALPORT_DATABITS_5 = 5,
  SERIALPORT_DATABITS_6 = 6,
  SERIALPORT_DATABITS_7 = 7,
  SERIALPORT_DATABITS_8 = 8,
  SERIALPORT_DATABITS_INVALID  
} SERIALPORT_enumDataBits;

      
/// \brief serial port stop bits enumeration
/// refer  http://msdn.microsoft.com/en-us/library/aa363214(VS.85).aspx
typedef enum 
{
  SERIALPORT_STOPBITS_1       = 0,
  SERIALPORT_STOPBITS_1POINT5 = 1,
  SERIALPORT_STOPBITS_2       = 2,
  SERIALPORT_STOPBITS_INVALID
} SERIALPORT_enumStopBits;


/// \brief serial port handshake enumeration
typedef enum 
{
  SERIALPORT_FLOWCONTROL_NONE = 0,
  SERIALPORT_FLOWCONTROL_HARDWARE = 1,
  SERIALPORT_FLOWCONTROL_XONXOFF = 2,
  SERIALPORT_FLOWCONTROL_INVALID
} SERIALPORT_enumFlowControl;


/*
// WIN32 serial port control settings struct
// http://msdn.microsoft.com/en-us/library/aa363214(VS.85).aspx
typedef struct _DCB {
  DWORD DCBlength;
  DWORD BaudRate;
  DWORD fBinary  :1;
  DWORD fParity  :1;
  DWORD fOutxCtsFlow  :1;
  DWORD fOutxDsrFlow  :1;
  DWORD fDtrControl  :2;
  DWORD fDsrSensitivity  :1;
  DWORD fTXContinueOnXoff  :1;
  DWORD fOutX  :1;
  DWORD fInX  :1;
  DWORD fErrorChar  :1;
  DWORD fNull  :1;
  DWORD fRtsControl  :2;
  DWORD fAbortOnError  :1;
  DWORD fDummy2  :17;
  WORD wReserved;
  WORD XonLim;
  WORD XoffLim;
  BYTE ByteSize;
  BYTE Parity;
  BYTE StopBits;
  char XonChar;
  char XoffChar;
  char ErrorChar;
  char EofChar;
  char EvtChar;
  WORD wReserved1;
} DCB;
*/


/// \brief  The serial port behaviour during read operations.
typedef enum 
{
  SERIALPORT_BEHAVIOUR_WAIT_UNTIL_BYTES_DETECTED = 0, //!< Wait until the timeout has elapsed or until bytes are present.
  SERIALPORT_BEHAVIOUR_RETURN_IMMEDIATELY = 1,        //!< Do not wait until the timeout has elapsed. Return immediately.
  SERIALPORT_BEHAVIOUR_INVALID
} SERIALPORT_enumBehaviour;

/**
\brief The serial port data container. i.e. The serial port 'object'.

An example method for the use of this object follows:

\code
BOOL TestSerialPort()
{
  BOOL result;
  unsigned i;
  unsigned numBytesRead = 0;
  unsigned char buffer[8192]
  SERIALPORT_structObject port;
  result = SERIALPORT_Initialize( &port );

  port.port = 1; // COM1
  port.baudrate = SERIALPORT_BAUD_9600;
  port.parity = SERIALPORT_PARITY_NONE;
  port.databits = SERIALPORT_DATABITS_8;
  port.stopbits = SERIALPORT_STOPBITS_1;
  port.flowcontrol = SERIALPORT_FLOWCONTROL_NONE;
  port.timeout = 0;
  port.behaviour = SERIALPORT_BEHAVIOUR_RETURN_IMMEDIATELY;

  result = SERIALPORT_Open( &port );
  if( !result )
    return FALSE;

  for( i = 0; i < 100; i++ )
  {
    result = SERIALPORT_Read( &port, buffer, 8192, numBytesRead );
    if( !result )
      return FALSE; 
    if( numBytesRead > 0 )
      printf( "%s\n", buffer );
    Sleep(1);
  }

  sprintf( buffer, "Hello SERIALPORT\n" );

  for( i = 0; i < 100; i++ )
  {
    result = SERIALPORT_Write( &port, buffer, strlen( buffer ) );
    if( !result )
      return FALSE; 
    Sleep(1);
  }

  result = SERIALPORT_Close( &port );

  return TRUE;
}
\endcode
*/
typedef struct
{
  SERIALPORT_enumBaudRate  baudrate;       //!< The serial port baud rate [bits per second].
  SERIALPORT_enumParity    parity;         //!< The serial port parity.
  SERIALPORT_enumDataBits  databits;       //!< The serial port data bits.
  SERIALPORT_enumStopBits  stopbits;       //!< The serial port stop bits.
  SERIALPORT_enumFlowControl  flowcontrol; //!< The serial port flow control setting.

  BOOL isPortOpen;      //!< A boolean to indicate if the serial port is open.

  unsigned short port;  //!< The serial port number. A value greater than 0.
  unsigned int timeout; //!< The serial port timeout value [ms]. Not used if behaviour == SERIALPORT_BEHAVIOUR_RETURN_IMMEDIATELY.

  HANDLE handle; //!< A windows handle for the serial port.

  SERIALPORT_enumBehaviour behaviour;  //!< The serial port behaviour during read operationss.

  // Do not alter the members of the control settings. This is done internally only.
  DCB control_setting; //!< The control settings for a windows serial communications device. Do not alter the members of the control settings. This is done internally only.

} SERIALPORT_structObject;


/**
\brief  Initialize a serial port 'object'. This does not open the serial port. 
        Call this function after the declaration of the struct.
\return TRUE if successful, FALSE otherwise.
*/
BOOL SERIALPORT_Initialize( SERIALPORT_structObject* serialport );

/**
\brief

\return TRUE if successful, FALSE otherwise.
*/
BOOL SERIALPORT_Open( SERIALPORT_structObject* serialport );

/**
\brief

\return TRUE if successful, FALSE otherwise.
*/
BOOL SERIALPORT_Close( SERIALPORT_structObject* serialport );

/**
\brief

\return TRUE if successful, FALSE otherwise.
*/
/* BOOL SERIALPORT_IsDataAvailableToRead( SERIALPORT_structObject* serialport, BOOL* isAvailable ); // disabled for now */

/**
\brief

\return TRUE if successful, FALSE otherwise.
*/
BOOL SERIALPORT_Read( 
  SERIALPORT_structObject* serialport,       //!< The serial port 'object'.
  unsigned char* buffer,                     //!< A valid buffer in which to place data.
  const unsigned int bytesAvailableInBuffer, //!< The maximum number of bytes avaiable in the buffer [bytes].
  unsigned int* bytesRead                    //!< The number of bytes read and stored in the buffer [bytes].
  );

/**
\brief

\return TRUE if successful, FALSE otherwise.
*/
BOOL SERIALPORT_Write( 
  SERIALPORT_structObject* serialport,     //!< The serial port 'object'.
  const unsigned char* buffer,             //!< A valid buffer containing the data to write.
  const unsigned int numberOfBytesToWrite  //!< The number of bytes to write [bytes].
  );

/**
\brief

\return TRUE if successful, FALSE otherwise.
*/
BOOL SERIALPORT_WaitOnRingIndicatorEvent(
  SERIALPORT_structObject* serialport,     //!< The serial port 'object'.
  unsigned short timeout_ms,               //!< Wait for up to this timeout value [ms].
  BOOL *ring_detected                      //!< A boolean to indicate if a ring signal was detected.
  );




#ifdef __cplusplus
}
#endif


#endif // _C_SERIALPORT_H_