Sensoray 2410 API User Manual

Page 37

Sensoray 24xx Programming Guide

Model 2426 Multi-Function I/O Module

7.5.3 s2426_ComportRead()

Function:

Fetch data and line state events from the comport’s serial receiver queue.

Prototype:

int s2426_ComportRead( HSESSION sess, u32 *err, void *buf, int len, BOOL wait );

Returns:

One of these values:

Notes:

This function transfers received data and line state change notifications from the comport’s serial receiver queue
into

buf[]

. If stream data was read, a positive value will be returned that indicates the number of bytes copied to

buf

. Zero will be returned if the receiver queue is empty or an error occurred. If the underlying connection was

closed, the function will return zero and

err

will be set to

ERR_CONNCLOSED

Line state change notifications indicate events that cannot be conveyed as stream data, such as parity errors and
incoming line breaks. These notifications appear in their order of occurrence in the receive stream. When this
function returns -1, event flags can be found in

buf[0]

that indicates the type of line state event (or events) that

occurred, and no other data will be copied to

buf

The comport must be attached to the specified session when this function is called. If the comport is closed, the
function will return zero and

err

will be set to

COMPORT_UNATTACHED

Example:

// Fetch and display received comport data.

char buf[256];
u32 err = ERR_NONE;

// Leave space at end of buf for string terminating NUL char.

int

nchars = s2426_ComportRead( sess, &err, buf,

sizeof

(buf)-1, FALSE )

;

( nchars > 0 ) {

buf[nchars] = 0;

// convert to C string

printf( "data received: %s\n", buf );
}

else if

( nchars < 0 ) {

printf( "linestate change(s):\n" );

( buf[0] & COMPORT_BREAK_ERROR ) printf( "receive break\n" );

( buf[0] & COMPORT_FRAMING_ERROR ) printf( "framing error\n" );

( buf[0] & COMPORT_PARITY_ERROR ) printf( "parity error\n" );

( buf[0] & COMPORT_OVERRUN_ERROR ) printf( "overrun error\n" );

}

else if

( err == ERR_NONE )

printf( "receive queue is empty\n" );

else

printf( "Error: %s\n", s24xx_ErrorText(err) );

Argument

Description

sess

Session handle obtained from

s24xx_SessionOpen()

err

Pointer to error code. See Section 4.3.1 for details.

buf

Pointer to a buffer that will receive the comport data.

len

Size of

buf

or maximum number of bytes to receive, whichever is smaller.

wait

Enable blocking operation. When True, the function will return when data is available or
upon error. When False, the function will return immediately regardless of data availability.

Return Value

Description

0 to len

Number of received comport bytes that were copied to

buf

. Zero may indicate an error.

-1

Line state change notification, with event flags stored in

buf[0]

. Up to four event flags

will be set to True to indicate the associated events were detected:

COMPORT_BREAK_ERROR

COMPORT_FRAMING_ERROR

COMPORT_PARITY_ERROR

, and

COMPORT_OVERRUN_ERROR.