Serialio
Class SerialPortLocal

java.lang.Object
  Serialio.SerialPortLocal

All Implemented Interfaces:

SerialPort

public class SerialPortLocal

extends java.lang.Object

implements SerialPort

Class for interface to serial port(s). This class allows high-performance serial port throughput as well as low-level serial port access to the serial port(s) of the computer.

Copyright (c) 1996-2006 Serialio.com, All Rights Reserved.

loads proper DLL to support Java VM and OS

Constructor uses SerialConfig object

Field Summary

protected static int	buildNum
protected ErrorStatusHandler	esh
protected static java.lang.String	jspLib
protected static boolean	jspLibLoaded
protected static int	maxBitRate
protected static Serialio.tool.SortVector	portList
protected static Serialio.tool.StringCompare	stringCompare

Fields inherited from interface Serialio.SerialPort

RXREADYCOUNT

Constructor Summary

SerialPortLocal()
Create a default SerialPort object.

SerialPortLocal(SerialConfig cfgObj)
Create a SerialPort object based on a SerialConfig object.

Method Summary

static void	addPortName(java.lang.String newName) Add port name to the list.
void	clearReadSinceRxBufCheck() Clears state of 'read since rx buffer check' flag.
void	clearSendSinceTxBufEmpty() Clears state of 'send since empty msg' flag.
void	close() Close a port object.
void	configure() Configures port with the parameters in the SerialConfig object
void	configure(SerialConfig cfgObj) Configures port with the parameters in the SerialConfig object.
protected void	finalize() Be sure that port is cleaned up before exit (in case close was not called)
int	getBitRate()
int	getBuildNum() Returns the build number of this class.
int	getByte() Get the next available byte from the receive buffer.
SerialConfig	getConfig() Gets the the SerialConfig object
int	getData(byte[] buf) Gets next available bytes from the receive buffer.
int	getData(byte[] buf, int off, int len) Gets next available bytes from the receive buffer.
int	getDataBits()
java.lang.String	getDevName() Returns the device name (OS name for port)
int	getHandshake()
static int	getInstanceLock() Get the instance lock state.
int	getLibVer() Returns the version number of the current serial port native lib (so/DLL) The most significant 16 bits contain the major version The least significant 16 bits contain the minor version
int	getMaxBitRate() Return maximum bitrate supported on the platform
java.lang.String	getName() Returns the name of this serial port object
java.lang.String	getName(int port) Returns the name of this serial port object
int	getParity()
static java.lang.String[]	getPortList() Get list of ports from OS 'registry' First we check to see if a system property SERIAL_PORT_LIST is defined.
java.lang.String	getPortName()
int	getPortNum() Returns the port number for this serial port object
static int	getPowerMode(int slotNum) Gets the port state for devices that support standby mode to save power.
static int	getResumeState(boolean clear) Gets the state of the resume flag.
static int	getStatusAPM() Gets the status of APM (advanced power management)
int	getStopBits()
int	getTimeoutRx() Returns the receive timeout interval of serial port object.
int	getTimeoutTx() Returns the receive timeout interval of serial port object.
boolean	isOpen() Indicates if port is currently open
boolean	isSupported(java.lang.String name) Check for supported feature
void	open() Open the SerialPortLocal object.
void	putByte(byte data) Send byte out the serial port.
void	putData(byte[] data) Send byte array contents to the serial port.
void	putData(byte[] data, int dLen) Deprecated. The preferred method is putData(dataBuf, off, len)
void	putData(byte[] data, int off, int dLen) Send specificed length of the byte array to the serial port.
void	putString(java.lang.String s) Send the string out the serial port.
boolean	readSinceRxBufCheck() Returns flag indicating if data was read since last receive buffer check.
void	reset() Reset a port object.
int	rxFlush() Flushes the objects receive buffer (contents are discarded)
boolean	rxOverflow() Returns true if the objects receive buffer overflowed since the last call to this method.
int	rxReadyCount() Returns number of bytes in the objects receive buffer
void	sendBreak(int bLen) Send a break signal on the line
boolean	sendSinceTxBufEmpty() Returns flag indicating if data sent since last transmit buffer check.
void	setBitRate(int value)
void	setConfig(SerialConfig serCfg) Sets the the SerialConfig object
void	setDataBits(int value)
void	setDTR(boolean onOff) Set the DTR signal of objects serial port
void	setErrorStatusHandler(ErrorStatusHandler handler) Sets the UnexpectedStatusHandler.
void	setHandshake(int value)
static int	setInstanceLock(int mode) Set the instance lock to SET or CLEAR state.
void	setName(java.lang.String spName) Sets the name of this serial port object
void	setParity(int value)
void	setPortName(java.lang.String name)
static void	setPowerMode(int slotNum, int pwrMode) Sets the port state for devices that support standby mode to save power.
void	setRTS(boolean onOff) Set the RTS signal of objects serial port.
void	setStopBits(int value)
void	setTimeoutRx(int tmoRx) Sets the receive timeout of the serial port object.
void	setTimeoutTx(int tmoTx) Sets the transmit timeout of the serial port object.
boolean	sigBreak() Returns true if the serial port for this object detected a break on the line since the last call to this method.
boolean	sigCD() Returns state of serial port CD (Carrier Detect) signal Note: This may not be supported on all platforms
boolean	sigCTS() Returns state of serial port CTS (Clear To Send) signal
boolean	sigDSR() Returns state of serial port DSR (Data Set Ready) signal
boolean	sigFrameErr() Returns true if the serial port for this object had a Framing Error since last call to this method.
boolean	sigOverrun() Returns true if the serial port UART for this object had a was Overrun since last call to this method.
boolean	sigParityErr() Returns true if the serial port for this object had a Parity Error Note: This may not be supported on all platforms since last call to this method.
boolean	sigRing() Returns true if the serial port object detects a ring signal on the line.
int	txBufCount() Returns number of bytes in the objects transmit buffer
int	txDrain() Drains the objects transmit buffer (contents are sent).
int	txFlush() Flushes the objects transmit buffer (contents are discarded)

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

buildNum

protected static int buildNum

stringCompare

protected static Serialio.tool.StringCompare stringCompare

portList

protected static Serialio.tool.SortVector portList

jspLib

protected static java.lang.String jspLib

jspLibLoaded

protected static boolean jspLibLoaded

maxBitRate

protected static int maxBitRate

esh

protected ErrorStatusHandler esh

Constructor Detail

SerialPortLocal

public SerialPortLocal()

Create a default SerialPort object. Required for well behaved bean.

SerialPortLocal

public SerialPortLocal(SerialConfig cfgObj)
                throws java.io.IOException

Create a SerialPort object based on a SerialConfig object. An attempt is made to open the port upon creation.

Parameters:

cfgObj - The serial port configuration object

Throws:

java.io.IOException - if error

Method Detail

open

public void open()
          throws java.io.IOException

Open the SerialPortLocal object.

Note: hardflow only allowed for Win95, native code uses this so we ensure it is set before calling open. If hardflow is true there must be a flowcontrol thread for it work properly. Since there is only a flow control thread on Win95, if the user forces hardflow on say WinNT, then no flow control thread is created, and flowcontrol does not work.

Check platform for undetailed error numbers (e.g. sys/errno.h)

Throws:

java.io.IOException - if error

configure

public void configure()
               throws java.io.IOException

Configures port with the parameters in the SerialConfig object

Throws:

java.io.IOException - if error

configure

public void configure(SerialConfig cfgObj)
               throws java.io.IOException

Configures port with the parameters in the SerialConfig object. See documentation for details on the SerialConfig parameters.

Specified by:

configure in interface SerialPort

Parameters:

cfgObj - The serial port configuration object

Throws:

java.io.IOException - if error

setConfig

public void setConfig(SerialConfig serCfg)

Sets the the SerialConfig object

Specified by:

setConfig in interface SerialPort

Parameters:

serCfg - The serial port configuration object

getConfig

public SerialConfig getConfig()

Gets the the SerialConfig object

Specified by:

getConfig in interface SerialPort

close

public void close()
           throws java.io.IOException

Close a port object. The port should be closed when its use is no longer required

Specified by:

close in interface SerialPort

Throws:

java.io.IOException - if error

EPOC note: be sure to close any threads that may be running on the port before closing the port. This is due to two EPOC limitations. First there can be no static data in the EPOC DLL, second only one thread can access the port on EPOC (multi-thread access is provided by facade). The close operation in the native code deletes the shared mem reference so if a 2nd thread were to be in the process of calling a method (it would fail if it had not entered the method yet as the port is marked closed at the Java level) it would cause a panic.

reset

public void reset()
           throws java.io.IOException

Reset a port object. This closes, opens, and configures the port.

Throws:

java.io.IOException - if error

putByte

public void putByte(byte data)
             throws java.io.IOException

Send byte out the serial port.

Note: This call returns when data is put in the queue or after a timeout. To wait until data is sent use txDrain, or loop on txBufCount.

Specified by:

putByte in interface SerialPort

Parameters:

data - The byte of data to output to the objects serial port

Throws:

java.io.IOException - if error

putString

public void putString(java.lang.String s)
               throws java.io.IOException

Send the string out the serial port.

Note: This call returns when data is put in the queue or after a timeout. To wait until data is sent use txDrain, or loop on txBufCount.

This will only pass UTF8 strings (i.e. 8 bit ASCII, not 16 bit UNICODE).

Specified by:

putString in interface SerialPort

Parameters:

s - The string to output to the objects serial port.

Throws:

java.io.IOException - if error

putData

public void putData(byte[] data)
             throws java.io.IOException

Send byte array contents to the serial port.

Note: This call returns when data is put in the queue, (or if the queue does not have room for the data within the specified timeout). To wait until data is sent use txDrain, or loop on txBufCount.

Specified by:

putData in interface SerialPort

Parameters:

data - The byte array of data to output to the objects serial port are not sent to the transmit buffer

Throws:

java.io.IOException - if error

putData

public void putData(byte[] data,
                    int dLen)
             throws java.io.IOException

Deprecated. The preferred method is putData(dataBuf, off, len)

Send specificed length of the byte array to the serial port. Note: This call returns when data is put in the queue or after a timeout. To wait until data is sent use txDrain, or loop on txBufCount.

Parameters:

data - The byte array of data to output to the objects serial port

dLen - The length from the beginning of the byte array that will be output to the objects serial port.

Throws:

java.io.IOException - if error

putData

public void putData(byte[] data,
                    int off,
                    int dLen)
             throws java.io.IOException

Send specificed length of the byte array to the serial port. Note: This call returns when data is put in the queue or after a timeout. To wait until data is sent use txDrain, or loop on txBufCount.

Specified by:

putData in interface SerialPort

Parameters:

data - The byte array of data to output to the objects serial port

off - The offset in the buffer where data will be sent from

dLen - The length of data that will be sent beginning at the offset

Throws:

java.io.IOException - if error

getByte

public int getByte()
            throws java.io.IOException

Get the next available byte from the receive buffer. This call returns after data has been received or after a timeout. Note: The timeout is set using setTimeoutRx, the default timeout is 0.

Specified by:

getByte in interface SerialPort

Returns:

byte or -1 if byte not available when timeout expired.

Throws:

java.io.IOException - if error

getData

public int getData(byte[] buf)
            throws java.io.IOException

Gets next available bytes from the receive buffer.

Note: If rxTimout is enabled (using setTimeoutRx), and the rxTimeout occurs before the requested number of bytes (buf.length) are available, then this method will not read any of the bytes, and the returned count value will be the number of bytes available.

Specified by:

getData in interface SerialPort

Parameters:

buf - The byte array that will contain the data read from the objects serial port.

Returns:

number of bytes transferred

Throws:

java.io.IOException - if error

getData

public int getData(byte[] buf,
                   int off,
                   int len)
            throws java.io.IOException

Gets next available bytes from the receive buffer.

Note: If rxTimout is enabled (using setTimeoutRx), and the rxTimeout occurs before the requested number of bytes (len) are available, then this method will not read any of the bytes, and the returned count value will be zero

Specified by:

getData in interface SerialPort

Parameters:

buf - the byte array buffer where data will be put when read

off - the offset in the buffer where data will be put

len - the length of data requested to be put in the buffer

Returns:

the total number of bytes read into the buffer

Throws:

java.io.IOException - if an error occurs.

rxFlush

public int rxFlush()
            throws java.io.IOException

Flushes the objects receive buffer (contents are discarded)

Specified by:

rxFlush in interface SerialPort

Throws:

java.io.IOException - if port not open

txFlush

public int txFlush()
            throws java.io.IOException

Flushes the objects transmit buffer (contents are discarded)

Specified by:

txFlush in interface SerialPort

Throws:

java.io.IOException - if port not open

txDrain

public int txDrain()
            throws java.io.IOException

Drains the objects transmit buffer (contents are sent).
Note: If handshake/flowcontrol has sending disabled, this method may wait indefinitely.

Specified by:

txDrain in interface SerialPort

Throws:

java.io.IOException - if port not open

rxReadyCount

public int rxReadyCount()
                 throws java.io.IOException

Returns number of bytes in the objects receive buffer

Specified by:

rxReadyCount in interface SerialPort

Throws:

java.io.IOException - if error

txBufCount

public int txBufCount()
               throws java.io.IOException

Returns number of bytes in the objects transmit buffer

Specified by:

txBufCount in interface SerialPort

Throws:

java.io.IOException - if error

Note: This may not be supported on all platforms. On some platforms This method is 'boolean' (returns 1 when there are bytes in the transmit queue, and 0 when the queue is empty) on some platforms (e.g. Mac,OS/2)

clearReadSinceRxBufCheck

public void clearReadSinceRxBufCheck()

Clears state of 'read since rx buffer check' flag. This is used mainly for implementation of the javax.comm.SerialPort API.

sendSinceTxBufEmpty

public boolean sendSinceTxBufEmpty()

Returns flag indicating if data sent since last transmit buffer check. This is used mainly for implementation of the javax.comm.SerialPort API.

clearSendSinceTxBufEmpty

public void clearSendSinceTxBufEmpty()

Clears state of 'send since empty msg' flag. This is used mainly for implementation of the javax.comm.SerialPort API.

Note: because the javax.comm.SerialPort SerialPortEventTask thread runs separate from the transmit thread that uses SerialPortLocal, it is entirely possible, that the transmit buffer could have data in it when the OUTPUT_BUFFER_EMPTY is processed. This could occur when multiple threads send data to the output. We would never expect that this would cause a problem in properly written code. This caveat is listed mainly for the purpose of debug information for the developer.

readSinceRxBufCheck

public boolean readSinceRxBufCheck()

Returns flag indicating if data was read since last receive buffer check. This is used mainly for implementation of the javax.comm.SerialPort API.

rxOverflow

public boolean rxOverflow()
                   throws java.io.IOException

Returns true if the objects receive buffer overflowed since the last call to this method.

Note: This may not be supported on all platforms

Specified by:

rxOverflow in interface SerialPort

Throws:

java.io.IOException - if error

sigDSR

public boolean sigDSR()
               throws java.io.IOException

Returns state of serial port DSR (Data Set Ready) signal

Specified by:

sigDSR in interface SerialPort

Throws:

java.io.IOException - if error

sigCTS

public boolean sigCTS()
               throws java.io.IOException

Returns state of serial port CTS (Clear To Send) signal

Specified by:

sigCTS in interface SerialPort

Throws:

java.io.IOException - if error

sigCD

public boolean sigCD()
              throws java.io.IOException

Returns state of serial port CD (Carrier Detect) signal

Note: This may not be supported on all platforms

Specified by:

sigCD in interface SerialPort

Throws:

java.io.IOException - if error

sigFrameErr

public boolean sigFrameErr()
                    throws java.io.IOException

Returns true if the serial port for this object had a Framing Error since last call to this method.

Note: This may not be supported on all platforms

Specified by:

sigFrameErr in interface SerialPort

Throws:

java.io.IOException - if error

sigOverrun

public boolean sigOverrun()
                   throws java.io.IOException

Returns true if the serial port UART for this object had a was Overrun since last call to this method.

Note: This may not be supported on all platforms

Specified by:

sigOverrun in interface SerialPort

Throws:

java.io.IOException - if error

sigParityErr

public boolean sigParityErr()
                     throws java.io.IOException

Returns true if the serial port for this object had a Parity Error

Note: This may not be supported on all platforms

since last call to this method.

Specified by:

sigParityErr in interface SerialPort

Throws:

java.io.IOException - if error

sigRing

public boolean sigRing()
                throws java.io.IOException

Returns true if the serial port object detects a ring signal on the line.

Specified by:

sigRing in interface SerialPort

Throws:

java.io.IOException - if error Note: This may not be supported on all platforms

sigBreak

public boolean sigBreak()
                 throws java.io.IOException

Returns true if the serial port for this object detected a break on the line since the last call to this method.

Note: This may not be supported on all platforms

Specified by:

sigBreak in interface SerialPort

Throws:

java.io.IOException - if error

setDTR

public void setDTR(boolean onOff)
            throws java.io.IOException

Set the DTR signal of objects serial port

Specified by:

setDTR in interface SerialPort

Parameters:

onOff - The state that the objects DTR line will be set to.

Throws:

java.io.IOException - if error

setRTS

public void setRTS(boolean onOff)
            throws java.io.IOException

Set the RTS signal of objects serial port.

Note: This is not be supported on all platforms, e.g. a MAC does not have an RTS hardware

Specified by:

setRTS in interface SerialPort

Parameters:

onOff - The state that the objects RTS line will be set to.

Throws:

java.io.IOException - if error Note: This may not be supported on all platforms

sendBreak

public void sendBreak(int bLen)
               throws java.io.IOException

Send a break signal on the line

Specified by:

sendBreak in interface SerialPort

Parameters:

bLen - The number of milliseconds for the break signal.

Throws:

java.io.IOException - if error

getTimeoutRx

public int getTimeoutRx()
                 throws java.io.IOException

Returns the receive timeout interval of serial port object.

Specified by:

getTimeoutRx in interface SerialPort

Throws:

java.io.IOException - if error

getTimeoutTx

public int getTimeoutTx()
                 throws java.io.IOException

Returns the receive timeout interval of serial port object.

Specified by:

getTimeoutTx in interface SerialPort

Throws:

java.io.IOException - if error

setTimeoutRx

public void setTimeoutRx(int tmoRx)
                  throws java.io.IOException

Sets the receive timeout of the serial port object.

Receive functions return after this amount of time if requested amount of data has not been received

Specified by:

setTimeoutRx in interface SerialPort

Parameters:

tmoRx - The number of milliseconds for the timeout.

Throws:

java.io.IOException - if error

setTimeoutTx

public void setTimeoutTx(int tmoTx)
                  throws java.io.IOException

Sets the transmit timeout of the serial port object. Transmit functions return after this amount of time if all data has not been sent.

Specified by:

setTimeoutTx in interface SerialPort

Parameters:

tmoTx - The number of milliseconds for the timeout.

Throws:

java.io.IOException - if error

setErrorStatusHandler

public void setErrorStatusHandler(ErrorStatusHandler handler)

Sets the UnexpectedStatusHandler. When UnexpectedStatusHandling is enabled, this method is called instead of throwing an IOException. The purpose for this is to allow applications to handle error values in cases where desired. e.g. when it expects an 'unexpected' port closure, e.g. due to a CF card being unexpectedly removed from a PDA. Setting this handler enables special handling. Currently only one handler is allowed. Caveat: Be sure you understand the ramifications

Throws:

java.io.IOException - if error

setPowerMode

public static void setPowerMode(int slotNum,
                                int pwrMode)
                         throws java.io.IOException

Sets the port state for devices that support standby mode to save power. If the device does not support standby mode, this method does nothing. Caveat: all ports on card should be closed before a suspend

Parameters:

slotNum - The card slot number (e.g. 0 for CF slot on Zaurus)

pwrMode - The power mode

Throws:

java.io.IOException - if error

getPowerMode

public static int getPowerMode(int slotNum)
                        throws java.io.IOException

Gets the port state for devices that support standby mode to save power. If the device does not support standby mode, this method does nothing.

Parameters:

slotNum - The card slot number (e.g. 0 for CF slot on Zaurus)

Returns:

returns card state 0=Suspended, 1=Active, or -1 if not supported

Throws:

java.io.IOException - if error

getResumeState

public static int getResumeState(boolean clear)

Gets the state of the resume flag. This flag is starts at 0 and gets set when the computer performs a resume following a suspend, or power off.

Parameters:

clear - Set true to clear the flag following the read.

Returns:

Returns state of resume flag. 0=not resumed, 1=resumed, or -1 if not supported

getStatusAPM

public static int getStatusAPM()

Gets the status of APM (advanced power management)

Returns:

returns card status Status can be decoded as follows int bExist = (bStat & 0x00000080) >> 7; int bPerLevel = bStat & 0x0000007f; int bLevel = (bStat & 0x0000ff00) >> 8; int bExtPwr = (bStat & 0x00010000) >> 16; WinCE note: At least through version 3.0.11171 (Build 11178) WinCE values for 'bLevel' or 'bPerLevel' should be ignored when bExtPwr is set.

Throws:

java.io.IOException - if error

getPortNum

public int getPortNum()

Returns the port number for this serial port object

Specified by:

getPortNum in interface SerialPort

setName

public void setName(java.lang.String spName)

Sets the name of this serial port object

Specified by:

setName in interface SerialPort

getName

public java.lang.String getName()

Returns the name of this serial port object

Specified by:

getName in interface SerialPort

getDevName

public java.lang.String getDevName()

Returns the device name (OS name for port)

getName

public java.lang.String getName(int port)

Returns the name of this serial port object

getBuildNum

public int getBuildNum()

Returns the build number of this class. The higher the build number, the more recent the class.

Returns:

the build number

getLibVer

public int getLibVer()

Returns the version number of the current serial port native lib (so/DLL)

The most significant 16 bits contain the major version

The least significant 16 bits contain the minor version

Specified by:

getLibVer in interface SerialPort

Returns:

the native library version number

setInstanceLock

public static int setInstanceLock(int mode)

Set the instance lock to SET or CLEAR state.

Parameters:

mode - 1=SET, 0=CLEAR

Returns:

0 on success or when or -1 on error. If method called with mode=SET, and lock is set, an error occurs. The InstanceLock methods are valuable for preventing multiple program instances on devices such as PDAs. Currently the lock is provided by the creation of a file. If the lock is not cleared before the program exits, it will need to be removed by hand, or the program can offer an option to remove it.

getInstanceLock

public static int getInstanceLock()

Get the instance lock state.

Returns:

0 if there is an instance lock active.

isOpen

public boolean isOpen()

Indicates if port is currently open

getMaxBitRate

public int getMaxBitRate()

Return maximum bitrate supported on the platform

isSupported

public boolean isSupported(java.lang.String name)

Check for supported feature

Specified by:

isSupported in interface SerialPort

getPortList

public static java.lang.String[] getPortList()
                                      throws java.io.IOException

Get list of ports from OS 'registry'

First we check to see if a system property SERIAL_PORT_LIST is defined. If so, we use the values in it as the port list. The property should contain a semi-colon or colon delimited list of port names, eg. SERIAL_PORT_LIST=COM1;COM2;COM3 SERIAL_PORT_LIST=/dev/ttyS0:/dev/ttyS1 Only when this property is undefined do we attempt to determine the list ourselves. This feature provides the option of avoiding native calls for port discovery.

Note: serial port device names must be 4 or more characters.

This feature can be involked via the command line, for example java -DSERIAL_PORT_LIST=COM1;COM2;COM3 classname

Throws:

java.io.IOException

addPortName

public static void addPortName(java.lang.String newName)

Add port name to the list.

finalize

protected void finalize()

Be sure that port is cleaned up before exit (in case close was not called)

setPortName

public void setPortName(java.lang.String name)

getPortName

public java.lang.String getPortName()

setBitRate

public void setBitRate(int value)

getBitRate

public int getBitRate()

setDataBits

public void setDataBits(int value)

getDataBits

public int getDataBits()

setStopBits

public void setStopBits(int value)

getStopBits

public int getStopBits()

setParity

public void setParity(int value)

getParity

public int getParity()

setHandshake

public void setHandshake(int value)

getHandshake

public int getHandshake()