From 6f5f2c4e8b6777cedab15173159358b9f4246677 Mon Sep 17 00:00:00 2001 From: hedgecrw85 Date: Mon, 15 Jun 2015 12:42:25 -0500 Subject: [PATCH] Added documentation for OS-specific differences. --- INSTALL | 14 ++++----- build.gradle | 2 +- .../com/fazecast/jSerialComm/SerialPort.java | 31 +++++++++++++++++-- .../jSerialComm/SerialPortDataListener.java | 4 ++- .../fazecast/jSerialComm/SerialPortEvent.java | 8 ++++- .../jSerialComm/SerialPortPacketListener.java | 2 +- .../fazecast/jSerialComm/SerialPortTest.java | 2 +- 7 files changed, 48 insertions(+), 15 deletions(-) diff --git a/INSTALL b/INSTALL index a7ffbc9..0acaf86 100644 --- a/INSTALL +++ b/INSTALL @@ -123,31 +123,31 @@ Maven: com.fazecast jSerialComm - 1.3.5 + 1.3.6 Ivy: - + Grape: @Grapes( - @Grab(group='com.fazecast', module='jSerialComm', version='1.3.5') + @Grab(group='com.fazecast', module='jSerialComm', version='1.3.6') ) Gradle: -'com.fazecast:jSerialComm:1.3.5' +'com.fazecast:jSerialComm:1.3.6' Buildr: -'com.fazecast:jSerialComm:jar:1.3.5' +'com.fazecast:jSerialComm:jar:1.3.6' SBT: -libraryDependencies += "com.fazecast" % "jSerialComm" % "1.3.5" +libraryDependencies += "com.fazecast" % "jSerialComm" % "1.3.6" Leiningen: -[com.fazecast/jSerialComm "1.3.5"] +[com.fazecast/jSerialComm "1.3.6"] diff --git a/build.gradle b/build.gradle index 4d7cc43..0fdde25 100644 --- a/build.gradle +++ b/build.gradle @@ -4,7 +4,7 @@ apply plugin: 'maven' group = 'com.fazecast' archivesBaseName = 'jSerialComm' -version = '1.3.5' +version = '1.3.6' sourceCompatibility = 1.6 targetCompatibility = 1.6 diff --git a/src/main/java/com/fazecast/jSerialComm/SerialPort.java b/src/main/java/com/fazecast/jSerialComm/SerialPort.java index fdd9805..55c77dc 100644 --- a/src/main/java/com/fazecast/jSerialComm/SerialPort.java +++ b/src/main/java/com/fazecast/jSerialComm/SerialPort.java @@ -38,7 +38,7 @@ import java.util.Date; * This class provides native access to serial ports and devices without requiring external libraries or tools. * * @author Will Hedgecock <will.hedgecock@fazecast.com> - * @version 1.3.5 + * @version 1.3.6 * @see java.io.InputStream * @see java.io.OutputStream */ @@ -501,6 +501,8 @@ public final class SerialPort /** * Sets the serial port read and write timeout parameters. *

+ * Note that write timeouts are only available on Windows-based systems. There is no functionality to set a write timeout on other operating systems. + *

* The built-in timeout mode constants should be used ({@link #TIMEOUT_NONBLOCKING}, {@link #TIMEOUT_READ_SEMI_BLOCKING}, * {@link #TIMEOUT_WRITE_SEMI_BLOCKING}, {@link #TIMEOUT_READ_BLOCKING}, {@link #TIMEOUT_WRITE_BLOCKING}, {@link #TIMEOUT_SCANNER}) to specify how * timeouts are to be handled. @@ -531,6 +533,10 @@ public final class SerialPort *

* A value of 0 for either newReadTimeout or newWriteTimeout indicates that a {@link #readBytes(byte[],long)} or * {@link #writeBytes(byte[],long)} call should block forever until it can return successfully (based upon the current timeout mode specified). + *

+ * It is important to note that non-Windows operating systems only allow decisecond (1/10th of a second) granularity for serial port timeouts. As such, your + * millisecond timeout value will be rounded to the nearest decisecond under Linux or Mac OS. To ensure consistent performance across multiple platforms, it is + * advisable that you set your timeout values to be multiples of 100, although this is not strictly enforced. * * @param newTimeoutMode The new timeout mode as specified above. * @param newReadTimeout The number of milliseconds of inactivity to tolerate before returning from a {@link #readBytes(byte[],long)} call. @@ -539,8 +545,13 @@ public final class SerialPort public final void setComPortTimeouts(int newTimeoutMode, int newReadTimeout, int newWriteTimeout) { timeoutMode = newTimeoutMode; - readTimeout = newReadTimeout; - writeTimeout = newWriteTimeout; + if (isWindows) + { + readTimeout = newReadTimeout; + writeTimeout = newWriteTimeout; + } + else + readTimeout = Math.round((float)newReadTimeout / 100.0f) * 100; if (isOpened) { @@ -627,6 +638,12 @@ public final class SerialPort *

* Note that only one valid flow control configuration can be used at any time. For example, attempting to use both XOn/XOff * and RTS/CTS will most likely result in an unusable serial port. + *

+ * Also note that some flow control modes are only available on certain operating systems. Valid modes for each OS are: + *

+ *      Windows: CTS, RTS/CTS, DSR, DTR/DSR, Xon, Xoff, Xon/Xoff
+ *      Mac: RTS/CTS, Xon, Xoff, Xon/Xoff
+ *      Linux: RTS/CTS, Xon, Xoff, Xon/Xoff * * @param newFlowControlSettings The desired type of flow control to enable for this serial port. * @see #FLOW_CONTROL_DISABLED @@ -752,6 +769,8 @@ public final class SerialPort *

* Any value other than 0 indicates the number of milliseconds of inactivity that will be tolerated before the {@link #writeBytes(byte[],long)} * call will return. + *

+ * Note that write timeouts are only available on Windows operating systems. This value is ignored on all other systems. * * @return The number of milliseconds of inactivity to tolerate before returning from a {@link #writeBytes(byte[],long)} call. */ @@ -769,6 +788,12 @@ public final class SerialPort *      DSR: {@link #FLOW_CONTROL_DSR_ENABLED}
*      DTR/DSR: {@link #FLOW_CONTROL_DTR_ENABLED} | {@link #FLOW_CONTROL_DSR_ENABLED}
*      XOn/XOff: {@link #FLOW_CONTROL_XONXOFF_IN_ENABLED} | {@link #FLOW_CONTROL_XONXOFF_OUT_ENABLED} + *

+ * Note that some flow control modes are only available on certain operating systems. Valid modes for each OS are: + *

+ *      Windows: CTS, RTS/CTS, DSR, DTR/DSR, Xon, Xoff, Xon/Xoff
+ *      Mac: RTS/CTS, Xon, Xoff, Xon/Xoff
+ *      Linux: RTS/CTS, Xon, Xoff, Xon/Xoff * * @return The flow control settings enabled on this serial port. * @see #FLOW_CONTROL_DISABLED diff --git a/src/main/java/com/fazecast/jSerialComm/SerialPortDataListener.java b/src/main/java/com/fazecast/jSerialComm/SerialPortDataListener.java index 4a96a99..94fb8af 100644 --- a/src/main/java/com/fazecast/jSerialComm/SerialPortDataListener.java +++ b/src/main/java/com/fazecast/jSerialComm/SerialPortDataListener.java @@ -31,7 +31,7 @@ import java.util.EventListener; * This interface must be implemented to enable simple event-based serial port I/O. * * @author Will Hedgecock <will.hedgecock@fazecast.com> - * @version 1.3.5 + * @version 1.3.6 * @see java.util.EventListener */ public interface SerialPortDataListener extends EventListener @@ -49,6 +49,8 @@ public interface SerialPortDataListener extends EventListener *

* Two or more events may be OR'd together to listen for multiple events; however, if {@link SerialPort#LISTENING_EVENT_DATA_AVAILABLE} is OR'd with {@link SerialPort#LISTENING_EVENT_DATA_RECEIVED}, the {@link SerialPort#LISTENING_EVENT_DATA_RECEIVED} flag will take precedence. *

+ * Note that event-based write callbacks are only supported on Windows operating systems. As such, the {@link SerialPort#LISTENING_EVENT_DATA_WRITTEN} + * event will never be called on a non-Windows system. * * @return The event constants that should trigger the {@link #serialEvent(SerialPortEvent)} callback. * @see SerialPort#LISTENING_EVENT_DATA_AVAILABLE diff --git a/src/main/java/com/fazecast/jSerialComm/SerialPortEvent.java b/src/main/java/com/fazecast/jSerialComm/SerialPortEvent.java index 6c16f77..29cbe3b 100644 --- a/src/main/java/com/fazecast/jSerialComm/SerialPortEvent.java +++ b/src/main/java/com/fazecast/jSerialComm/SerialPortEvent.java @@ -31,7 +31,7 @@ import java.util.EventObject; * This class describes an asynchronous serial port event. * * @author Will Hedgecock <will.hedgecock@fazecast.com> - * @version 1.3.5 + * @version 1.3.6 * @see java.util.EventObject */ public final class SerialPortEvent extends EventObject @@ -51,6 +51,8 @@ public final class SerialPortEvent extends EventObject *      {@link SerialPort#LISTENING_EVENT_DATA_RECEIVED}
*      {@link SerialPort#LISTENING_EVENT_DATA_WRITTEN}
*

+ * Note that event-based write callbacks are only supported on Windows operating systems. As such, the {@link SerialPort#LISTENING_EVENT_DATA_WRITTEN} + * event will never be called on a non-Windows system. * * @param comPort The {@link SerialPort} about which this object is being created. * @param serialEventType The type of serial port event that this object describes. @@ -74,6 +76,8 @@ public final class SerialPortEvent extends EventObject *      {@link SerialPort#LISTENING_EVENT_DATA_RECEIVED}
*      {@link SerialPort#LISTENING_EVENT_DATA_WRITTEN}
*

+ * Note that event-based write callbacks are only supported on Windows operating systems. As such, the {@link SerialPort#LISTENING_EVENT_DATA_WRITTEN} + * event will never be called on a non-Windows system. * * @param comPort The {@link SerialPort} about which this object is being created. * @param serialEventType The type of serial port event that this object describes. @@ -105,6 +109,8 @@ public final class SerialPortEvent extends EventObject *      {@link SerialPort#LISTENING_EVENT_DATA_RECEIVED}
*      {@link SerialPort#LISTENING_EVENT_DATA_WRITTEN}
*

+ * Note that event-based write callbacks are only supported on Windows operating systems. As such, the {@link SerialPort#LISTENING_EVENT_DATA_WRITTEN} + * event will never be called on a non-Windows system. * * @return The serial port event that this object describes. * @see SerialPort#LISTENING_EVENT_DATA_AVAILABLE diff --git a/src/main/java/com/fazecast/jSerialComm/SerialPortPacketListener.java b/src/main/java/com/fazecast/jSerialComm/SerialPortPacketListener.java index 220d1cf..aba449d 100644 --- a/src/main/java/com/fazecast/jSerialComm/SerialPortPacketListener.java +++ b/src/main/java/com/fazecast/jSerialComm/SerialPortPacketListener.java @@ -31,7 +31,7 @@ package com.fazecast.jSerialComm; * Note: Using this interface will negate any serial port read timeout settings since they make no sense in an asynchronous context. * * @author Will Hedgecock <will.hedgecock@fazecast.com> - * @version 1.3.5 + * @version 1.3.6 * @see com.fazecast.jSerialComm.SerialPortDataListener * @see java.util.EventListener */ diff --git a/src/test/java/com/fazecast/jSerialComm/SerialPortTest.java b/src/test/java/com/fazecast/jSerialComm/SerialPortTest.java index 459a989..3a410f1 100644 --- a/src/test/java/com/fazecast/jSerialComm/SerialPortTest.java +++ b/src/test/java/com/fazecast/jSerialComm/SerialPortTest.java @@ -32,7 +32,7 @@ import java.util.Scanner; * This class provides a test case for the jSerialComm library. * * @author Will Hedgecock <will.hedgecock@gmail.com> - * @version 1.3.5 + * @version 1.3.6 * @see java.io.InputStream * @see java.io.OutputStream */