IOSerial interface

Detailed Description

The IOSerial interface captures the capabilities of a typical serial port (UART, USART, RS-232).

Enumerations
enum	IOSERIAL_NumberOfDataBits {   IOSERIAL_DATABITS_8, IOSERIAL_DATABITS_5, IOSERIAL_DATABITS_6, IOSERIAL_DATABITS_7,   IOSERIAL_DATABITS_9 }
enum	IOSERIAL_Parity {   IOSERIAL_PARITY_NONE, IOSERIAL_PARITY_ODD, IOSERIAL_PARITY_EVEN, IOSERIAL_PARITY_MARK,   IOSERIAL_PARITY_SPACE }
enum	IOSERIAL_NumberOfStopBits { IOSERIAL_STOPBITS_1, IOSERIAL_STOPBITS_1_5, IOSERIAL_STOPBITS_2 }
enum	IOSERIAL_Handshaking { IOSERIAL_HANDSHAKING_NONE, IOSERIAL_HANDSHAKING_RTS_CTS }

Functions
unsigned int	IOSERIAL_Enumerate (void)
const char *	IOSERIAL_GetEnumeratedDeviceName (unsigned int index)
IODevice	IOSERIAL_Create (const char *name)
void	IOSERIAL_Destroy (IODevice serial)
HALRESULT	IOSERIAL_SetBaudrate (IODevice serial, uint32_t baudrate)
uint32_t	IOSERIAL_GetBaudrate (IODevice serial)
HALRESULT	IOSERIAL_SetFrameFormat (IODevice serial, IOSERIAL_NumberOfDataBits data_bits, IOSERIAL_Parity parity, IOSERIAL_NumberOfStopBits stop)
HALRESULT	IOSERIAL_GetFrameFormat (IODevice serial, IOSERIAL_NumberOfDataBits *data_bits, IOSERIAL_Parity *parity, IOSERIAL_NumberOfStopBits *stop)
HALRESULT	IOSERIAL_SetHandshaking (IODevice serial, IOSERIAL_Handshaking handshaking)
IOSERIAL_Handshaking	IOSERIAL_GetHandshaking (IODevice serial)
HALRESULT	IOSERIAL_EnableRTS (IODevice serial)
HALRESULT	IOSERIAL_DisableRTS (IODevice serial)
HALRESULT	IOSERIAL_SetRTS (IODevice serial, bool rts)
bool	IOSERIAL_GetRTS (IODevice serial)
HALRESULT	IOSERIAL_EnableCTS (IODevice serial)
HALRESULT	IOSERIAL_DisableCTS (IODevice serial)
HALRESULT	IOSERIAL_SetCTS (IODevice serial, bool cts)
bool	IOSERIAL_GetCTS (IODevice serial)

Enumeration Type Documentation

enum IOSERIAL_NumberOfDataBits

Possible settings for the number of data bits in a serial frame.

Enumerator
IOSERIAL_DATABITS_8	8 data bits (default)
IOSERIAL_DATABITS_5	5 data bits
IOSERIAL_DATABITS_6	6 data bits
IOSERIAL_DATABITS_7	7 data bits
IOSERIAL_DATABITS_9	9 data bits

enum IOSERIAL_Parity

Possible settings for the parity bit mode in a serial frame.

Enumerator
IOSERIAL_PARITY_NONE	no parity
IOSERIAL_PARITY_ODD	odd parity
IOSERIAL_PARITY_EVEN	even parity
IOSERIAL_PARITY_MARK	mark parity
IOSERIAL_PARITY_SPACE	space parity

enum IOSERIAL_NumberOfStopBits

Possible number of stop bits in a serial frame.

Enumerator
IOSERIAL_STOPBITS_1	1 stop bit
IOSERIAL_STOPBITS_1_5	1.5 stop bits
IOSERIAL_STOPBITS_2	2 stop bits

enum IOSERIAL_Handshaking

Possible handshaking modes used by the serial device.

Enumerator
IOSERIAL_HANDSHAKING_NONE	Handshaking disabled.

Function Documentation

unsigned int IOSERIAL_Enumerate

(

void

)

Enumerates available serial ports. The names of the enumerated devices are available through subsequent calls to IOSERIAL_GetEnumeratedDeviceName.

Returns

number of enumerated serial ports

const char* IOSERIAL_GetEnumeratedDeviceName

(

unsigned int

index

)

Gets the name of an enumerated serial device under given index. This name can be used to create a new IOSerialDevice using IOSERIAL_Create. This function shall be called after IOSERIAL_Enumerate to retrieve the results.

Parameters

index

enumeration index (0-based)

Returns

name of the device under given index.

IODevice IOSERIAL_Create

(

const char *

name

)

Creates a new IOSerialDevice based on it's system name.

This utility function returns an IOSerialDevice handle of a device, given it's system name. It is targeted mainly at host operating systems, where devices are identified by their names rather than hardware identifiers (as is the case of bare metal applications). The returned IOSerialDevice is uninitialized. Systems that do not support device names will always return NULL.

Parameters

name	device system name (in ex. "COM3" or "\dev\ttyS0")

Returns

IOSerialDevice handle or NULL if the device could not been created

void IOSERIAL_Destroy

(

IODevice

serial

)

Destroys an IOSerialDevice previously returned by the IOSERIAL_Create function. The device should be deinitialized (IODEV_Deinit) prior to being destroyed, otherwise some resources may not be freed or other error might occur.

Parameters

serial

handle of the IOSerialDevice, returned by IOSERIAL_Create

HALRESULT IOSERIAL_SetBaudrate	(	IODevice	serial,
		uint32_t	baudrate
	)

Sets baudrate of an IOSerialDevice

Parameters

serial	IOSerialDevice
baudrate	baudrate

Returns

HALRESULT_OK on success. Other values indicate error (see HALRESULT).

References DIAG_DEFAULT_CHANNEL.

uint32_t IOSERIAL_GetBaudrate

(

IODevice

serial

)

Gets the baudrate currently set for the given IOSerialDevice

Parameters

serial

IOSerialDevice

Returns

currently set baudrate or 0 if the baudrate could not be determined.

References DIAG_DEFAULT_CHANNEL.

HALRESULT IOSERIAL_SetFrameFormat	(	IODevice	serial,
		IOSERIAL_NumberOfDataBits	data_bits,
		IOSERIAL_Parity	parity,
		IOSERIAL_NumberOfStopBits	stop
	)

Sets the frame format for the given IOSerialDevice

Parameters

serial	IOSerialDevice
data_bits	number of data bits in a frame (see IOSERIAL_NumberOfDataBits)
parity	parity bit mode (see IOSERIAL_Parity)
stop	number of stop bits (see IOSERIAL_NumberOfStopBits)

Returns

HALRESULT_OK on success. Other values indicate error (see HALRESULT).

References DIAG_DEFAULT_CHANNEL.

HALRESULT IOSERIAL_GetFrameFormat	(	IODevice	serial,
		IOSERIAL_NumberOfDataBits *	data_bits,
		IOSERIAL_Parity *	parity,
		IOSERIAL_NumberOfStopBits *	stop
	)

Gets the frame format currently set for a given IOSerialDevice.

Parameters

serial	IOSerialDevice
data_bits	pointer to a variable where number of data bits in a frame will be stored (see IOSERIAL_NumberOfDataBits)
parity	pointer to a variable where parity bit mode will be stored (see IOSERIAL_Parity)
stop	pointer to a variable where number of stop bits will be stored (see IOSERIAL_NumberOfStopBits)

Returns

HALRESULT_OK on success. Other values indicate error (see HALRESULT).

References DIAG_DEFAULT_CHANNEL.

HALRESULT IOSERIAL_SetHandshaking	(	IODevice	serial,
		IOSERIAL_Handshaking	handshaking
	)

Sets handshaking mode for a given IOSerialDevice

Parameters

serial	IOSerialDevice
handshaking	handshaking mode (see IOSERIAL_Handshaking)

Returns

HALRESULT_OK on success. Other values indicate error (see HALRESULT).

References DIAG_DEFAULT_CHANNEL.

IOSERIAL_Handshaking IOSERIAL_GetHandshaking

(

IODevice

serial

)

Gets handshaking mode currently set for a given IOSerialDevice

Parameters

serial

IOSerialDevice

Returns

handshaking mode (see IOSERIAL_Handshaking). In case the handshaking mode can not be retireved returns IOSERIAL_HANDSHAKING_NONE.

References DIAG_DEFAULT_CHANNEL, and IOSERIAL_HANDSHAKING_NONE.

HALRESULT IOSERIAL_EnableRTS

(

IODevice

serial

)

Enables the RTS (request to send) signal in a given IOSerialDevice.

Parameters

serial

IOSerialDevice

Returns

HALRESULT_OK on success. Other values indicate error (see HALRESULT).

References DIAG_DEFAULT_CHANNEL.

HALRESULT IOSERIAL_DisableRTS

(

IODevice

serial

)

Disables the RTS (request to send) signal in a given IOSerialDevice.

Parameters

serial

IOSerialDevice

Returns

HALRESULT_OK on success. Other values indicate error (see HALRESULT).

References DIAG_DEFAULT_CHANNEL.

HALRESULT IOSERIAL_SetRTS	(	IODevice	serial,
		bool	rts
	)

Sets the RTS (request to send) signal in a given IOSerialDevice.

Parameters

serial	IOSerialDevice
rts	RTS signal value (true means RTS is active, false means the RTS is inactive)

Returns

HALRESULT_OK on success. Other values indicate error (see HALRESULT).

References DIAG_DEFAULT_CHANNEL.

bool IOSERIAL_GetRTS

(

IODevice

serial

)

Gets the RTS (request to send) signal value in a given IOSerialDevice.

Parameters

serial

IOSerialDevice

Returns

rts RTS signal value (true means RTS is active, false means the RTS is inactive). If the RTS signal value could not be read this function returns false.

References DIAG_DEFAULT_CHANNEL.

HALRESULT IOSERIAL_EnableCTS

(

IODevice

serial

)

Enables the CTS (clear to send) signal in a given IOSerialDevice.

Parameters

serial

IOSerialDevice

Returns

HALRESULT_OK on success. Other values indicate error (see HALRESULT).

References DIAG_DEFAULT_CHANNEL.

HALRESULT IOSERIAL_DisableCTS

(

IODevice

serial

)

Disables the CTS (clear to send) signal in a given IOSerialDevice.

Parameters

serial

IOSerialDevice

Returns

HALRESULT_OK on success. Other values indicate error (see HALRESULT).

References DIAG_DEFAULT_CHANNEL.

HALRESULT IOSERIAL_SetCTS	(	IODevice	serial,
		bool	cts
	)

Sets the CTS (clear to send) signal in a given IOSerialDevice.

Parameters

serial	IOSerialDevice
cts	CTS signal value (true means CTS is active, false means the CTS is inactive)

Returns

HALRESULT_OK on success. Other values indicate error (see HALRESULT).

References DIAG_DEFAULT_CHANNEL.

bool IOSERIAL_GetCTS

(

IODevice

serial

)

Gets the CTS (clear to send) signal value in a given IOSerialDevice.

Parameters

serial

IOSerialDevice

Returns

rts CTS signal value (true means CTS is active, false means the CTS is inactive). If the CTS signal value could not be read this function returns false.

References DIAG_DEFAULT_CHANNEL.