# Serial Communications Class

Topics

:

OverviewOverview
Conditional Directives
Enumerations
Functions

Overview

The gxSerialComm class is a base class used to open a serial port for bi-directional communication. It includes several low-level functions needed by derived classes to initialize a serial port, transmit, and receive data.

Conditional Directives

__UNIX__

- Conditional directive required for all UNIX variants.

__WIN32__

- Conditional directive required for all WIN32 platforms

Enumerations

    enum {
      // Internal error codes used to report the serial port last error
      gxSerialComm::scomm_NO_ERROR  = 0,      // No errors reported
      gxSerialComm::scomm_INVALID_ERROR_CODE, // Invalid error code

      gxSerialComm::scomm_BAUDRATE_ERROR,    // Invalid baud rate
      gxSerialComm::scomm_CS_ERROR,          // Invalid character size
      gxSerialComm::scomm_FLOWCONTROL_ERROR, // Invalid flow control
      gxSerialComm::scomm_INIT_ERROR,        // Initialization error
      gxSerialComm::scomm_INVALIDPARM,       // Invalid parameter
      gxSerialComm::scomm_OPEN_ERROR,        // Cannot open serial device
      gxSerialComm::scomm_PARITY_ERROR,      // Invalid parity
      gxSerialComm::scomm_RECEIVE_ERROR,     // Serial device receive error
      gxSerialComm::scomm_STOPBIT_ERROR,     // Invalid stop bit
      gxSerialComm::scomm_TRANSMIT_ERROR,    // Transmit error

      // Exception codes added to handle variable block errors
      gxSerialComm::scomm_BLOCKACK_ERROR,    // Acknowledgment error
      gxSerialComm::scomm_BLOCKHEADER_ERROR, // Bad variable block header
      gxSerialComm::scomm_BLOCKSIZE_ERROR,   // Bad variable block size
      gxSerialComm::scomm_BLOCKSYNC_ERROR    // Synchronization error
     };

    enum {
      // Flow control constants
      gxSerialComm::scommHARD_FLOW,
      gxSerialComm::scommSOFT_FLOW,
      gxSerialComm::scommXON_XOFF,
      gxSerialComm::scommNO_FLOW_CONTROL,

      // Device access constants
      gxSerialComm::scommREAD_ONLY,
      gxSerialComm::scommWRITE_ONLY,
      gxSerialComm::scommREAD_WRITE
     };

Functions

gxSerialComm::gxSerialComm()
gxSerialComm::~gxSerialComm()
gxSerialComm::BinaryMode()
gxSerialComm::BytesMoved()
gxSerialComm::BytesRead()
gxSerialComm::CharacterMode()
gxSerialComm::Close()
gxSerialComm::DeviceHandle()
gxSerialComm::GetSerialCommError()
gxSerialComm::InitSerialPort()
gxSerialComm::OpenSerialPort()
gxSerialComm::RawRead()
gxSerialComm::RawWrite()
gxSerialComm::Recv()
gxSerialComm::ResetError()
gxSerialComm::ResetSerialCommError()
gxSerialComm::Send()
gxSerialComm::SerialCommExceptionMessage()
gxSerialComm::SetBaudRate()
gxSerialComm::SetCharacterSize()
gxSerialComm::SetFlowControl()
gxSerialComm::SetParity()
gxSerialComm::SetSerialCommError()
gxSerialComm::SetStopBits()
gxSerialComm::Send()

gxSerialComm::gxSerialComm()

- Default class constructor.

virtual gxSerialComm::~gxSerialComm()

- Class destructor used to automatically close an open serial device when a gxSerialComm object is deleted.

void gxSerialComm::BinaryMode()

- Public member function used to toggle from character mode to binary mode. NOTE: This function has no effect under WIN32. The Win32 API does not support non-binary mode transfers.

int gxSerialComm::BytesMoved()

- Public member function that returns the number of bytes moved following a write operation.

int gxSerialComm::BytesRead()

- Public member function that returns the number of bytes read following a read operation.

void gxSerialComm::CharacterMode()

- Public member function used to toggle from binary mode to character mode. NOTE: This function has no effect under WIN32. The Win32 API does not support non-binary mode transfers.

void gxSerialComm::Close()

- Public member function used to close a previously opened serial device.

scommDeviceHandle gxSerialComm::DeviceHandle()

- Public member function that returns the device handle for the currently opened serial device.

int gxSerialComm::GetSerialCommError()

- Public member function used to retrieve the last reported serial port error. The return value will correspond to one of the integer constants defined in the error code enumeration.

int gxSerialComm::GetSerialCommError()

- Public member function used to retrieve the last reported serial port error. The return value will correspond to one of the integer constants defined in the error code enumeration.

int gxSerialComm::InitSerialPort()

- Public member function used to initialize a serial device. Returns zero to indicate success or -1 to indicate a serial port error.

int gxSerialComm::InitSerialPort(char *device_name, int sp = 9600, char pr = 'N', int cs = 8, int sb = 1, int flow = gxSerialComm::scommNO_FLOW_CONTROL,int bin_mode = 1)

- Public member function used to initialize a serial device. Returns zero to indicate success or -1 to indicate a serial port error.

int gxSerialComm::OpenSerialPort(char *device_name)

- Public member function to open a serial port for read/write operations depending on the device file permissions. This function will try to open the device for read/write, read, and then write access. Returns -1 if the device cannot be opened. This function will return a non-zero value corresponding to one of the integer constants defined in the device access enumeration if the serial device is opened successfully.

int gxSerialComm::RawRead(void *buf, int bytes)

- Public member function used read a specified number of bytes from the serial port and return whether or not the read was completed. Returns the number of bytes received or -1 if an error occurred.

int gxSerialComm::RawWrite(const void *buf, int bytes)

- Public member function used to write a specified number of bytes to a serial port and return whether or not the write was complete. Returns the total number of bytes moved or -1 if an error occurred.

int gxSerialComm::Recv(void *buf, int bytes)

- Public member function used to receive a specified number of bytes from a serial port and does not return until all the byte have been read. Returns the total number of bytes read or -1 if an error occurred.

void gxSerialComm::ResetError()

- Public member function used to clear the last reported serial device error.

void gxSerialComm::ResetSerialCommError()

- Public member function used to clear the last reported serial device error.

int gxSerialComm::Send(const void *buf, int bytes)

- Public member function used to write a specified number of bytes to a serial port and does not return until all the bytes have been written. Returns the total number of bytes written or -1 if an error occurred.

const char *gxSerialComm::SerialCommExceptionMessage()

- Public member function that returns a null-terminated string that can be use to log or print a serial port exception.

void gxSerialComm::SetBaudRate(int br)

- Public member function used to set the baud rate prior to initialization.

void gxSerialComm::SetCharacterSize(int cs)

- Public member function used to set the character size prior to initialization.

void gxSerialComm::SetFlowControl(int f)

- Public member function used to set the flow control prior to initialization. The "f" variable must equal one of the integer constants defined in the flow control enumeration.

void gxSerialComm::SetParity(char p)

- Public member function used to set the parity prior to initialization.

void gxSerialComm::SetSerialCommError(int err)

- Public member function used to set the serial device error code. The "err" variable must equal one of the integer constants defined in the error code enumeration.

void gxSerialComm::SetStopBits(int sb)

- Public member function used to set the stop bits prior to initialization.

int gxSerialComm::Send(const void *buf, int bytes)

- Public member function used to write a specified number of bytes to a serial port and does not return until all the bytes have been written. Returns the total number of bytes written or -1 if an error occurred.

End Of Document