spd.h

Headers Index Help      Within this page: Functions Constants Variables

Overview

spd, the SerialPort server.

spd provides remote access to serial ports for client processes using the Java SerialPort interface class or the libsp.a C interface library. See the spd manpage for more details.

• Written by M.C.Gregorie.
• Version history
• 1.0, Pre-release version 27/09/03
• 1.1, Asynchronous serial port handling implemented 09/03/05
• 1.2, Loopback testing facility added 24/12/05
• 1.3, Can be run as a daemon 07/02/06

The remainder of this page documents the internal functions declared in this header file.

SerialPort - serial connections for Java
Copyright (C) 2005,2006 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

Functions

accept_connection

#include "spd.h"

int accept_connection(FDL *pl, int caught_fd, int debug);

Accept an incoming connection request. set up a socket and add it to the poll list. Create a session control block for the connection.

In: spd.c

handle_event

#include "spd.h"

int handle_event(FDL *pl,
                 int caught_fd,
                 int *connect_count,
                 int port_count,
                 int debug);

Decide what event happened to a polled file and deal with it appropriately. Polled files include all open TCP/IP connections and any open serial port: both cause POLLIN events whenever data is available to be read. Serial ports will also generate POLLOUT events whenever there is data waiting to be sent. Outbound polling is not used for TCP/IP connections.

Note: if a serial port has been configured as a filestore file for development testing, it may generate a continuous stream of POLLIN events even after EOF has been reached and without any data being available. handle_event() will handle these events correctly. This is the case under Linux kernel 2.4 and may possibly happen with later kernels as well. No attempt is made to turn off POLLIN events because a serial port does not exhibit this behavior.

In: spd.c

main

#include "spd.h"

int main(int argc, char *argv[]);

This function contains the essential outline of the program. It directly controls the following actions, handing off all the detailed processing to other functions apart from running the main polling loop:

• parsing and processing the the command line arguments
• reading configuration file and setting up the serial port control blocks
• creating the listener socket
• setting up polling
• executing the main polling loop until the program is stopped by a command from spc or a kill signal is received.
• finally, tidying up by closing all connections and terminating.

In: spd.c

port_check

#include "spd.h"

char *port_check(int i);

Sanity-check port parameters. i is the index returned by port_find(). It returns NULL if no problems were found and a string describing the problem if an error was encountered.

In: port.c

port_close

#include "spd.h"

int port_close(int i, int force);

Close the serial port. i is the index returned by port_find(). If force is TRUE the port always closes. If force is FALSE it only closes if the buffers are empty. The serial port has the settings that were saved by port_open() restored before it is closed. The function returns i on success and a negative number if the port was not closed.

In: port.c

port_config

#include "spd.h"

int port_config(char *prog, char *file, int dbg);

Create serial port definitions from the configuration file. It is passed the name of the configuration file as file. prog is used in error messages. dbg sets the debugging level.

The serial port definitions and all associated data for each port is maintained in a private structure that can only be accessed via the port_xxx() functions.

It returns the number of port definitions found in the configuration file.

In: port.c

port_find

#include "spd.h"

int port_find(char *key);

Return the index to a serial port definition or an error. key contains the name of the port.

In: port.c

port_getbuffsize

#include "spd.h"

int port_getbuffsize(int portref);

Return the size of the port's output buffer: this is the same size as the input buffer. portref is the index returned by port_find().

In: port.c

port_getcount

#include "spd.h"

int port_getcount();

Return the number of serial port definitions.

In: port.c

port_geterr

#include "spd.h"

char *port_geterr();

Retrieve a string containing the last error that ocurred on any serial port. The error details are held globally, so errors must be checked for and retrieved after every port_xxx() call.

In: port.c

port_getfd

#include "spd.h"

int port_getfd(int portref);

Return the serial port's fd. portref is the index returned by port_find().

In: port.c

port_getincount

#include "spd.h"

int port_getincount(int portref);

Return the number of bytes in the port's input buffer. portref is the index returned by port_find().

In: port.c

port_getoutcount

#include "spd.h"

int port_getoutcount(int portref);

Return the number of bytes in the port's output buffer. portref is the index returned by port_find().

In: port.c

port_open

#include "spd.h"

int port_open(int i);

Open the serial port. i is the index returned by port_find(). The input and output buffers are cleared, the port is opened and its speed, parity, etc. are set to the defaults in the configuration file after saving the original values. It returns the subscript to the port array or a negative value if the port could not be opened and configured.

In: port.c

port_params

#include "spd.h"

char *port_params(i);

Return a string containing the serial port parameters. It is identical with the input string for port_set_parameters() (baud,databits,parity,stopbits,transmit delay). i is the index returned by port_find().

In: port.c

port_read

#include "spd.h"

int port_read(int f, char *buff, int bufflth);

Reads up to bufflth bytes into buff from the serial port's input buffer. f is the index returned by port_find(). It returns a count of the bytes read or -1 on error.

In: port.c

port_read_one

#include "spd.h"

int port_read_one(int f);

Read the next byte from the serial port and store it in the input buffer. f is the index returned by port_find(). This function is called asynchronously by the polling system when a POLLIN event is generated by the serial port. It returns the count of bytes just read, -1 if a fatal error ocurred or -2 if there is no space in the input buffer and in consequence the byte wasn't read.

In: port.c

port_reset

#include "spd.h"

void port_reset(int i, char *line);

Reset the line settings, tx delay and record separator controls the their default conditions. i is the index returned by port_find(). The three values are the first three bytes in line. These are:

1. the line settings flag. Set on for values t,T or 1 and off for f,F or 0. If on, the line settings (baud rate, data bits, parity and stop bits are reset to the values defined in the configuration file for this port.
2. the tx delay flag. Set on for values t,T or 1 and off for f,F or 0. If on, the transmission delay is reset to zero delay.
3. the record separator flag. Set on for values t,T or 1 and off for f,F or 0. If on, the record separator control values are reset to the defaults: separator inactive, separator character is null, separator is internal.

In: port.c

port_selection

#include "spd.h"

char *port_selection();

Return a string containing a comma delimited list of the names of available serial ports.

In: port.c

port_set_delay

#include "spd.h"

void port_set_delay(int i, char *line);

Set up the delay between writing characters to the serial port. i is the index returned by port_find(). line is the delay (in mS) as a character string. After decoding, the delay is checked for validity and, if it passes this check, it is applied to the serial port. If the check fails the global error flag is set.

In: port.c

port_set_parameters

#include "spd.h"

void port_set_parameters(int i, char *line);

Set up baud rate, databits, parity and stopbits for the serial port. i is the index returned by port_find(). line is a comma separated list of settings in the format:

baudrate,databits(5-8),parity(O,E,N),stopbits(1,2)

After decoding, the settings are checked for validity and, if they pass this check, they are applied to the serial port. If the check fails the global error flag is set.

In: port.c

port_set_separator

#include "spd.h"

void port_set_separator(int i, char *line);

Set up record separator and conditions. i is the index returned by port_find(). The three values are the first three bytes in line. These are:

1. the active flag. Set on for values t,T or 1 and off for f,F or 0.
2. The character that is to act as the field separator.
3. the external separator flag. Set on for values t,T or 1 and off for f,F or 0.

In: port.c

port_status

#include "spd.h"

char *port_status(int i);

Return a serial port's current settings as a formatted, displayable string. i is the index returned by port_find().

In: port.c

port_write

#include "spd.h"

int port_write(int f, char *value, int valuelth);

Write to the serial port's output buffer. f is the index returned by port_find().

If the port type is port or file then this function adds valuelth bytes from value to the port's output buffer from where port_write_one(), which is called by the polling mechanism, extracts bytes and writes them to the serial port.

If the port type is loopback then this function adds valuelth bytes from value to the port's input buffer. The effect is the same as if the data had been sent via a serial port with a loopback cable connected to it.

It returns the number of bytes written or -1 on error.

In: port.c

port_write_one

#include "spd.h"

int port_write_one(int f);

Extract a byte from the output buffer and write it to the serial port. f is the index returned by port_find(). This function is called by the polling routines when there is data to be written and the serial port has generated a POLLOUT event. It returns the number of bytes written, zero if there was nothing to write or -1 on error.

In: port.c

readargs

#include "spd.h"

int readargs(int argc, char *argv[], int flags[], char **pipe);

This function scans the command line for options and does all the associated setup.

In: spd.c

respond_to_input

#include "spd.h"

int respond_to_input(FDL *pl,
                     int fd,
                     int sd,
                     int *connected,
                     int port_count,
                     int debug);

Take the actions needed to receive and respond to a message.

Incoming commands are read from the connection and passed to spd_cmd_handler, which takes the appropriate action and returns a response, which this function sends back to the command's originator. It also handles zero length messages: these indicate that the client has closed the connection.

It returns FALSE if a command was received to stop the server and TRUE otherwise. On return connected is TRUE if the connection is still live and FALSE otherwise.

In: spd.c

session_create

#include "spd.h"

int session_create(int sd, int s_type);

Create a new session control block. sd is the required session identifier and must not exist. If it does exist the program will abandon with an error message because this can only happen as the result of a programming error.

At this release the session identifier is the same as the session control block's index and is typically the same as the associated connection or serial port's fd. In a Linux/UNIX system these are unique within a process so this scheme will not generate conflicts.

s_type is the session type, which must be TCP_SESSION if the session is associated with a TCP/IP connection or PORT_SESSION if it is associated with a serial port. The function returns the session identifier.

In: session.c

session_delete

#include "spd.h"

void session_delete(int sd);

Destroy a session control block. sd is the session identifier of the block that will be destroyed.

In: session.c

session_find

#include "spd.h"

int session_find(int sd);

Find a session control block. sd is checked to determine that it is valid and returned to the caller.

In: session.c

session_get_ref

#include "spd.h"

int session_get_ref(int sd);

Retrieve the ref field from the session control block identified by sd.

In: session.c

session_has_ref

#include "spd.h"

int session_has_ref(int sd);

Retrieve the has_ref flag from the session control block identified by sd. This function returns TRUE or FALSE. The preferred way of retrieving the reference from a session control block is:

   if (session_has_ref(sd))
   {
      psref = session_get_ref(sd);
      .....
   }
   

In: session.c

session_init

#include "spd.h"

void session_init(int n, int dbg);

Initialise session storage structures. n is the number of serial ports configured in the spd configuration file. dbg sets the debugging level for all the session_xxx() functions. If the debugging level is 1 or more it merely traces session_xxx() function calls as an aid to debugging the calling program.

In: session.c

session_set_ref

#include "spd.h"

void session_set_ref(int sd, int ref, int has_ref);

Change the settings of ref and has_ref in the session control block identified by sd.

A TCP_SESSION control block's ref field points to a PORT_SESSION control block if it has an open serial port and has_ref is true.

A PORT_SESSION control block's ref field points to the port control block (managed by the port_xxx() functions and has_ref is true.

If has_ref is false the contents of ref are undefined.

In: session.c

session_type

#include "spd.h"

int session_type(int sd);

Return the session type from the session control block identified by sd.

In: session.c

showhelp

#include "spd.h"

void showhelp();

Display a summary of the program's operation in response to the -? command line option.

In: spd.c

spd_cmd_handler

#include "spd.h"

int spd_cmd_handler(FDL *pl,
                    int fd,
                    int sd,
                    void *input,
                    int inputlth,
                    void *output,
                    int outputlth,
                    int debug);

This module contains message handling code for spd, the serial port server. These functions analyse and execute commands received from client processes via the libsp.a C interface library or the SerialPort Java interface class. The function returns the length of the response message or a negated response length if the server is to shut down.

This is the only externally referenced function in this module.

In: spd_cmd_handler.c

spd_errlth

#include "spd.h"

int spd_errlth(int e);

Return the length of the text associated with the error code e. This is needed to complete an error response message: see spd_errmsg() for more details.

In: spd_error.c

spd_errmsg

#include "spd.h"

char *spd_errmsg(int e);

Return the text for the error code e. This becomes the value field when a request is rejected by the SerialPort server, spd. The messages are held in an internal database in this module.

In: spd_error.c

Constants

#define BADMARK         '!'

#define CMDBUFF         10

#define CONFIG_FILE     "spd.conf"

#define DAEMON          2

#define DEBUG           1

#define DEFPORT         16001

#define DEFTIMEOUT      2000

#define FALSE           0

#define FLAGCNT         4

#define HELP            0

#define MAYBEMARK       '%'

#define MUST_EXIST      1

#define MUST_NOT_EXIST  0

#define OK              ' '

#define OPTLIST         "?dDp:"

#define PORT            3

#define PORT_SESSION    2

#define SPEBADCMD       -10

#define SPEDEFAULT      0

#define SPEINACTIVE     -9

#define SPEINVBAUD      -1

#define SPEINVCOMB      -3

#define SPEINVDBITS     -2

#define SPEINVPARITY    -4

#define SPEINVPORT      -8

#define SPEINVSBITS     -5

#define SPEPORTCLOSED   -7

#define SPEPORTUSED     -6

#define TCPBUFF         1500

#define TCP_SESSION     1

#define TRUE            1

Public variables were not declared.
Return to the top