[[TOC]]

= CComm =

CComm is a C++ class that is provided to simplify 825 serial and ethernet operations. CComm is a base class for the inherited classes CCommSerial (serial ports), CCommClient (TCP/IP client), and CCommServer (TCP/IP Server).

== Member Functions ==

=== Send ===
{{{
virtual int Send(CCommConnection *pConnection, const uint8* data, int len)
}}}

==== Description ====

The Send method sends the specified data over the specified connection. 

==== Parameters ==== 

 * pConnection - pointer to connection instance to send to, May be NULL to send to all instances. This is only significant for TCP/IP server, NULL will send to all connected clients, or specified connection will send to a specific connected client.
 * data - pointer to data to be sent
 * len - number of bytes of data to send

==== Return value ====

Send returns the number of characters sent if successful.

=== Process ===

{{{ 
void Process(void)
}}}

==== Description ====

The Process method must be called regularly for the communication channel to be serviced allowing any receive events to occur. This should usually be done in the app background event such as:
{{{
BACKGROUND_EVENT(Comm)
{
   if(pComm != NULL)
   {
      pComm->Process();
   }
}
}}}

=== !AddRcvEvent ===

{{{
void AddRcvEvent(uint8 chr, int (*pDataEvent)(CComm* pComm, CConnection *pConnnection, int nData, void* pUser), int nRawCnt = 0, void* pUser = NULL)
void AddRcvEvent(uint16 startchr, uint16 endchr, int (*pDataEvent)(CComm* pComm, CConnection *pConnnection, int nData, void* pUser), int nRawCnt = 0, void* pUser = NULL)
void AddRcvEvent(uint8 startchrs[], int startchrcnt, uint8 endchrs[], int endchrcnt, int (*pDataEvent)(CComm* pComm, CConnection *pConnnection, int nData, void* pUser), int nRawCnt = 0, void* pUser = NULL)
void AddRcvEvent(uint16 startchr, int (*pDataEvent)(CComm* pComm, CConnection *pConnnection, int nData, void* pUser), int nRawCnt = 0, void* pUser = NULL)
}}}

==== Parameters ==== 

 * chr - single character code to trigger event
 * startchr - character code to start receiving data for specified event, or START_CHR_ANY to start on any character received
 * startchrs - array of start characters to start receiving data if any of the characters is received, startchrcnt must be specified
 * startchrcnt - number of start characters in array startchrs.
 * endchr - character code to end receiving data for specified event, or END_CHR_ANY for unspecified
 * endchrs - array of end characters to stop receiving data if any of the characters is received. endchrcnt must be specified
 * endcharcnt - number of end characters in array endchrs.
 * nRawCnt - Normally 0 for variable length data, otherwise character count may be specified to receive specific number of binary characters after the start
 * pDataEvent - COMM_EVENT function to be called after endchr is received or specified number of raw count characters is received
 * pUser = User pointer to anything that may be useful that will be passed to the COMM_EVENT function.


==== Description ====

Specifies a receive event (callback function) when after data is received based on the specified start, end chars, data count. A COMM_EVENT preprocessor define is provided to simply the event function declarations.
If start character may be specified as START_CHR_ANY to start with any character. END_CHR_ANY for no specific end character. END_CHR_ANY should normally only be used if fixed size raw data is to be received and the nRawCnt value is specified.

==== Example ====

{{{
CComm *pComm = NULL;
// pComm is a pointer that can point to a CCommSerial, CCommClient, or CCommServer instance

#define SERIAL 1
#define CLIENT 2
#define SERVER 3

void StartCommunications(int commTypeSelection)
{
   if(commTypeSelection == SERIAL)
   {
      int commPort = 2;
      CCommSerial *pSerial = new CCommSerial(commPort);
      pComm = pSerial;
   }
   else if(commTypeSelection == CLIENT)
   {
      string svrIP = "192.168.1.25";
      int svrPort = 8001;
      CCommClient *pClient = new CCommClient(svrIP, svrPort);
      pComm = pClient;
   }
   else if(commTypeSelection == SERVER)
   {
      int svrPort = 8001;
      CCommServer *pServer = new CCommServer(svrPort);
      pComm = pServer;
   }

   pComm->Open();

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

   // Designate receive event COMM_EVENT(DataMsg) to be called when data starting with STX and ending with ETX is received
   pComm->AddRcvEvent(CHR_STX, CHR_ETX, NAME_COMM_EVENT(DataMsg), 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;
}


}}}

=== !SetDebugRawRead ===

{{{
void SetDebugRawRead(bool bDebugShowRawRead)
}}}

==== Parameters ==== 

 * bDebugShowRawRead - true to enable console output showing read data, false to disable

==== Description ====

This is only compiled for DEBUG build so must be wrapped with precompile options to only call this function when DEBUG defined.

==== Example ====

{{{
CComm *pComm = NULL;

void StartCommunications(void)
{
    int commPort = 2;
    CCommSerial *pSerial = new CCommSerial(commPort);
    pComm = pSerial;
 
    pComm->Open();

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

#if defined(DEBUG)
    // Helpful for initial development to see all characters received on the port
    pComm->SetDebugRawRead(true);
#endif
}


}}}

== See Also ==

 * [wiki:CCommSerial CCommSerial]
 * [wiki:CCommClient CCommClient]
 * [wiki:CCommServer CCommServer]