CSerialFile : CDummyFile

$Revision: 55 $

Description

This class makes it easy to play with serial ports in NT. The serial ports in Windows 95 are screwed up so this class may not work the same way under 95 as it does in NT. I haven't had time to play with the Win95 stuff yet.

Data Members

FileHandle - A handle that you can use to call the native Win32 API yourself. You can modify this value but CSerialFile will ignore the change. In other words, you can't break the class by modifying this variable.

Name - The name passed in to the Open() function.

Methods

BOOL CancelWaitFor( void )

WaitFor() is a blocking call. The thread from which you call WaitFor() will stop running until whatever you're waiting for happens. Sometimes you will never get what you wait for. This means your thread will never wake up. To get out of this problem, you can call CancelWaitFor() from another thread (usually the parent thread).

BOOL ClearBreak( void )

Resumes transmission of data.

BOOL Close( void )

Closes the serial port.

BOOL ConfigurationDialog( CCommunicationsConfiguration& configuration, BOOL save_changes = TRUE, HWND parent_window_handle = NULL )

It pops up a dialogbox letting you change the parameters of the serial port.

DWORD GetBaudRate( void )

Returns the current baud rate.

BOOL GetConfiguration( CCommunicationsConfiguration& configuration )

Retrieves the configuration of the serial port.

DWORD GetFlowControl( void )

Retrieves the type of flow control being used.

DWORD GetInputBufferSize( void ) const

Retrieves the input buffer size set via SetInputBufferSize().

DWORD GetModemStatus( void )

Retrieves the status of the modem if there is one. The return value is a 32-bit wide bit field. You must and the return value with one of these flags (defined in WINBASE.H to see if that status is true:

MS_CTS_ON - To see if the Clear to Send (CTS) pin is high
MS_DSR_ON - To see if the Data Set Ready (DSR) pin is high
MS_RING_ON - To see if the modem has detected a ring
MS_RLSD_ON - To see if the Receive Line Signal Detect (RLSD) signal is on

DWORD GetOutputBufferSize( void ) const

Retrieves the output buffer size set via SetOutputBufferSize().

BOOL GetProperties( CCommunicationProperties& properties )

Gets properties about the provider of the serial port. Returns the data in a CCommunicationProperties object.

BOOL GetState( CDeviceControlBlock& device_control_block )

Gets the state of the port.

BOOL GetTimeouts( COMMTIMEOUTS& timeouts )

Retrieves the timeouts (COMMTIMEOUTS).

BOOL IsDataWaiting( void )

Returns TRUE if there is data waiting to be read. If the number of bytes in the input queue is zero then it will return FALSE.

DWORD NumberOfBytesWaitingToBeRead( void )

Hhhhmmm, Gee I wonder...

DWORD NumberOfBytesWaitingToBeWritten( void )

Hhhhmmm, Gee I wonder...

BOOL Open( void ) BOOL Open( LPCTSTR channel_name, UINT flags = 0, CFileException * exception_p = NULL )

Opens the serial port. You pass the name of the serial port in the "COM1:9600,n,8,1" format.

BOOL Purge( DWORD what_to_purge = purgeAll )

Purges data in the system buffers. what_to_purge can be one or a combination of the following:

purgeTerminateWriteOperation
purgeTerminateReadOperation
purgeClearInputBuffer
purgeClearOutputBuffer
purgeAll

UINT Read( void *buffer, UINT length )

Reads data from the serial port.

BOOL ReplaceGarbledCharacter( yes_or_no = TRUE, BYTE replacement_character = ' ' )

You can tell the serial driver to automagically replace garbled characters with a known character. The Open() function sets this mode on replacing garbles with spaces (' ').

Serialize

Saves/restores the object.

BOOL SetBaudRate( DWORD baud_rate )

Changes the current baud rate to baud_rate.

BOOL SetBreak( void )

Halts transmission of data. You must call ClearBreak() to resume data IO. These are handy functions to use if you have a lot of processing you need to perform on the data received from the serial port.

BOOL SetCharacterToWaitFor( BYTE character_to_wait_for )

Sets the character to wait for when you WaitFor() with waitParticularCharacterReceived flag.

BOOL SetDataTerminalReady( BOOL set_DTR_on = TRUE )

Sets the DTR pin high (TRUE) or low (FALSE).

void SetFlowControl( DWORD flow_control )

Sets the serial port to use the type of flow control you specify.

void SetInputBufferSize( DWORD buffer_size )

Sets the size of the system input buffer for the serial port. Make this call before you Open() the port. The default is 4096.

void SetOutputBufferSize( DWORD buffer_size )

Sets the size of the system output buffer for the serial port. Make this call before you Open() the port. The default is 4096.

BOOL SetPurgeBufferOnError( BOOL purge_buffer = TRUE )

This method lets you specify whether or not the buffer will be purged when an error occurs. This usually happened when the hardware detected a framing error. The default is to NOT purge the buffer. The return value is the previous state of the setting.

BOOL SetRequestToSend( BOOL set_RTS_on = TRUE )

Sets the RTS pin high (TRUE) or low (FALSE).

BOOL SetState( CDeviceControlBlock& device_control_block )

Sets the state of the port.

BOOL SetTimeouts( COMMTIMEOUTS * timeouts_p = NULL )

Sets the timeouts (COMMTIMEOUTS).

BOOL TransmitCharacter( char character_to_transmit )

Will interrupt the transmission of any buffered data and send character_to_transmit immediately. This is kind of dangerous to do.

BOOL WaitFor( DWORD& stuff_you_can_wait_for )

Stops execution of your thread until one of the events has occured. The stuff_you_can_wait_for parameter can be one of the following:

waitBreakDetected
waitClearToSendChangedState
waitDataSetReadyChangedState
waitLineStatusError
waitRing
waitReceiveLineSignalDetectChangedState
waitAnyCharacterReceived
waitParticularCharacterReceived
waitTransmitBufferEmpty

BOOL WaitForString( const CString& string_to_wait_for, DWORD timeout_seconds = 5, CString * what_was_read )

This handy dandy routine will wait for a specified time for a specified string to come into the serial port. It is good for dealing with text devices.

void Write( BYTE byte_to_write ) void Write( const CByteArray& array_of_bytes ) void Write( CString& string_to_write ) void Write( const void * buffer, UINT number_of_bytes )

Sends data to the serial port. You can send data using a CString, CByteArray or plain old void pointer. Writing a single BYTE differs from TransmitCharacter() in that writing the BYTE queues the byte to be transmitted.

Example

void wait_for_ring( void )
{
   WFCTRACEINIT( TEXT( "wait_for_ring()" ) );

   CSerialFile serial;

   while( 1 )
   {
      _tprintf( TEXT( "Opening serial port\n" ) );

      if ( serial.Open( TEXT( "COM1:57600,n,8,1" ) ) != FALSE )
      {
         CString response;

         response = TEXT( "ATM0\r\n" );

         serial.Write( response );

         // See if the phone rang

         while ( serial.WaitForString( TEXT( "RING" ), 2, &response ) == FALSE )
         {
            if ( response.GetLength() > 0 )
            {
               _tprintf( TEXT( "Didn't get RING, going to sleep \"%s\"\n" ), (LPCTSTR) response );
            }

            Sleep( 10000 );
         }

         _tprintf( TEXT( "Received a RING, waiting for them to end\n" ) );

         while( serial.WaitForString( TEXT( "RING" ), 7 ) != FALSE )
         {
            // Do Nothing
         }

         _tprintf( TEXT( "Closing serial port\n" ) );

         serial.Close();

         CTime time_now( CTime::GetCurrentTime() );

         Sleep( 1000 );

         CString message;

         message.Format( TEXT( "The phone rang at %s" ), (LPCTSTR) time_now.Format( "%H:%M:%S %d %b %y" ) );

         CSprintSpectrum pager;

         pager.SetAccount( TEXT( "4101234567" ) );
         pager.SetMessage( message );

         _tprintf( TEXT( "Calling pager.Send()\n" ) );
         pager.Send();
      }
      else
      {
         _tprintf( TEXT( "Can't open serial port\n" ) );
      }

      Sleep( 1000 );
   }
}

API's Used

CSerialFile encapsulates the following API's:

BuildCommDCB
ClearCommBreak
ClearCommError
CommConfigDialog
CreateFile
EscapeCommFunction
GetCommConfig
GetCommModemStatus
GetCommProperties
GetCommState
GetCommTimeouts
PurgeComm
SetCommBreak
SetCommConfig
SetCommMask
SetCommState
SetCommTimeouts
SetupComm
TransmitCommChar
WaitCommEvent

Copyright, 2000, Samuel R. Blackburn
$Workfile: serial.cpp $
$Modtime: 1/17/00 9:29a $