WinDoesIt ( Frame4J -- the Java framework de.frame4j... )

java.lang.Object
- de.weAut.ioPorts.WinDoesIt

```
public class WinDoesIt
extends Object
```
System services — especially for the serial interface.

This class provides the underlying operating system's services by native methods (JNI) of the library "bsDoesItNative". On Windows this library must exist as "bsDoesItNative.dll". Until July 2013 that Windows shared library (DLL) was available as C/C++ implementation for Win32 only. As of August 2013 all was modified to support Windows 64 bit systems as well.

If functionally equivalent shared libraries were available for other platforms, like say a "bsDoesItNative.so" for Solaris e.g., this class would be usable for other platforms too. As of writing it's Frame4J just provides Windows implementations. (And therefore its badly needed as Sun dropped the comm-extensions for Windows.)

Constants and methods are as far as possible (mostly one to one) those of the services provided by the Windows platform making those services available to Java applications.
Remark 1: This recommendable design approach may be called
* "minimal native wrapper"
or as a motto
* "If it has to be C/C++, let's take the absolute minimal dose."

Remark 2: The serial interface services for Windows (and their quality) provided by this approach go beyond the SUN Comm API's possibilities.

The (static) methods of this class may of cause be used directly. Usually a comfortable and OO like wrapper, as provided by SerNimpl is preferred by the application programmer. This wrapper is also robust in the sense that the (native) C functions (just forwarded by this class) by its nature lack Java's type safety. The direct caller of this class' methods has to check the ability to be called and the parameter values in every single case.

Hints for making the Windows implementation "bsDoesItNative.dll":

The fist step is the generation of a compatible include file by

javah -o de_a-weinert_io_WinDoesIt.h de.frame4j.io.WinDoesIt

Any C or C++ sources etc., like e.g. WinDoesIt.cpp and WinDoesIt.def, have to be consistent to the actual WinDoesIt.h

Hints on the library generation of are found in the comments of WinDoesIt.cpp, that is (now) part of Frame4J.

Important:
As the native Windows implementations differ for Win32 and Win64 be sure to pick the right WinDoesIt.dll to put into %JAVA_HOME%\jre\bin\.
© Copyright 2007 Albrecht Weinert

Version:

66 (7.06.2024)

Author:

Albrecht Weinert

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`CLRBREAK` Constant for escape method.
`static int`	`CLRDTR` Constant for escape method.
`static int`	`CLRRTS` Constant for escape method.
`static long`	`INVALID_HANDLE_VALUE` Invalid value for the system's I/O handle.
`static int`	`MS_CTS_ON` Constant for modem state.
`static int`	`MS_DSR_ON` Constant for modem state.
`static int`	`MS_RING_ON` Constant for modem state.
`static int`	`MS_RLSD_ON` Constant for modem state.
`static int`	`ONE5STOPBITS` Constant for StoppBits.
`static int`	`ONESTOPBIT` Constant for stop bits.
`static int`	`PURGE_OR` Constant for purge method.
`static int`	`PURGE_RXABORT` Constant for purge method.
`static int`	`PURGE_RXCLEAR` Constant for purge method.
`static int`	`PURGE_RXOR` Constant for purge method.
`static int`	`PURGE_TXABORT` Constant for purge method.
`static int`	`PURGE_TXCLEAR` Constant for purge method.
`static int`	`SETBREAK` Constant for escape method.
`static int`	`SETDTR` Constant for escape method.
`static int`	`SETRTS` Constant for escape method.
`static int`	`SETXOFF` Constant for escape method.
`static int`	`SETXON` Constant for escape method.
`static int`	`TWOSTOPBITS` Constant for StoppBits.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static boolean`	`closePort(long port)` Close the port respectively handle.
`static String`	`errorMessage(int errNo)` Get the report String from the error number.
`static boolean`	`escapeComm(long handle, int op)` USART control.
`static boolean`	`flushSerial(long port)` Empty the (system's) output buffer.
`static int`	`getLastError()` Determine the last respectively actual error number.
`static int`	`getSerial(long port)` Read just one byte.
`static int`	`getSerialModemStatus(long port)` Read the modem state.
`static int[]`	`getSerialParams(long port)` Get the serial port's actual settings.
`static int[]`	`getSerialTimeouts(long port)` Get the actual timeouts for the serial port.
`static long`	`openSerialPort(String comPort)` Open a serial port.
`static boolean`	`purgeSerialPort(long port, int ops)` Clear / abort all outstanding operations.
`static int`	`putSerial(long port, byte data)` Write just one byte.
`static int`	`readSerial(long port, byte[] data, int off, int len)` Read some bytes from the handle (port).
`static boolean`	`setDtrRts(long handle, boolean dtr, boolean rts)` Set the modem control outputs DTR and RTS.
`static boolean`	`setSerialParams(long port, int baud, int dataBits, int stopBits, int parity, int flowControl)` Do the serial port's basic settings.
`static boolean`	`setSerialTimeouts(long port, int readIntervalTimeout, int readTotalTimeoutMultiplier, int readTotalTimeoutConstant, int writeTotalTimeoutMultiplier, int writeTotalTimeoutConstant)` Set the serial port's timeouts.
`static int`	`writeSerial(long port, byte[] data, int off, int len)` Write some bytes.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - INVALID_HANDLE_VALUE
```
public static final long INVALID_HANDLE_VALUE
```
    Invalid value for the system's I/O handle.
    
    Hint WinBase.h:
    #define INVALID_HANDLE_VALUE (HANDLE)(-1)
    respectively for 64 bit:
    #define INVALID_HANDLE_VALUE ((HANDLE)(LONG_PTR)-1)
    
    Value: -1L
    
    See Also:
    
    Constant Field Values
  - ONESTOPBIT
```
public static final int ONESTOPBIT
```
    Constant for stop bits.
    
    Hint: The Windows (winBase.h) value and not the one according to javax.comm, RXTX and hence SerialDefs.
    
    Value: 0
    
    See Also:
    
    setSerialParams(long, int, int, int, int, int), ONE5STOPBITS, TWOSTOPBITS, Constant Field Values
  - TWOSTOPBITS
```
public static final int TWOSTOPBITS
```
    Constant for StoppBits.
    
    Value: 2
    
    See Also:
    
    ONE5STOPBITS, ONESTOPBIT, Constant Field Values
  - ONE5STOPBITS
```
public static final int ONE5STOPBITS
```
    Constant for StoppBits.
    
    Hint: The values used here are those of Windows (winBase.h) and not those defined by javax.comm, RXTX and hence SerialDefs.
    
    Value: 1
    
    See Also:
    
    ONESTOPBIT, Constant Field Values
  - PURGE_RXABORT
```
public static final int PURGE_RXABORT
```
    Constant for purge method.
    
    Terminates all outstanding overlapped read operations and returns immediately, even if the read operations have not been completed.
    
    Hint: This class' access methods respectively their native implementation "bsDoesItNative.dll for Windows all are "non overlapped".
    
    Value: 2
    
    See Also:
    
    purgeSerialPort(long, int), PURGE_TXABORT, Constant Field Values
  - PURGE_RXCLEAR
```
public static final int PURGE_RXCLEAR
```
    Constant for purge method.
    
    Clears the input buffer (if the device driver has one).
    
    Value: 8
    
    See Also:
    
    purgeSerialPort(long, int), PURGE_RXABORT, Constant Field Values
  - PURGE_TXABORT
```
public static final int PURGE_TXABORT
```
    Constant for purge method.
    
    Terminates all outstanding overlapped write operations and returns immediately, even if the write operations have not been completed.
    
    Value: 1
    
    See Also:
    
    purgeSerialPort(long, int), PURGE_RXABORT, PURGE_RXOR, Constant Field Values
  - PURGE_RXOR
```
public static final int PURGE_RXOR
```
    Constant for purge method.
    
    OR of the receive operations.
    
    Value: 10
    
    See Also:
    
    purgeSerialPort(long, int), PURGE_RXABORT, Constant Field Values
  - PURGE_TXCLEAR
```
public static final int PURGE_TXCLEAR
```
    Constant for purge method.
    
    Clears the output buffer (if the device driver has one).
    
    Value: 4
    
    See Also:
    
    purgeSerialPort(long, int), PURGE_RXABORT, Constant Field Values
  - PURGE_OR
```
public static final int PURGE_OR
```
    Constant for purge method.
    
    OR of all PURGE constants.
    
    Value: 15
    
    See Also:
    
    purgeSerialPort(long, int), PURGE_RXABORT, PURGE_RXCLEAR, PURGE_TXABORT, PURGE_TXCLEAR, Constant Field Values
  - MS_CTS_ON
```
public static final int MS_CTS_ON
```
    Constant for modem state.
    
    The CTS (clear-to-send) signal is on.
    
    Value: 16
    
    See Also:
    
    getSerialModemStatus(long), MS_DSR_ON, Constant Field Values
  - MS_DSR_ON
```
public static final int MS_DSR_ON
```
    Constant for modem state.
    
    The DSR (data-set-ready) signal is on.
    
    Value: 32
    
    See Also:
    
    getSerialModemStatus(long), MS_RING_ON, Constant Field Values
  - MS_RING_ON
```
public static final int MS_RING_ON
```
    Constant for modem state.
    
    The ring indicator signal is on.
    
    Value: 64
    
    See Also:
    
    getSerialModemStatus(long), MS_RLSD_ON, Constant Field Values
  - MS_RLSD_ON
```
public static final int MS_RLSD_ON
```
    Constant for modem state.
    
    The RLSD (receive-line-signal-detect; vulgo carrier detect ??) signal is on.
    
    Value: 128
    
    See Also:
    
    getSerialModemStatus(long), MS_CTS_ON, Constant Field Values
  - CLRBREAK
```
public static final int CLRBREAK
```
    Constant for escape method.
    
    Restores character transmission and places the transmission line into a non-break state.
    
    Value: 9
    
    See Also:
    
    escapeComm(long, int), CLRDTR, Constant Field Values
  - CLRDTR
```
public static final int CLRDTR
```
    Constant for escape method.
    
    Clears DTR (data-terminal-ready).
    
    Value: 6
    
    See Also:
    
    escapeComm(long, int), CLRBREAK, Constant Field Values
  - CLRRTS
```
public static final int CLRRTS
```
    Constant for escape method.
    
    Clears RTS (request-to-send).
    
    Value: 4
    
    See Also:
    
    escapeComm(long, int), CLRBREAK, Constant Field Values
  - SETBREAK
```
public static final int SETBREAK
```
    Constant for escape method.
    
    Suspends character transmission and places the transmission line in a break state.
    
    Value: 8
    
    See Also:
    
    escapeComm(long, int), CLRBREAK, Constant Field Values
  - SETDTR
```
public static final int SETDTR
```
    Constant for escape method.
    
    Sets DTR (data-terminal-ready).
    
    Value: 5
    
    See Also:
    
    escapeComm(long, int), CLRBREAK, Constant Field Values
  - SETRTS
```
public static final int SETRTS
```
    Constant for escape method.
    
    Sets RTS (request-to-send).
    
    Value: 3
    
    See Also:
    
    escapeComm(long, int), CLRBREAK, Constant Field Values
  - SETXOFF
```
public static final int SETXOFF
```
    Constant for escape method.
    
    Causes transmission to act as if an XOFF character has been received.
    
    Value: 1
    
    See Also:
    
    escapeComm(long, int), CLRBREAK, Constant Field Values
  - SETXON
```
public static final int SETXON
```
    Constant for escape method.
    
    Causes transmission to act as if an XOFN character has been received.
    
    Value: 2
    
    See Also:
    
    escapeComm(long, int), CLRBREAK, Constant Field Values
- Method Detail
  - openSerialPort
```
public static long openSerialPort(String comPort)
```
    Open a serial port.
    
    The valid handle returned in the case of success must be used for all further operations.
    
    Failures are signalled by returning the invalid handle INVALID_HANDLE_VALUE.
    The cause may be retrieved by getLastError() (and by errorMessage(int)):
    "error = 5 : access denied" mostly means the interface being in use already.
    "error = 3 : The system cannot finde ....." usually means that there is no interface of the given name at all.
    
    Hint: On Windows the interfaces names are usually "COM1", "COM2" and so on.
    
    Parameters:
    
    comPort - the port's name
    
    Returns:
    
    Handle to the port (it is a Windows file handle); INVALID_HANDLE_VALUE on failure
  - closePort
```
public static boolean closePort(long port)
```
    Close the port respectively handle.
    
    The device, the interface or even a file represented by the valid handle port will be closed for all further operations.
    
    Parameters:
    
    port - a handle
    
    Returns:
    
    true on success
    
    See Also:
    
    getLastError()
  - getLastError
```
public static int getLastError()
```
    Determine the last respectively actual error number.
    
    If any method returned had met no success (signalled by INVALID_HANDLE_VALUE, false, null or similar) this method fetches the operating systems error number.
    
    Hint: The Windows implementation (bsDoesItNative.dll) returns the value got (already) by using the system call (GetLastError()). If that is 0 this library's last cached error value for the last failed operation is returned.
    
    Hint 2: A second call after a failed operation usually returns 0 (OK) as does a call after a successful operation.
    
    Hint 3: Java classes wrapping this class in an OO conforming way will forward the (non OK) information got here and translated by errorMessage(int) to human readable text usually as an Exception.
    
    Returns:
    
    operating system specific error number
    
    See Also:
    
    errorMessage(int)
  - errorMessage
```
public static String errorMessage(int errNo)
```
    Get the report String from the error number.
    
    For a valid (known) error number the system specific text report will be fetched.
    
    Hint: At least on Windows the text to number correlation is strictly static. The text provided will be (nationalised) mostly in the installation language of that Windows. That does not have to be the language (see AppLangMap etc.) set for the Java application. Hence, the number to text translation may be cached and done self for the language expected.
    
    Parameters:
    
    errNo - error number; see getLastError()
    
    Returns:
    
    operating system provided error text
  - setSerialParams
```
public static boolean setSerialParams(long port,
                                      int baud,
                                      int dataBits,
                                      int stopBits,
                                      int parity,
                                      int flowControl)
```
    Do the serial port's basic settings.
    
    This method sets (almost) all parameters relevant for the port's communication protocol in one step. The set of parameters is that the station at the other and of the line must have set the same way to enable any communication.
    
    A value -1 and partly illegal values mean no change of the setting in each case.
    
    For those settings, when 0 is illegal, 0 means the default value.
    
    Parameters:
    
    port - handle
    
    baud - baud rate
    
    dataBits - 5..8
    
    stopBits - fitting constant value
    
    parity - see SerialDefs
    
    flowControl - (see SerialDefs)
    
    Returns:
    
    true on success
    
    See Also:
    
    ONESTOPBIT, ONE5STOPBITS, TWOSTOPBITS, getSerialParams(long), setSerialTimeouts(long, int, int, int, int, int), getSerialTimeouts(long)
  - getSerialParams
```
public static int[] getSerialParams(long port)
```
    Get the serial port's actual settings.
    
    Parameters:
    
    port - handle
    
    Returns:
    
    int[] of length 5; for the entries see setSerialParams(long, int, int, int, int, int)); null on failure
    
    See Also:
    
    setSerialParams(long, int, int, int, int, int)
  - setSerialTimeouts
```
public static boolean setSerialTimeouts(long port,
                                        int readIntervalTimeout,
                                        int readTotalTimeoutMultiplier,
                                        int readTotalTimeoutConstant,
                                        int writeTotalTimeoutMultiplier,
                                        int writeTotalTimeoutConstant)
```
    Set the serial port's timeouts.
    
    readIntervalTimeout:
    Maximum time in milliseconds before the arrival of a second and all following bytes.
    A value -1 (interpreted by the driver as a very big unsigned value) combined with two times 0 for the next two values will provide immediate return with buffered input valued, even that may mean none at all.
    
    readTotalTimeoutMultiplier:
    Factor in milliseconds for the whole read operations timeout. This value will be multiplied by the maximum number of bytes expected (length of input buffer provided).
    
    readTotalTimeoutConstant:
    This value will be added to the product just described. If both are 0 that means no timeout for read operations.
    
    writeTotalTimeoutMultiplier:
    Factor in milliseconds for the whole write operations timeout. This value will be multiplied by the number of bytes to be written (length of output buffer / array provided)..
    
    writeTotalTimeoutConstant:
    This value will be added to the product just described. If both are 0 that means no timeout for write operations.
    
    Remark:
    If readIntervalTimeout and readTotalTimeoutMultiplier are -1 (meaning unsigned maximum) and readTotalTimeoutConstant is > 0 and < (unsigned) maximum, the following applies:
    If there is at least one byte (or more) in a system (driver) or hardware input buffer, the read operations will return immediately fetching values from that buffer.
    If the buffer is empty, the read operations will wait for the first byte input and fetch it.
    If no input byte arrives within readTotalTimeoutConstant a timeout occurs.
    
    Parameters:
    
    readIntervalTimeout - between the bytes (see above)
    
    readTotalTimeoutMultiplier - * number of bytes (see above)
    
    readTotalTimeoutConstant - + (see above)
    
    writeTotalTimeoutMultiplier - * number of bytes (see above)
    
    writeTotalTimeoutConstant - + (see above)
    
    Returns:
    
    true bei Erfolg
  - getSerialTimeouts
```
public static int[] getSerialTimeouts(long port)
```
    Get the actual timeouts for the serial port.
    
    Parameters:
    
    port - handle
    
    Returns:
    
    int[] of length 5 containing the timeout values as seen by setSerialTimeouts(long, int, int, int, int, int)) parameters;
    null on failure
  - purgeSerialPort
```
public static boolean purgeSerialPort(long port,
                                      int ops)
```
    Clear / abort all outstanding operations.
    
    It is quite usual to call this method immediately after opening with the OR of all PURGE constants.
    
    Parameters:
    
    port - handle
    
    ops - Ein oder mehrere (Oder) PURGE-Konstanten
    
    Returns:
    
    true bei Erfolg
    
    See Also:
    
    PURGE_RXABORT, PURGE_RXCLEAR, PURGE_TXABORT, PURGE_TXCLEAR, PURGE_OR
  - getSerialModemStatus
```
public static int getSerialModemStatus(long port)
```
    Read the modem state.
    
    Parameters:
    
    port - the Windows handle for the port
    
    Returns:
    
    -1 on failure, otherwise a combination of modem state constants
    
    See Also:
    
    MS_CTS_ON, MS_DSR_ON, MS_RING_ON, MS_RLSD_ON
  - writeSerial
```
public static int writeSerial(long port,
                              byte[] data,
                              int off,
                              int len)
```
    Write some bytes.
    
    The specified number of bytes (len of the array data) will be written to the port. The serial interface's timing / time out behaviour will be determined by the method's setSerialTimeouts() two relevant parameters.
    
    Hint: This method works on Windows for any valid handle and hence device or file.
    
    Parameters:
    
    port - handle
    
    data - buffer
    
    off - index of first byte to be output (0 or larger)
    
    len - number of bytes (has to be <= data's length!)
    
    Returns:
    
    number of bytes written or -1 on failure
  - putSerial
```
public static int putSerial(long port,
                            byte data)
```
    Write just one byte.
    
    This method is to be preferred over writeSerial(long, byte[], int, int) if and only if just one byte is to be output.
    
    Hint: This method works on Windows for any valid handle and hence device or file.
    
    Parameters:
    
    port - handle
    
    data - the byte
    
    Returns:
    
    number of bytes written (i.e. 0 or 1); -1 on failure
  - flushSerial
```
public static boolean flushSerial(long port)
```
    Empty the (system's) output buffer.
    
    The output buffers of the device represented by the handle port will be flushed.
    
    Hint: There are no useful informations on necessity and return behaviour for serial interfaces from platform specification. It should be not to naive, to infer that bytes fed to a USART or its driver will flow out by itself as fast as hardware and receiving station permit.
    This method called for serial devices may probably make no sense.
    
    Returns:
    
    true on success
  - readSerial
```
public static int readSerial(long port,
                             byte[] data,
                             int off,
                             int len)
```
    Read some bytes from the handle (port).
    
    This method reads a number of bytes from the represented device.
    
    The serial interface's timing / time out behaviour will be determined by the method's setSerialTimeouts() three relevant parameters.
    
    Hint: This method works on Windows for any valid handle and hence device or file.
    
    Parameters:
    
    port - handle
    
    data - the input buffer provided
    
    off - index of where the first byte read is to be put (0 or larger)
    
    len - number of bytes (has to be <= data's length!)
    
    Returns:
    
    number of bytes read or -1 on failure
    
    See Also:
    
    writeSerial(long, byte[], int, int)
  - getSerial
```
public static int getSerial(long port)
```
    Read just one byte.
    
    This method is to be preferred over readSerial(long, byte[], int, int) if and only if just one byte is to be read.
    
    Hint: This method works on Windows for any valid handle and hence device or file.
    
    Parameters:
    
    port - handle
    
    Returns:
    
    the read byte's value (0..255) or -1 on failure or timeout
  - setDtrRts
```
public static boolean setDtrRts(long handle,
                                boolean dtr,
                                boolean rts)
```
    Set the modem control outputs DTR and RTS.
    
    In time critical cases calling this method should be preferred over the single settings by escapeComm(long, int).
    
    For example, time critical cases are those, when only one of the control signals really is used for control, while together the other one it powers the external hardware (via a bridge rectifier). There are HART modems working just that way.
    
    Hint: This is the (one and) only method that under Windows (i.e. bsDoesItNative.dll) does not procure exactly one fitting system call. (It procures two).
    
    See Also:
    
    escapeComm(long, int), SETDTR, CLRRTS
  - escapeComm
```
public static boolean escapeComm(long handle,
                                 int op)
```
    USART control.
    
    Parameters:
    
    handle - the Windows handle for the port
    
    op - Eine der SET.. respectively CLR...-Konstanten
    
    Returns:
    
    true bei Erfolg
    
    See Also:
    
    CLRDTR, CLRBREAK, CLRRTS, SETBREAK, SETDTR, SETRTS, SETXOFF, SETXON

Class WinDoesIt

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

INVALID_HANDLE_VALUE

ONESTOPBIT

TWOSTOPBITS

ONE5STOPBITS

PURGE_RXABORT

PURGE_RXCLEAR

PURGE_TXABORT

PURGE_RXOR

PURGE_TXCLEAR

PURGE_OR

MS_CTS_ON

MS_DSR_ON

MS_RING_ON

MS_RLSD_ON

CLRBREAK

CLRDTR

CLRRTS

SETBREAK

SETDTR

SETRTS

SETXOFF

SETXON

Method Detail

openSerialPort

closePort

getLastError

errorMessage

setSerialParams

getSerialParams

setSerialTimeouts

getSerialTimeouts

purgeSerialPort

getSerialModemStatus

writeSerial

putSerial

flushSerial

readSerial

getSerial

setDtrRts

escapeComm