/**
 * \brief RS232 communication
 * \copyright 2013-2014, IQ² Development GmbH, Neckartenzlingen. All rights reserved.
 */

#ifndef _iqi_rs232_h
#define _iqi_rs232_h

/**
 * \brief Scan for available com ports
 *
 * \param[in]   ucFromPortNo        com port number search from
 * \param[in]   ucUntilPortNo       com port number until search
 * \param[out]  ucpFoundPorts       list with founded ports [256]
 * \param[out]  cpErrMsg            an error message (minimum 256 symbols!)
 */
int16 rs232_ScanPorts(uchar08 ucFromPortNo,
                      uchar08 ucUntilPortNo,
                      uchar08 *ucpFoundPorts,
                      char08 *cpErrMsg);

/**
 * \brief Get existing com-port handle to reuse it in other process instance
 *
 * Usefull for example in order to reuse already openning com-port in another DLL.
 *
 * \param[in]   uiPortNo      IQI's com-port number
 * \param[out]  hpPort        a pointer to com-port handle variable
 * \param[out]  cpErrMsg      an error message (minimum 256 symbols!)
 */
int16 rs232_GetPortHandle(uint16 uiPortNo,
                          HANDLE *hpPort,
                          char08 *cpErrMsg);

/**
 * \brief Set com-port handle explicitly to reuse it without opening
 *
 * Usefull for example in order to reuse already openning com-port in another DLL.
 *
 * \param[in]   uiPortNo      IQI's com-port number
 * \param[in]   hPort         an existing com-port handle
 * \param[out]  cpErrMsg      an error message (minimum 256 symbols!)
 */
int16 rs232_SetPortHandle(uint16 uiPortNo,
                          HANDLE hPort,
                          char08 *cpErrMsg);

/**
 * \brief Open com-port for IQI-communication
 *
 * \param[in]   uiPortNo      IQI's com-port number
 * \param[out]  ulBaudrate    a required baud rate
 * \param[out]  cpErrMsg      an error message (minimum 256 symbols!)
 */
int16 rs232_OpenPort(uint16 uiPortNo,
                     ulong32 ulBaudrate,
                     char08 *cpErrMsg);

int16 rs232_OpenPortWithTimeout(uint16 uiPortNo,
                                ulong32 ulBaudrate,
                                uint16 uiTimeoutMs,
                                char08 *cpErrMsg);

/**
 * \brief Close com-port for IQI-communication
 *
 * \param[in]   uiPortNo      IQI's com-port number
 * \param[out]  cpErrMsg      an error message (minimum 256 symbols!)
 */
int16 rs232_ClosePort(uint16 uiPortNo,
                      char08 *cpErrMsg);

/**
 * \brief Change com-port baud rate
 *
 * \param[in]   uiPortNo      IQI's com-port number
 * \param[out]  ulBaudrate    a new required baud rate
 * \param[out]  cpErrMsg      an error message (minimum 256 symbols!)
 */
int16 rs232_ChangeBaudrate(uint16 uiPortNo,
                           ulong32 ulBaudrate,
                           char08 *cpErrMsg);

/**
 * \brief Read bytes from com-port into buffer
 *
 * \param[in]   uiPortNo      IQI's com-port number
 * \param[out]  ucpBuf        pointer on data buffer
 * \param[in]   ulBytesCount  count of bytes to read
 * \param[out]  cpErrMsg      an error message (minimum 256 symbols!)
 */
int16 rs232_Read(uint16 uiPortNo,
                 uchar08 *ucpBuf,
                 ulong32 ulBytesCount,
                 char08 *cpErrMsg);

/**
 * \brief Write buffer to com-port
 *
 * \param[in]   uiPortNo      IQI's com-port number
 * \param[in]   ucpBuf        pointer on data buffer to send
 * \param[in]   ulBytesCount  count of bytes to send
 * \param[out]  cpErrMsg      an error message (minimum 256 symbols!)
 */
int16 rs232_Write(uint16 uiPortNo,
                  uchar08 *ucpBuf,
                  ulong32 ulBytesCount,
                  char08 *cpErrMsg);

#endif
