SMSLib 3.5.3

org.smslib.helper
Class SerialPort

java.lang.Object
  extended by org.smslib.helper.SerialPort

public class SerialPort
extends java.lang.Object

An RS-232 serial communications port.

Please note: This is a wrapper around javax.comm.SerialPort (and so gnu.io.SerialPort). The API definition is taken from Sun. So honor them!

SerialPort describes the low-level interface to a serial communications port made available by the underlying system. SerialPort defines the minimum required functionality for serial communications ports.

Author:
gwellisch

Field Summary
static int DATABITS_8
          8 data bit format.
static int FLOWCONTROL_RTSCTS_IN
          RTS/CTS flow control on input.
static int FLOWCONTROL_RTSCTS_OUT
          RTS/CTS flow control on output.
static int PARITY_NONE
          No parity bit.
static int STOPBITS_1
          Number of STOP bits - 1.
 
Method Summary
 void addEventListener(SerialPortEventListener lsnr)
          Registers a SerialPortEventListener object to listen for SerialEvents.
 void close()
          Closes the communications port.
 void enableReceiveThreshold(int i)
          Enables receive threshold, if this feature is supported by the driver.
 void enableReceiveTimeout(int rcvTimeout)
          Enables receive timeout, if this feature is supported by the driver.
 java.io.InputStream getInputStream()
          Returns an input stream.
 java.io.OutputStream getOutputStream()
          Returns an output stream.
 void notifyOnBreakInterrupt(boolean b)
          Expresses interest in receiving notification when there is a break interrupt on the line.
 void notifyOnDataAvailable(boolean b)
          Expresses interest in receiving notification when input data is available.
 void notifyOnFramingError(boolean b)
          Expresses interest in receiving notification when there is a parity error.
 void notifyOnOutputEmpty(boolean b)
          Expresses interest in receiving notification when the output buffer is empty.
 void notifyOnOverrunError(boolean b)
          Expresses interest in receiving notification when there is an overrun error.
 void notifyOnParityError(boolean b)
          Expresses interest in receiving notification when there is a parity error.
 void setFlowControlMode(int flowcontrol)
          Sets the flow control mode.
 void setInputBufferSize(int serial_buffer_size)
          Gets the input buffer size.
 void setOutputBufferSize(int serial_buffer_size)
          Sets the output buffer size.
 void setSerialPortParams(int baudrate, int dataBits, int stopBits, int parity)
          Sets serial port parameters.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FLOWCONTROL_RTSCTS_IN

public static final int FLOWCONTROL_RTSCTS_IN
RTS/CTS flow control on input.


DATABITS_8

public static final int DATABITS_8
8 data bit format.


STOPBITS_1

public static final int STOPBITS_1
Number of STOP bits - 1.


PARITY_NONE

public static final int PARITY_NONE
No parity bit.


FLOWCONTROL_RTSCTS_OUT

public static final int FLOWCONTROL_RTSCTS_OUT
RTS/CTS flow control on output.

Method Detail

addEventListener

public void addEventListener(SerialPortEventListener lsnr)
Registers a SerialPortEventListener object to listen for SerialEvents. Interest in specific events may be expressed using the notifyOnXXX calls. The serialEvent method of SerialPortEventListener will be called with a SerialEvent object describing the event. The current implementation only allows one listener per SerialPort. Once a listener is registered, subsequent call attempts to addEventListener will throw a TooManyListenersException without effecting the listener already registered. All the events received by this listener are generated by one dedicated thread that belongs to the SerialPort object. After the port is closed, no more event will be generated. Another call to open() of the port's CommPortIdentifier object will return a new CommPort object, and the lsnr has to be added again to the new CommPort object to receive event from this port.

Parameters:
lsnr - The SerialPortEventListener object whose serialEvent method will be called with a SerialEvent describing the event.
Throws:
java.util.TooManyListenersException - (Wrapped as RuntimeException) If an initial attempt to attach a listener succeeds, subsequent attempts will throw TooManyListenersException without effecting the first listener.

close

public void close()
Closes the communications port. The application must call close when it is done with the port. Notification of this ownership change will be propagated to all classes registered using addPortOwnershipListener.


enableReceiveThreshold

public void enableReceiveThreshold(int i)
Enables receive threshold, if this feature is supported by the driver. When the receive threshold condition becomes true, a read from the input stream for this port will return immediately. enableReceiveThreshold is an advisory method which the driver may not implement. By default, receive threshold is not enabled. An application can determine whether the driver supports this feature by first calling the enableReceiveThreshold method and then calling the isReceiveThresholdEnabled method. If isReceiveThresholdEnabled still returns false, then receive threshold is not supported by the driver. If the driver does not implement this feature, it will return from blocking reads at an appropriate time. See getInputStream for description of exact behaviour.

Parameters:
i - when this many bytes are in the input buffer, return immediately from read.
Throws:
UnsupportedCommOperationException - - (Wrapped as RuntimeException) is thrown if receive threshold is not supported by the underlying driver.

enableReceiveTimeout

public void enableReceiveTimeout(int rcvTimeout)
Enables receive timeout, if this feature is supported by the driver. When the receive timeout condition becomes true, a read from the input stream for this port will return immediately.

enableReceiveTimeout is an advisory method which the driver may not implement. By default, receive timeout is not enabled.

An application can determine whether the driver supports this feature by first calling the enableReceiveTimeout method and then calling the isReceiveTimeout method. If isReceiveTimeout still returns false, then receive timeout is not supported by the driver.

See getInputStream for description of exact behaviour.

Parameters:
rcvTimeout - when this many milliseconds have elapsed, return immediately from read, regardless of bytes in input buffer.

getInputStream

public java.io.InputStream getInputStream()
Returns an input stream. This is the only way to receive data from the communications port. If the port is unidirectional and doesn't support receiving data, then getInputStream returns null.

The read behaviour of the input stream returned by getInputStream depends on combination of the threshold and timeout values. The possible behaviours are described in the table below:

Threshold Timeout Read Buffer Size Read Behaviour
State Value State Value
disabled - disabled - n bytes block until any data is available
enabled m bytes disabled - n bytes block until min(m,n) bytes are available
disabled - enabled x ms n bytes block for x ms or until any data is available
enabled m bytes enabled x ms n bytes block for x ms or until min(m,n) bytes are available

Note, however, that framing errors may cause the Timeout and Threshold values to complete prematurely without raising an exception.

Enabling the Timeout OR Threshold with a value a zero is a special case. This causes the underlying driver to poll for incoming data instead being event driven. Otherwise, the behaviour is identical to having both the Timeout and Threshold disabled.

Returns:
InputStream object that can be used to read from the port

getOutputStream

public java.io.OutputStream getOutputStream()
Returns an output stream. This is the only way to send data to the communications port. If the port is unidirectional and doesn't support sending data, then getOutputStream returns null.

Returns:
OutputStream object that can be used to write to the port

notifyOnBreakInterrupt

public void notifyOnBreakInterrupt(boolean b)
Expresses interest in receiving notification when there is a break interrupt on the line. This notification is hardware dependent and may not be supported by all implementations.

Parameters:
b -
  • true: enable notification
  • false: disable notification

notifyOnDataAvailable

public void notifyOnDataAvailable(boolean b)
Expresses interest in receiving notification when input data is available. This may be used to drive asynchronous input. When data is available in the input buffer, this event is propagated to the listener registered using addEventListener. The event will be generated once when new data arrive at the serial port. Even if the user doesn't read the data, it won't be generated again until next time new data arrive.

Parameters:
b -
  • true: enable notification
  • false: disable notification

notifyOnFramingError

public void notifyOnFramingError(boolean b)
Expresses interest in receiving notification when there is a parity error. This notification is hardware dependent and may not be supported by all implementations.

Parameters:
b -
  • true: enable notification
  • false: disable notification

notifyOnOutputEmpty

public void notifyOnOutputEmpty(boolean b)
Expresses interest in receiving notification when the output buffer is empty. This may be used to drive asynchronous output. When the output buffer becomes empty, this event is propagated to the listener registered using addEventListener. The event will be generated after a write is completed, when the system buffer becomes empty again. This notification is hardware dependent and may not be supported by all implementations.

Parameters:
b -
  • true: enable notification
  • false: disable notification

notifyOnOverrunError

public void notifyOnOverrunError(boolean b)
Expresses interest in receiving notification when there is an overrun error. This notification is hardware dependent and may not be supported by all implementations.

Parameters:
b -
  • true: enable notification
  • false: disable notification

notifyOnParityError

public void notifyOnParityError(boolean b)
Expresses interest in receiving notification when there is a parity error. This notification is hardware dependent and may not be supported by all implementations.

Parameters:
b -
  • true: enable notification
  • false: disable notification

setFlowControlMode

public void setFlowControlMode(int flowcontrol)
Sets the flow control mode.

Parameters:
flowcontrol - Can be a bitmask combination of
  • FLOWCONTROL_NONE: no flow control
  • FLOWCONTROL_RTSCTS_IN: RTS/CTS (hardware) flow control for input
  • FLOWCONTROL_RTSCTS_OUT: RTS/CTS (hardware) flow control for output
  • FLOWCONTROL_XONXOFF_IN: XON/XOFF (software) flow control for input
  • FLOWCONTROL_XONXOFF_OUT: XON/XOFF (software) flow control for output

setInputBufferSize

public void setInputBufferSize(int serial_buffer_size)
Gets the input buffer size. Note that this method is advisory and the underlying OS may choose not to report correct values for the buffer size.

Parameters:
serial_buffer_size - input buffer size currently in use

setOutputBufferSize

public void setOutputBufferSize(int serial_buffer_size)
Sets the output buffer size. Note that this is advisory and memory availability may determine the ultimate buffer size used by the driver.

Parameters:
serial_buffer_size - size of the output buffer

setSerialPortParams

public void setSerialPortParams(int baudrate,
                                int dataBits,
                                int stopBits,
                                int parity)
Sets serial port parameters.

Parameters:
baudrate - If the baudrate passed in by the application is unsupported by the driver, the driver will throw an UnsupportedCommOperationException
dataBits -
  • DATABITS_5: 5 bits
  • DATABITS_6: 6 bits
  • DATABITS_7: 7 bits
  • DATABITS_8: 8 bits
stopBits -
  • STOPBITS_1: 1 stop bit
  • STOPBITS_2: 2 stop bits
  • STOPBITS_1_5: 1.5 stop bits
parity -
  • PARITY_NONE: no parity PARITY_ODD: odd parity
  • PARITY_EVEN: even parity PARITY_MARK: mark parity
  • PARITY_SPACE: space parity

SMSLib 3.5.3

(c) 2002-2011, http://smslib.org