cbser.h File Reference

Serial port support. More...

#include "cbthr.h"
#include <wchar.h>
#include <termios.h>

Go to the source code of this file.

Data Structures
struct	t_cbserparam
	Describes a serial port parameter. More...
struct	t_comport
	Handle of the comport. More...
struct	t_cbserinfo
	Handle for cbserinfo() and cbserinfo_stop(). More...
Defines
#define	CBSTXTLEN   31
	Length of text entries used for describing com port names, baudrates, parities, number of databits or stopbits.
#define	DEFAULT_TIMEOUT   2000
	Default timeout.
Typedefs
typedef void(*)	t_cbsercb (const char *, size_t, void *)
	Type of the callback function called for each line of text retrieved from the serial port.
typedef void(*)	t_cbserinfocb (const char *, CBSERINFO, void *)
	Type of the callback function called in cbserinfo().
typedef int	t_hcomport
	Type for the serial port handle.
Enumerations
enum	CBSERINFO {   CBSI_INVALID, CBSI_BAUDRATE, CBSI_DATABITS, CBSI_PARITY,   CBSI_STOPBITS, CBSI_SERIALPORT, CBSI_READY }
	Type of information returned in the callback function by cbserinfo(). More...
Functions
void	cbserinitcom (t_comport *theHandle)
	Initializes the given handle with empty values.
void	cbserinitinfo (t_cbserinfo *theHandle)
	Initializes the given handle with empty values.
int	cbseropen (t_comport *theHandle, const char *aComPort, const t_cbserparam *aSpeed, const t_cbserparam *databits, const t_cbserparam *aParity, const t_cbserparam *stopbits, int aTimeout, t_cbsercb rdCb, void *aCtx)
	Opens serial port and starts reading it.
int	cbseropenstr (t_comport *theHandle, const char *aComPort, const char *aSpeed, const char *databits, const char *aParity, const char *stopbits, int aTimeout, t_cbsercb rdCb, void *aCtx)
	Opens serial port and starts reading it.
int	cbseropenwstr (t_comport *theHandle, const wchar_t *aComPort, const wchar_t *aSpeed, const wchar_t *databits, const wchar_t *aParity, const wchar_t *stopbits, int aTimeout, t_cbsercb rdCb, void *aCtx)
	Opens serial port and starts reading it.
int	cbserwrite (const t_comport *aHandle, const char *aBuf, size_t aLen)
	Writes the given number of bytes from the given buffer into the serial port.
int	cbserclose (t_comport *theHandle)
	Closes the given serial port.
int	cbserinfo (t_cbserinfo *theHandle, t_cbserinfocb cbsicb, void *aCtx)
	Returns serial port informations.
int	cbserinfo_end (t_cbserinfo *theHandle, short doStop)
	Stops the background information retrieving.
Variables
const t_cbserparam	COMSPEEDS []
	Array of serial port speeds.
const t_cbserparam	COMDATABITS []
	Array of available numbers of databits for a serial port.
const t_cbserparam	COMPARITIES []
	Array of available parities for a serial port.
const t_cbserparam	COMSTOPBITS []
	Array of available stopbits for a serial port.
const char *	DEFAULTPORT
	Default name of the com port, only informational purposes.
const char *	DEFAULTSPEED
	Default baudrate, only informational purposes.
const char *	DEFAULTDATABITS
	Default number of databits, only informational purposes.
const char *	DEFAULTPARITY
	Default parity, only informational purposes.
const char *	DEFAULTSTOPBITS
	Default number of stopbits, only informational purposes.
const int	NCOMSPEEDS
	Number of speed definition in COMSPEEDS.
const int	NCOMDATABITS
	Number of databit number defintions in COMDATABITS.
const int	NCOMPARITIES
	Number of parity definitions in COMPARITIES.
const int	NCOMSTOPBITS
	Number of stop bit definitions in COMSTOPBITS.
const t_hcomport	CBINVALIDCOMPORT
	Invalid comport returned by the opencomport() on error.

---

Detailed Description

Serial port support.

Opens a serial port, reads line of text from it in a background thread calling a callback procedure for each line read, writes data to a serial port and return informations about serial ports available in the system.

Example of use: the following program opens a serial port, prints lines of text coming from it, sends lines of thex to the serial port. If the program is called without command line parameters, then it prints a short usage info and informations about serial ports and their parameters availble in the system.

 #include "cbthr.h"
 #include "cbser.h"
 #include <stdio.h>
 #include <string.h>
 
 #define MAXBUF 4095
 
 static void _portinfo(const char *aText, CBSERINFO aType, void *aCtx) {
   const char *typetxt;
 
   switch(aType) {
     case CBSI_BAUDRATE   : typetxt = "baud"; break;
     case CBSI_DATABITS   : typetxt = "databits"; break;
     case CBSI_PARITY     : typetxt = "parity"; break;
     case CBSI_STOPBITS   : typetxt = "stopbits"; break;
     case CBSI_SERIALPORT : typetxt = "port"; break;
     case CBSI_READY      : typetxt = ""; break;
     default              : typetxt = "unknown"; break;
   }
   if (aText != NULL)
     printf("%8s : %6s\n", typetxt, aText);
 }
 
 static void _comread(const char *aLine, size_t aLen, void *aCtx) {
   if (aLine != NULL) fprintf(stdout, "COM: %s\n", aLine);
 }
 
 int main(int argc, char **argv) {
   char        buf[MAXBUF+1];
   t_comport   hcom;
   t_cbserinfo cbsi;
   
   cbserinitcom(&hcom);
   cbserinitinfo(&cbsi);
   if (argc < 5) {
     printf("Usage %s port baud databits parity stopbits\n", argv[0]);
     printf("Values available for the parameters:\n");
     cbserinfo(&cbsi, _portinfo, NULL);
     goto end;
   }
   if (cbseropenstr(&hcom, 
                    argv[1],
                    argv[2],
                    argv[3],
                    argv[4],
                    argv[5],
                    DEFAULT_TIMEOUT,
                    _comread,
                    NULL) == 0) goto end;
   printf("Enter a string to send to the comport or EXIT in order to break\n");
   while(fgets(buf, MAXBUF, stdin) != NULL) {
     if (buf[0] == 'E' && buf[1] == 'X'  && buf[2] == 'I' && buf[3] == 'T' &&
         (buf[4] == '\0' || buf[4] == '\r' || buf[4] == '\n')) break;
     if (cbserwrite(&hcom, buf, strlen(buf)) == 0) goto end;
   }
   end:
   cbserinfo_end(&cbsi, 0);
   cbserclose(&hcom);
   return 0;
 }

---

Define Documentation

#define CBSTXTLEN   31

Length of text entries used for describing com port names, baudrates, parities, number of databits or stopbits.

#define DEFAULT_TIMEOUT   2000

Default timeout.

Use this value for cbseropen(), cbseropenstr() and cbseropenwstr(), if you don't know a better one.

---

Typedef Documentation

typedef void(*) t_cbsercb(const char *, size_t, void *)

Type of the callback function called for each line of text retrieved from the serial port.

The parameters are the line of text, length of the line in characters and context.

typedef void(*) t_cbserinfocb(const char *, CBSERINFO, void *)

Type of the callback function called in cbserinfo().

The parameters are: parameter name, parametr type, context.

t_hcomport

Type for the serial port handle.

Only the comport. We use internally a more sophisticated handle type t_comport in order to identify the serial port.

See also:

t_comport

---

Enumeration Type Documentation

enum CBSERINFO

Type of information returned in the callback function by cbserinfo().

Enumerator:

CBSI_INVALID	invalid message type
CBSI_BAUDRATE	string describing the baudrate
CBSI_DATABITS	string describing the number of databits
CBSI_PARITY	string describing the parity
CBSI_STOPBITS	string describing the number of stopbits
CBSI_SERIALPORT	serial port name
CBSI_READY	cbserinfo is ready, no more informations available

---

Function Documentation

int cbserclose

(

t_comport *

theHandle

)

Closes the given serial port.

Closes the serial port, joins the reading thread and sets all fields in the given handle description to invalid values.

Parameters:

theHandle

the handle description of the serial port to close.

Returns:

!= 0 if everything wen OK, 0 on error.

int cbserinfo	(	t_cbserinfo *	theHandle,
		t_cbserinfocb	cbsicb,
		void *	aCtx
	)

Returns serial port informations.

For each serial port available on the system, each available baudrate, number of databits, parity and number of stopbits the function calls the given callback. It may be used in order to fill combo boxes for selecting serial port parameters or for printing a short info on the screen.

The informations are retreived in a background thread and it may take a long time, until the function is ready. Especially the function tries to open each serial port possibly available on the system in order to check, if the port can be opened and if it is really available. On small Windows CE devices it may take few seconds, until each of 10 of a windows system have been scanned.

The serial ports potencially available on the system are retrieved as:

1. ports COM0: ... COM9: on windows
2. available /dev/ttyS* and /dev/ttyUSB* ports on Linux
3. other Unix systems are not supported yet but they can be easyly adapted by using another filenames in /dev, eg. /dev/cua*, /dev/tty[a-z] etc.

The possibly available baudrates, databit numbers, parities and stopbit numbers are retrieved from the arrays COMSPEEDS, COMDATABITS, COMPARITIES and COMPSTOPBITS.

Parameters:

	theHandle	here the function returns the handle of the background thread retrieving the information. The handle may be used in order to stop the process in cbserinfo_end(). The function does nothing and returns an error, if this pointer is NULL.
	cbsicb	the callback function called for each information. The first parameter is a pointer to a zero terminated string with the returned information (baudrate name, name for the number of databits, parity, stopbits or the port name). Warning! It may be a pointer to the same temporary internal buffer, so that the callback fuction should use a copy of the passed string rather than to use the pointer directly. The second parameter of this callback is the type of the information passed to the callback function. This function calls the callback first for all available baudrates, databits, parities, stopbits, then for all available comports and finally it calls the callback with the first parameter set to NULL and the last parameter to CBSI_READY. The last parameter is the given context.
	aCtx	context for the callback function.

Returns:

!= 0 if everything wen OK, 0 on error.

int cbserinfo_end	(	t_cbserinfo *	theHandle,
		short	doStop
	)

Stops the background information retrieving.

Joins the background information retrieving started in cbserinfo().

Parameters:

	theHandle	pointer to the handle with the description of the background thread for retrieving the informations. The function returns an error, if this pointer is NULL.
	doStop	if != 0, then not only join but also break the background thread as soon as possible.

Returns:

!= 0 if everything wen OK, 0 on error.

void cbserinitcom

(

t_comport *

theHandle

)

Initializes the given handle with empty values.

The function may be used in order to have a safely initialized handle. It is not mandatory, as long, as cbseropen() or cbseropenstr() has been called before.

Parameters:

theHandle

the handle to initialize

void cbserinitinfo

(

t_cbserinfo *

theHandle

)

Initializes the given handle with empty values.

The function may be used in order to have a safely initialized handle. It is not mandatory, as long, as cbserinfo() has been called before.

Parameters:

theHandle

the handle to initialize

int cbseropen	(	t_comport *	theHandle,
		const char *	aComPort,
		const t_cbserparam *	aSpeed,
		const t_cbserparam *	databits,
		const t_cbserparam *	aParity,
		const t_cbserparam *	stopbits,
		int	aTimeout,
		t_cbsercb	rdCb,
		void *	aCtx
	)

Opens serial port and starts reading it.

Parameters:

	theHandle	the resulting handle of the opened serial port and started reading thread
	aComPort	the name of the serial port, zero terminated string.
	aSpeed	the baud rate.
	databits	number of databits.
	aParity	the parity.
	stopbits	number of stopbits.
	aTimeout	timeout in milliseconds to wait, until information arrives on the serial port between subsequent reading operations. Set it to a value, which is neighter to long nor to short. Short timeouts waste computer power, long timeouts cause long reposnse times, while closing the port and joining the reading thread. A value of few seconds, ie. 1000 to 4000 milliseconds, should be OK for the most purposes. Timeouts <= 0 are remapped to 1ms.
	rdCb	callback for each line of text received from the serial port. The lines of text are assumed to be separated either by carriage returns or new lines. the callback function gets a pointer to the buffer containing the received text, zero terminated and the length of the text. The pointer to the callback function may be also NULL, in this case the information is read from the serial port and dicarded afterwards.
	aCtx	context passed to the callback function.

Returns:

!= 0 if everything went OK, 0 on error.

See also:

cbseropenstr()

cbseropenwstr()

int cbseropenstr	(	t_comport *	theHandle,
		const char *	aComPort,
		const char *	aSpeed,
		const char *	databits,
		const char *	aParity,
		const char *	stopbits,
		int	aTimeout,
		t_cbsercb	rdCb,
		void *	aCtx
	)

Opens serial port and starts reading it.

Unlike cbseropen() this function uses names of serial port settings rather than their descriptions. The function can be used for example for text names for baudrate, number of databits, stopbits or parities entered as a command line parameter or in a text control of the GUI. The name of the certain parameters must match one of the names in the arrays of available settings in COMSPEEDS, COMDATABOTS, COMPARITIES or COMSTOPBITS.

Parameters:

	theHandle	the resulting handle of the opened serial port and started reading thread, passed directly to cbseropen().
	aComPort	the name of the serial port, zero terminated string, passed directly to cbseropen().
	aSpeed	the name of the baudrate, one of the names in COMSPEEDS.
	databits	the name of the number of databits, on of the names in COMDATABITS.
	aParity	the name of the parity, one of the names in COMPARITIES.
	stopbits	the name of the number of stopbits, one of the names in COMSTOPBITS.
	aTimeout	timeout in milliseconds, passed directly to cbseropne().
	rdCb	callback for each line of text received from the serial port. Passed directly to cbseropen().
	aCtx	context passed to the callback function.

Returns:

!= 0 if everything went OK, 0 on error.

See also:

cbseropen()

cbseropenwstr()

int cbseropenwstr	(	t_comport *	theHandle,
		const wchar_t *	aComPort,
		const wchar_t *	aSpeed,
		const wchar_t *	databits,
		const wchar_t *	aParity,
		const wchar_t *	stopbits,
		int	aTimeout,
		t_cbsercb	rdCb,
		void *	aCtx
	)

Opens serial port and starts reading it.

This function does the same like cbseropenstr(), but for unicode characters.

Parameters:

	theHandle	the resulting handle of the opened serial port and started reading thread, passed directly to cbseropen().
	aComPort	the name of the serial port, zero terminated string, passed directly to cbseropen().
	aSpeed	the name of the baudrate, one of the names in COMSPEEDS.
	databits	the name of the number of databits, on of the names in COMDATABITS.
	aParity	the name of the parity, one of the names in COMPARITIES.
	stopbits	the name of the number of stopbits, one of the names in COMSTOPBITS.
	aTimeout	timeout in milliseconds, passed directly to cbseropne().
	rdCb	callback for each line of text received from the serial port. Passed directly to cbseropen().
	aCtx	context passed to the callback function.

Returns:

!= 0 if everything went OK, 0 on error.

See also:

cbseropen()

cbseropenstr()

int cbserwrite	(	const t_comport *	aHandle,
		const char *	aBuf,
		size_t	aLen
	)

Writes the given number of bytes from the given buffer into the serial port.

Parameters:

	aHandle	the handle of the serial port returned by cbseropen().
	aBuf	the buffer with the bytes to write to the serial port.
	aLen	number of bytes from aBuf to write into aHandle.

Returns:

!= 0 if everything went OK, 0 on error.

---

Variable Documentation

const t_hcomport CBINVALIDCOMPORT

Invalid comport returned by the opencomport() on error.

const t_cbserparam COMDATABITS[]

Array of available numbers of databits for a serial port.

const t_cbserparam COMPARITIES[]

Array of available parities for a serial port.

const t_cbserparam COMSPEEDS[]

Array of serial port speeds.

const t_cbserparam COMSTOPBITS[]

Array of available stopbits for a serial port.

const char* DEFAULTDATABITS

Default number of databits, only informational purposes.

const char* DEFAULTPARITY

Default parity, only informational purposes.

const char* DEFAULTPORT

Default name of the com port, only informational purposes.

The value may be NULL or have an invalid port name. No checks are performed, if the port exists.

const char* DEFAULTSPEED

Default baudrate, only informational purposes.

const char* DEFAULTSTOPBITS

Default number of stopbits, only informational purposes.

const int NCOMDATABITS

Number of databit number defintions in COMDATABITS.

const int NCOMPARITIES

Number of parity definitions in COMPARITIES.

const int NCOMSPEEDS

Number of speed definition in COMSPEEDS.

const int NCOMSTOPBITS

Number of stop bit definitions in COMSTOPBITS.

---