serialport.c

Go to the documentation of this file.

/**
\file    serialport.c
\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.
*/

#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include "serialport.h"

#define SERIALPORT_SETUPCOMM_INTERNAL_BUFFER_SIZE (8192)   //!< Internal buffer size used by the serial port. 8 KB should be plenty.


/// \brief  A function to assist in error reporting.
static BOOL SERIALPORT_static_ReportLastError();



BOOL SERIALPORT_Initialize( SERIALPORT_structObject* serialport )
{
  if( serialport == NULL )
  {
    SERIALPORT_ERROR_MSG( "if( serialport == NULL )" );
    return FALSE;
  }
  serialport->baudrate = SERIALPORT_BAUD_9600;
  serialport->parity   = SERIALPORT_PARITY_NONE;
  serialport->databits = SERIALPORT_DATABITS_8;
  serialport->stopbits = SERIALPORT_STOPBITS_1;
  serialport->flowcontrol = SERIALPORT_FLOWCONTROL_NONE;
  serialport->isPortOpen = FALSE;

  serialport->port = 0;      // not yet a valid port.
  serialport->timeout = 0; // 100 ms time-out default.
  serialport->handle = NULL; // invalid handle initially.

  serialport->behaviour = SERIALPORT_BEHAVIOUR_RETURN_IMMEDIATELY;

  memset( &serialport->control_setting, 0, sizeof(serialport->control_setting) );

  return TRUE;
}




BOOL SERIALPORT_Open( SERIALPORT_structObject* serialport )
{
  char msg[128];
  char comName[8];
  COMMTIMEOUTS CommTimeouts;
  WCHAR comStr[8];
  unsigned i = 0;

  if( serialport == NULL )
  {
    SERIALPORT_ERROR_MSG( "if( serialport == NULL )" );
    return FALSE;
  }
  
  // Check if the port is already open
  if( serialport->isPortOpen )
  {
    sprintf( msg, "Serial port %d is already open.", serialport->port );
    SERIALPORT_ERROR_MSG( msg );
    return FALSE;
  }

  sprintf( comName, "COM%d", serialport->port );

  for( i = 0; i < 8; i++ )
  {
    comStr[i] = comName[i];
  }

  // open the port
  // CreateFile() refer http://msdn.microsoft.com/en-us/library/aa363858(VS.85).aspx
  serialport->handle = CreateFile( 
    comStr,            // e.g. "COM1"
    GENERIC_READ | GENERIC_WRITE, // access rights: read and write
    0,                            // exclusive access
    NULL,                         // no security attributes
    OPEN_EXISTING,                // the serial port must exist on the system.
    0,                            // no flags or attributes
    NULL                          // No template file is needed
    );

  // check the handle
  if( serialport->handle == INVALID_HANDLE_VALUE )
  {
    SERIALPORT_ERROR_MSG( "CreateFile returned an invalid handle.\nGetLastError() reports:\n" );
    SERIALPORT_static_ReportLastError();    
    return FALSE;
  }

  // set buffer sizes
  // SetupComm() refer http://msdn.microsoft.com/en-us/library/aa363439.aspx
  if( !SetupComm( serialport->handle, SERIALPORT_SETUPCOMM_INTERNAL_BUFFER_SIZE, SERIALPORT_SETUPCOMM_INTERNAL_BUFFER_SIZE ) )
  {
    SERIALPORT_ERROR_MSG( "SetupComm returned error condition.\nGetLastError() reports:\n" );   
    SERIALPORT_static_ReportLastError();    
    SERIALPORT_Close( serialport );
    return FALSE;
  }

  if( !GetCommState(serialport->handle, &serialport->control_setting) )
  {
    SERIALPORT_ERROR_MSG( "GetCommState returned error condition.\nGetLastError() reports:\n" );    
    SERIALPORT_static_ReportLastError();    
    SERIALPORT_Close( serialport );
    return FALSE;
  }

  // see http://msdn.microsoft.com/en-us/library/aa363214(VS.85).aspx
  serialport->control_setting.BaudRate = serialport->baudrate;
  serialport->control_setting.ByteSize = serialport->databits;
  serialport->control_setting.Parity   = serialport->parity;
  serialport->control_setting.StopBits = serialport->stopbits;
  if( serialport->parity != SERIALPORT_PARITY_NONE )
  {
    serialport->control_setting.fParity = TRUE;
  }
  else
  {
    serialport->control_setting.fParity = FALSE;
  }

  if( serialport->flowcontrol == SERIALPORT_FLOWCONTROL_NONE )
  {
    serialport->control_setting.fOutxCtsFlow = 0;
    serialport->control_setting.fOutxDsrFlow = 0;
    serialport->control_setting.fDtrControl  = DTR_CONTROL_DISABLE;
    serialport->control_setting.fOutX        = 0;
    serialport->control_setting.fInX         = 0;
    serialport->control_setting.fRtsControl  = RTS_CONTROL_DISABLE;
  }
  else if( serialport->flowcontrol == SERIALPORT_FLOWCONTROL_HARDWARE )
  {
    serialport->control_setting.fOutxCtsFlow  = 1;
    serialport->control_setting.fOutxDsrFlow  = 1;
    serialport->control_setting.fDtrControl  = DTR_CONTROL_HANDSHAKE;
    serialport->control_setting.fOutX        = 0;
    serialport->control_setting.fInX         = 0;
    serialport->control_setting.fRtsControl  = RTS_CONTROL_HANDSHAKE;
  }
  else if( serialport->flowcontrol == SERIALPORT_FLOWCONTROL_XONXOFF )
  {
    serialport->control_setting.fOutxCtsFlow  = 0;
    serialport->control_setting.fOutxDsrFlow  = 0;
    serialport->control_setting.fDtrControl  = DTR_CONTROL_ENABLE;
    serialport->control_setting.fOutX        = 1;
    serialport->control_setting.fInX         = 1;
    serialport->control_setting.fRtsControl  = RTS_CONTROL_ENABLE;
  }
  else
  {
    SERIALPORT_ERROR_MSG( "Unexpected" );   
    return FALSE;
  }

  // set the COM port settings
  // refer http://msdn.microsoft.com/en-us/library/aa363436.aspx
  if( !SetCommState( serialport->handle, &serialport->control_setting ) )
  {
    SERIALPORT_ERROR_MSG( "SetCommState returned error condition.\nGetLastError() reports:\n" );    
    SERIALPORT_static_ReportLastError();  
    SERIALPORT_Close( serialport );
    return FALSE;
  }

  // Retrieve the time-out parameters for all read and write operations on the port.  
  // http://msdn.microsoft.com/en-us/library/aa363261(VS.85).aspx
  if( !GetCommTimeouts( serialport->handle, &CommTimeouts ) )
  {
    SERIALPORT_ERROR_MSG( "GetCommTimeouts returned error condition.\nGetLastError() reports:\n" );   
    SERIALPORT_static_ReportLastError();  
    SERIALPORT_Close( serialport );
    return FALSE;
  }

  if( serialport->behaviour == SERIALPORT_BEHAVIOUR_WAIT_UNTIL_BYTES_DETECTED )
  {
    CommTimeouts.ReadIntervalTimeout = MAXDWORD;
    CommTimeouts.ReadTotalTimeoutMultiplier = MAXDWORD;
    CommTimeouts.ReadTotalTimeoutConstant = serialport->timeout;
  }
  else if( serialport->behaviour == SERIALPORT_BEHAVIOUR_RETURN_IMMEDIATELY )
  {
    CommTimeouts.ReadIntervalTimeout = MAXDWORD;
    CommTimeouts.ReadTotalTimeoutMultiplier = 0;
    CommTimeouts.ReadTotalTimeoutConstant = 0;
    serialport->timeout = 0;
  }
  else
  {
    SERIALPORT_ERROR_MSG("Unexpected.");
    return FALSE;
  }

  if( !SetCommTimeouts( serialport->handle, &CommTimeouts ) )
  {
    SERIALPORT_ERROR_MSG( "SetCommTimeouts returned FALSE.\nGetLastError() reports:\n" );   
    SERIALPORT_static_ReportLastError();
    SERIALPORT_Close( serialport );
    return FALSE;
  }

  serialport->isPortOpen = TRUE;

  return TRUE;
}

BOOL SERIALPORT_Close( SERIALPORT_structObject* serialport )
{
  if( serialport == NULL )
  {
    SERIALPORT_ERROR_MSG( "if( serialport == NULL )" );
    return FALSE;
  }
  if( serialport->isPortOpen )
  {
    if( !CloseHandle( serialport->handle ) )
    {
      SERIALPORT_ERROR_MSG( "CloseHandle returned FALSE.\nGetLastError() reports:\n" );   
      SERIALPORT_static_ReportLastError();        
      return FALSE;
    }
    serialport->isPortOpen = FALSE;
    serialport->handle = NULL;
    return TRUE;
  }
  else
  {
    SERIALPORT_ERROR_MSG( "The serial port is not open." );   
    return FALSE;
  }
}


/*
BOOL SERIALPORT_IsDataAvailableToRead( SERIALPORT_structObject* serialport, BOOL* isAvailable )
{
  BOOL result;
  if( serialport->isPortOpen )
  {
    unsigned long eventMask = 0;

    // refer http://msdn.microsoft.com/en-us/library/aa363435.aspx

    // Wait briefly on the event EV_RXCHAR (0x0001).
    // This means a character was received and placed in the input buffer.

    if( !SetCommMask( serialport->handle, EV_RXCHAR ) )
    {
      SERIALPORT_ERROR_MSG( "SetCommMask returned FALSE.\nGetLastError() reports:\n" );
      SERIALPORT_static_ReportLastError();
      SERIALPORT_Close( serialport );
      return FALSE;
    }

    if( !WaitCommEvent( serialport->handle, &eventMask, NULL ) )
    {
      SERIALPORT_ERROR_MSG( "WaitCommEvent returned FALSE.\nGetLastError() reports:\n" );
      SERIALPORT_static_ReportLastError();
      SERIALPORT_Close( serialport );
      return FALSE;
    }

    return TRUE;
  }
  else
  {
    SERIALPORT_ERROR_MSG( "The serial port is not open." );   
    return FALSE;
  }
}
*/

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.
  unsigned int *bytesRead                     //!< The number of bytes read and stored in the buffer.
  )
{
  BOOL result;
  DWORD dwbytesRead = 0;
  *bytesRead = 0;  

  if( serialport == NULL )
  {
    SERIALPORT_ERROR_MSG( "if( serialport == NULL )" );
    return FALSE;
  }
  if( serialport->isPortOpen )
  {
    result = ReadFile(
      serialport->handle, 
      buffer, 
      bytesAvailableInBuffer, 
      (LPDWORD)&dwbytesRead, 
      NULL );

    *bytesRead = dwbytesRead;

    if( GetLastError() == ERROR_IO_PENDING )
    {
      // The read operation is pending completion asynchronously. This is not an error.
      return TRUE;
    }
    if( !result )
    {
      SERIALPORT_ERROR_MSG( "ReadFile returned FALSE.\nGetLastError() reports:\n" );
      SERIALPORT_static_ReportLastError();        
      SERIALPORT_Close( serialport );
      return FALSE;
    }
    else
    {      
      return TRUE;
    }
  }
  else
  {
    SERIALPORT_ERROR_MSG( "The serial port is not open." );   
    return FALSE;
  }
}

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.  
  )
{  

  BOOL result;
  DWORD dwbytesWritten = 0;
  
  if( serialport == NULL )
  {
    SERIALPORT_ERROR_MSG( "if( serialport == NULL )" );
    return FALSE;
  }
  if( serialport->isPortOpen )
  {
    // write to file
    result = WriteFile( 
      serialport->handle,
      buffer,
      numberOfBytesToWrite,
      (LPDWORD)&dwbytesWritten,
      NULL 
      );

    if( GetLastError() == ERROR_IO_PENDING )
    {
      // The write operation is pending completion asynchronously. This is not an error.
      return TRUE;
    }
    if( !result )
    {
      SERIALPORT_ERROR_MSG( "WriteFile returned FALSE.\nGetLastError() reports:\n" );
      SERIALPORT_static_ReportLastError();        
      SERIALPORT_Close( serialport );
      return FALSE;
    }
    else
    {   
      if( dwbytesWritten != numberOfBytesToWrite )
      {
        SERIALPORT_ERROR_MSG( "if( dwbytesWritten != numberOfBytesToWrite )" );
        return FALSE;
      }      
      return TRUE;
    }
  }
  else
  {
    SERIALPORT_ERROR_MSG( "The serial port is not open." );   
    return FALSE;
  }
}



BOOL SERIALPORT_static_ReportLastError()
{
  unsigned i = 0;
  char msg[8192];
  LPTSTR pszMessage;
  DWORD dwLastError = GetLastError(); 
  FormatMessage(
    FORMAT_MESSAGE_ALLOCATE_BUFFER | 
    FORMAT_MESSAGE_FROM_SYSTEM |
    FORMAT_MESSAGE_IGNORE_INSERTS,
    NULL,
    dwLastError,
    MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
    (LPTSTR)&pszMessage,
    0, 
    NULL 
    );
  for( i = 0; i < 8192; i++ )
  {
    msg[i] = (char)pszMessage[i];
    if( pszMessage[i] == '\0' )
    {
      break;
    }
  }
  SERIALPORT_ERROR_MSG( msg );

  return TRUE;
}


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.
  )
{
  BOOL result;
  DWORD EvtMask;
  SERIALPORT_enumBehaviour prev_behaviour;
  SERIALPORT_enumBehaviour prev_timeout;
  COMMTIMEOUTS CommTimeouts;

  if( serialport == NULL )
  {
    SERIALPORT_ERROR_MSG( "if( serialport == NULL )" );
    return FALSE;
  }
  if( !serialport->isPortOpen )
  {
    SERIALPORT_ERROR_MSG( "if( !serialport->isPortOpen )" );
    return FALSE;
  }

  result = GetCommMask( serialport->handle, &EvtMask );
  if( !result )
  {
    SERIALPORT_ERROR_MSG( "GetCommMask returned FALSE.\nGetLastError() reports:\n" );
    SERIALPORT_static_ReportLastError();        
    SERIALPORT_Close( serialport );
    return FALSE;
  }
  EvtMask |= EV_RING;

  result = SetCommMask( serialport->handle, EvtMask );
  if( !result )
  {
    SERIALPORT_ERROR_MSG( "SetCommMask returned FALSE.\nGetLastError() reports:\n" );
    SERIALPORT_static_ReportLastError();        
    SERIALPORT_Close( serialport );
    return FALSE;
  }

  // Alter the serial port so that it has a timeout value.
  prev_behaviour = serialport->behaviour; // store the old behaviour  
  prev_timeout = serialport->timeout; // and old timout
  serialport->behaviour = SERIALPORT_BEHAVIOUR_WAIT_UNTIL_BYTES_DETECTED;
  
  // Retrieve the time-out parameters for all read and write operations on the port.
  // http://msdn.microsoft.com/en-us/library/aa363261(VS.85).aspx
  if( !GetCommTimeouts( serialport->handle, &CommTimeouts ) )
  {
    SERIALPORT_ERROR_MSG( "GetCommTimeouts returned error condition.\nGetLastError() reports:\n" );   
    SERIALPORT_static_ReportLastError();  
    SERIALPORT_Close( serialport );
    return FALSE;
  }

  CommTimeouts.ReadIntervalTimeout = MAXDWORD;
  CommTimeouts.ReadTotalTimeoutMultiplier = MAXDWORD;
  CommTimeouts.ReadTotalTimeoutConstant = timeout_ms;

  if( !SetCommTimeouts( serialport->handle, &CommTimeouts ) )
  {
    SERIALPORT_ERROR_MSG( "SetCommTimeouts returned FALSE.\nGetLastError() reports:\n" );   
    SERIALPORT_static_ReportLastError();
    SERIALPORT_Close( serialport );
    return FALSE;
  }

  EvtMask = 0;
  result = WaitCommEvent(
    serialport->handle,
    &EvtMask,
    NULL
    );
  if( !result )
  {
    SERIALPORT_ERROR_MSG( "WaitCommEvent returned FALSE.\nGetLastError() reports:\n" );
    SERIALPORT_static_ReportLastError();        
    SERIALPORT_Close( serialport );
    return FALSE;
  }

  if( EvtMask == EV_RING )
  {
    *ring_detected = TRUE;
  }

  serialport->behaviour = prev_behaviour;
  serialport->timeout = prev_timeout;

  if( serialport->behaviour == SERIALPORT_BEHAVIOUR_WAIT_UNTIL_BYTES_DETECTED )
  {
    CommTimeouts.ReadIntervalTimeout = MAXDWORD;
    CommTimeouts.ReadTotalTimeoutMultiplier = MAXDWORD;
    CommTimeouts.ReadTotalTimeoutConstant = serialport->timeout;
  }
  else if( serialport->behaviour == SERIALPORT_BEHAVIOUR_RETURN_IMMEDIATELY )
  {
    CommTimeouts.ReadIntervalTimeout = MAXDWORD;
    CommTimeouts.ReadTotalTimeoutMultiplier = 0;
    CommTimeouts.ReadTotalTimeoutConstant = 0;
    serialport->timeout = 0;
  }
  else
  {
    SERIALPORT_ERROR_MSG("Unexpected.");
    return FALSE;
  }
  if( !SetCommTimeouts( serialport->handle, &CommTimeouts ) )
  {
    SERIALPORT_ERROR_MSG( "SetCommTimeouts returned FALSE.\nGetLastError() reports:\n" );   
    SERIALPORT_static_ReportLastError();
    SERIALPORT_Close( serialport );
    return FALSE;
  }

  return TRUE;
}