serialport.h

Headers Index Help      Within this page: Functions Constants Variables

Overview

SerialPort - Java and C access to local or remote serial ports.

The SerialPort package provides a Java or C program with access to serial ports. This is the C interface module, used by a client program to access the SerialPort server, spd. It allows its caller to control the port's settings (speed, parity, etc) and to transfer data to and from a remote peer. Each open connection to a serial port has its own control block and operates independently of any other serial ports the program may be using. It uses TCP/IP to connect to spd, the server that handles serial ports on its behalf. spd is written in C. It is always run on the host which has the serial ports, but a SerialPort client can communicate with spd regardless of whether it is running on the same system or on a remote host.

All functions contain in-line code with no internal delays apart from the sp_sleep() function, which is provided as a convenient way to wait for remote activity to occur and to allow for transmission time. There are no internal delays in the serial server. The intent is to allow a client program to choose when or if it needs to wait for external events. The functions do, however, contain sufficient validation to ensure that the function should complete during normal operation.

The control block is created by calling sp_create() and finally deleted by calling sp_delete(). The latter fails if the connection to spd is still open. All other functions specify the control block as their first or only argument: its contents must not be altered except via the functions provided for that purpose. If they are called with a null pointer to the control block they will return the SPEINVPTR error.

sp_listports() establishes the connection it needs to retrieve the list of ports if one does not exist. Subsequent connection requests will use this connection. If a connection already exists the sp_open() function will re-use it. Pre-existing information in the control block, set up by sp_create(), is used to identify the hostname and port that will be used to establish a connection.

sp_open() claims the serial port to be used by the application and sp_close() releases it and closes the TCP connection to the server. A connection that has been closed can be re-opened by another call to sp_open().

Call sp_delete() to release the memory occupied by the control block. This will fail if the connection is still open.

Function definitions are included by

#include <serialport.h>
#include <environ.h>

The second include pulls in a set of general purpose utilities used to support the interface functions. The executable must be linked with libenviron.a and libsp.a.

SerialPort - serial connections for Java
Copyright (C) 2005 Martin C Gregorie

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Contact Martin Gregorie at martin@gregorie.org

The following sections describe the C interface functions which are contained in the libsp.a library module.

Functions

sp_close

#include "serialport.h"

int sp_close(SPC *cb, char *force);

Releases the serial port and closes the connection. If the force argument starts with T, t or 1 the serial port will be forced to close with possible data loss. Otherwise the serial port is not closed if there is still data in the buffers. Returns -ve on error. Errors are SPEINVPTR, SPEHOSTLOST.

In: serialport.c

sp_create

#include "serialport.h"

SPC *sp_create(int debug, char *host, int port);

Create a control block and set the debugging level, the name of the host supporting the server, spd and the port number. The connection to spd is not established until sp_open() is called. If the server is in the same system as the client, set host to "localhost". NULL is returned on failure.

The error notification function, sp_error(), cannot be used until the control block is successfully created.

In: serialport.c

sp_delay

#include "serialport.h"

int sp_delay(SPC *cb, int delay);

Sets time that spd must wait between sending characters to the serial port. The delay time is specified in mS and must be in the range 0 - 1000 mS. The receive delay time is recalculated. Returns -ve on error. Errors are SPEINVPTR, SPEHOSTLOST.

In: serialport.c

sp_delete

#include "serialport.h"

int sp_delete(SPC **cb);

Releases the control block if the connection has been closed. Otherwise it returns the SPEHOSTOPEN error. Returns -ve on error. Errors are SPEINVPTR, SPEHOSTOPEN

In: serialport.c

sp_echo

#include "serialport.h"

int sp_echo(SPC *cb,
            char *charsout,
            int outlth,
            int adj,
            char *charsin,
            int inlth);

A convenience method that calls the sp_put(), sp_sleep() and sp_get() functions. Sends outlth bytes from charsout to the port by calling sp_put(). The expected and adj arguments are passed to sp_sleep(). sp_get() is called to retrieve the available bytes and put them in charsin. A maximum of inlth bytes will be read. If a terminator is active then it will terminate the input string. sp_echo() returns the number of characters read or -ve on error. Errors are SPEINVPTR, SPEHOSTLOST.

In: serialport.c

sp_error

#include "serialport.h"

char *sp_error(SPC *cb);

Returns a pointer to the error string or "OK" if no error ocurred.

In: serialport.c

sp_get

#include "serialport.h"

int sp_get(SPC *cb, char *buff, int n);

Reads up to n characters from the port and stores them in buff. If requested by sp_setsep(), the separator character may terminate the characters read (active separator is true) and may be hidden from the caller (external separator is true).

Note: if the remote response is slower than expected an incomplete message may be returned. In this case the caller should wait for a suitable time and call sp_get() again. See the sp_sleep() function for suggestions on preventing this.

sp_get() returns the number of characters read or -ve on error. Errors are SPEINVPTR, SPEHOSTLOST.

In: serialport.c

sp_getport

#include "serialport.h"

int sp_getport(SPC *cb,
               int *baud,
               int *bits,
               char *parity,
               int *stopbits);

Gets baud rate, bits (5-8), parity (O, E, N), stopbits (1,2). If the port has not been opened successfully the returned values are meaningless. Returns -ve on error. Errors are SPEINVPTR, SPEHOSTLOST.

In: serialport.c

sp_listports

#include "serialport.h"

int sp_listports(SPC *cb, char *ports, int lth);

Returns a comma separated list of available ports as a string. lth is the maximum size of the buffer.

Returns -ve on error. Errors are SPEINVPTR, SPEHOSTBAD, SPEPORTLONG.

In: serialport.c

sp_open

#include "serialport.h"

int sp_open(SPC *cb, char *name);

Open a connection to spd and claim the serial port identified by name. Default run time conditions are set by the spd configuration file. Returns -ve on error. Errors are: SPEINVPTR, SPEHOSTBAD, SPEUNKNOWN, SPEPORTUSED.

In: serialport.c

sp_put

#include "serialport.h"

int sp_put(SPC *cb, char *buff, int n);

Sends n characters from the buffer to the port. If requested by sp_setsep(), a terminator may be appended to the byte string. Returns -ve on error. Errors are SPEINVPTR, SPEHOSTLOST.

In: serialport.c

sp_query

#include "serialport.h"

int sp_query(SPC *cb, int *incount, int *outcount, int *buffsize);

Queries the server for the numbers of bytes in the input and output buffers plus the buffer size and decodes the result. Values are returned in incount, outcount and buffsize respectively. Returns -ve on error.

In: serialport.c

sp_reset

#include "serialport.h"

int sp_reset(SPC *cb, char line_settings, char tx_delay, char separator);

Resets the line settings, tx delay and record separator to their default settinfs as required The arguments are boolean values encoded as T/F, t/f or 1/0.

• line_settings, if true, causes the baud rate, data bits, parity and stop bits to be reset to the values defined in the configuration file for this port.
• tx_delay, if true, causes the delay between sernding successive bytes to be reset to zero.
• separator, if true, causes the record separator control values to be reset to their default values: inactive separator, separator value is NULL, separator is internal to its record.

Returns -ve on error.

In: serialport.c

sp_setport

#include "serialport.h"

int sp_setport(SPC *cb,
               int baud,
               int bits,
               char parity,
               int stopbits);

Sets baud rate, bits (5-8), parity (O, E, N), stopbits (1,2). Calculates and stores the time (in mS) to read or write one character through the serial port. Returns -ve on error. Errors are SPEINVPTR, SPEHOSTLOST.

In: serialport.c

sp_setsep

#include "serialport.h"

int sp_setsep(SPC *cb, char active, char marker, char ext);

Sets the record separator and its application conditions. The arguments active and external are boolean values encoded as T/F, t/f or 1/0. active determines whether the field separator character, set by sep, is in use. If it is active sp_put() and sp_get() operate at the field level. sp_get() stops when the separator character is found and sp_put() should send one field at a time. If external is true the separator character is added during an sp_put() operation and not returned to the caller by an sp_get() operation. If external is false the caller must ensure that each string sent by sp_put() is terminated by the separator character and must expect the separator at the end of the string returned by an sp_get() operation.

The default is that active and external are false and sep is 0 (zero).

Returns -ve on error.

In: serialport.c

sp_sleep

#include "serialport.h"

int sp_sleep(SPC *cb, int expected, int adj);

Cause the calling process to sleep while the remote process generates and sends a reply.

First it queries the server for buffer content. Then it calculates the delay time needed for all waiting bytes to be sent and all expected incoming bytes to have been received. Finally it adds on adj, which is in mS.

sp_sleep() waits for the calculated time.

This is repeated until the output buffer is empty and the number of bytes in the input buffer stops changing or there are enough bytes in the buffer to match the expected number.

adj is a signed integer that is added to the calculated time. It is in mS and is intended to let the caller specify additional sleep time to make allowance for a remote process that is known to have a long response time. adj can also be used to adjust the sleep time downwards but it cannot reduce the time below zero.

Returns -ve on error.

In: serialport.c

Constants

enum errcodes  {  SPEOK = 0, SPEINVPTR,
                  SPEHOSTLOST, SPEHOSTOPEN, SPEHOSTCLOSED, SPEHOSTBAD,
                  SPEPORTCLOSED,
                  SPEPORTLONG,
                  SPEREMERR,
                  SPETIMERR,
                  SPEPARAMERR
               };

Variable type definitions

typedef struct
{
   int   debug;         /* Debugging level for the connection instance     */
   char  *host;         /* name of spd's host computer                     */
   int   port;          /* spd's listener port number                      */
   char  *errmsg;       /* Text of the last error to be reported           */
   int   connectstate;  /* OPEN if there is a connection to spd or CLOSED  */
   int   connection;    /* fd of the connection to spd                     */
   int   portstate;     /* OPEN if spd has opened a serial port or CLOSED  */  
   int   baudrate;      /* set by sp_open() and overridden by sp_setport() */
   char  parity;        /* set by sp_open() and overridden by sp_setport() */
   int   databits;      /* set by sp_open() and overridden by sp_setport() */
   int   stopbits;      /* set by sp_open() and overridden by sp_setport() */
   int   txdelay;       /* set by sp_open() and overridden by sp_setport() */
   int   rxdelay;       /* calculated by rxdelay() from baudrate..txdelay  */
   int   txbytes;       /* Bytes sent since sp_open() or last sp_sleep     */
   int   rxbytes;       /* Bytes received by last sp_get()                 */
   int   buffsize;      /* SPD buffer size (same for input and output)     */
} SPC;

Global Variable definitions

extern char *errmsg[];