[[TOC]]

= CCommSerial =

CCommSerial is a C++ class that is provided to simplify 825 serial communications. CCommSerial is inherited from the CComm base class.

== Constructors ==

{{{
CCommSerial(void)
CCommSerial(int port);
}}}
These constructors just create a CCommSerial object without opening a communications channel.

==== Parameters ====
 * port - serial port number ( 1 = COM1, 2 = COM2 )

==== Examples ====

{{{
CCommSerial *pSerial = new CCommSerial(2);
// Creates a CCommSerial instance that when opened will connect to COM2
}}}

{{{
CCommSerial *pSerial = new CCommSerial();
// Creates a CCommSerial instance that does not have a port specified yet. Method SetPort() must be called before calling Open().
}}}

==== Example ====

{{{
   if(commTypeSelection == SERIAL)
   {
      int commPort = 2;
      CCommSerial *pSerial = new CCommSerial(commPort);
      pComm = pSerial;
   }
   pComm->Open();

   // Now the app can call pComm->Send to send data without regard for whether it is serial or TCP/IP.

   pComm->AddRcvEvent(CHR_STX, CHR_ETX, CommEventDataMsg, 0, NULL);

}

void StopCommunications(void)
{ 
   if(pComm != NULL)
   {
       pComm->Close();
       delete pComm;
       pComm = NULL;
   }
}

COMM_EVENT(DataMsg)
{
   uint8* buf = pConnection->GetRcvBuffer();
   buf[pConnection->GetRcvPos() - 1] = '\0';

   printf("rcvd [%s]\r\n", buf);

   if(buf[1] == 'T') // Received <STX>T<ETX> return timeval
   {
       time_t tmval;
       time(&tmval);  // Get timeval

       char response[12];
       sprintf(response, "%d\n", tmval);
       // pConnection isn't important in the case of serial port, but if TCP/IP server it is important to send
       // the response to the connection that the message was received from.
       pComm->Send(pConnection, response, strlen(response);
    }


   return 0;
}


}}}

== Member Functions ==

=== SetPort ===
Sets the communications port to be used when Open() is called.

{{{
void SetPort(int port);
}}}

==== Parameters ====
 * port - the port number

==== Return Value ====

Function does not return any parameters

=== Open ===
Opens a specified file, or using the filename already stored in the object.

{{{
int Open(void);
}}}

==== Parameters ====
 * void - no parameters

==== Return Value ====

Returns 1 if successful or 0 if unsuccessful.

==== Remarks ====

==== Example ====

{{{
}}}

=== Close ===
Closes the connection
{{{
int Close(void);
}}}

==== Parameters ====

Function does not accept any parameters

==== Return Value ====
 
Function always returns zero.

==== Remarks ====

For serial ports it may be necessary to provide some delay to allow all of the buffered data to be sent out of the port before closing the port.

==== Example ====

=== SetParameters ===
Set the baud rate, number of data bits, parity, and number of stop bits for serial ports.
{{{
bool SetParameters(baud_index baud, data_bit_index = data8, parity_index = parityNone, stop_bit_index = stopOne);
}}}

==== Parameters ====
 * baud_index - baud1200, baud2400, baud4800, baud9600, baud19200, baud38400, baud57600, or baud115200
 * data_bit_index - data7 or data8
 * parity_index - parityNone, parityEven, or parityOdd
 * stop_bit_index - stopOne or stopTwo

==== Return Value ====

Returns true if successful, false if not successful.

==== Remarks ====

==== Examples ====

{{{
CCommSerial* pSerial = new CCommSerial(2);
if(pSerial->Open())
{
   pSerial->SetParameters(CCommSerial::baud9600, CCommSerial::data7, CCommSerial::parityEven, CCommSerial::stopOne);
}
}}}

{{{
CCommSerial* pSerial = new CCommSerial(2);
if(pSerial->Open())
{
   pSerial->SetParameters(CCommSerial::baud19200);
}
}}}

=== IsReady ===
Check the state of the serial CTS input (for serial ports that are equipped with CTS input)
{{{
bool IsReady(void);
}}}
==== Parameters ==== 

Function does not accept any parameters.

==== Return Value ====

Function returns true if CTS is active, false if CTS is inactive.

==== Remarks ====

IsReady() will return false if the CTS line is unconnected. Printers or other devices must be wired correctly for applications to be able to use this function to determine their readiness. '''The main board COM3 is not currently supported by this function.'''

==== Example ====

{{{
CCommSerial *pSerial = new CCommSerial(2);
if(pSerial->Open())
{
   pSerial->SetRTS(true);
   if(pSerial->IsReady() == false)
   {
      DisplayText(0, 0, "Device offline, or disconnected");
   }
}
}}}


=== SetRTS ===
Set the state of the serial RTS output

{{{
bool SetRTS(bool bRTSOn = true);
}}}

==== Parameters ==== 

 * bRTSOn - true to turn on RTS output, false to turn off RTS output

==== Return Value ====

Returns true if successfully set RTS state, false otherwise.

==== Remarks ====

==== Example ====

{{{
CCommSerial* pSerial = new CCommSerial(2);
if(pSerial->Open())
{
   pSerial->SetRTS(true);
}
}}}







== See Also ==

 * [http://tech.825spectrum.com/wiki/Docs/Prog/Manual/ApplicationLibraries/lib825ev/Comm/CComm CComm]
 * [http://tech.825spectrum.com/wiki/Docs/Prog/Manual/ApplicationLibraries/lib825ev/Comm/CCommClient CCommClient]
 * [http://tech.825spectrum.com/wiki/Docs/Prog/Manual/ApplicationLibraries/lib825ev/Comm/CCommServer CCommServer]