SerialComManager (Serial Pundit 1.0.4-SNAPSHOT API)

java.lang.Object
- com.serialpundit.serial.SerialComManager

```
public final class SerialComManager
extends Object
```
Root of SerialPundit.
- Native layer if fails to throw exception when an error occurs would log error message to STDERR file. It is assumed that Java application running on production systems will deploy a Java logger which will redirect STDERR messages to a log file. This way if an error occurs and native layer could not throw exception for example in out of memory case it will still be logged for later analysis.
Version:

1.0.4

Author:

Rishi Gupta

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`SerialComManager.BAUDRATE` Pre-defined enum constants for baud rate values.
`static class`	`SerialComManager.DATABITS` Pre-defined enum constants for number of data bits in a serial frame.
`static class`	`SerialComManager.ENDIAN` Pre-defined enum constants for defining endianness of data to be sent over serial port.
`static class`	`SerialComManager.FLOWCONTROL` Pre-defined enum constants for controlling data flow between DTE and DCE or two serial devices.
`static class`	`SerialComManager.FTPPROTO` Pre-defined enum constants for defining file transfer protocol to use.
`static class`	`SerialComManager.FTPVAR` Pre-defined enum constants for defining variant of file transfer protocol to use.
`static class`	`SerialComManager.NUMOFBYTES` Pre-defined enum constants for defining number of bytes given data can be represented in.
`static class`	`SerialComManager.PARITY` Pre-defined enum constants for enabling type of parity in a serial frame.
`static class`	`SerialComManager.SMODE` Pre-defined enum constants for defining behavior of byte stream.
`static class`	`SerialComManager.STOPBITS` Pre-defined enum constants for number of stop bits in a serial frame.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`CTS` Clear to send mask bit constant for UART control line.
`static int`	`DCD` Data carrier detect mask bit constant for UART control line.
`static int`	`DEFAULT_READBYTECOUNT` Default number of bytes (1024) to read from serial port.
`static int`	`DSR` Data set ready mask bit constant for UART control line.
`static int`	`DTR` Data terminal ready mask bit constant for UART control line.
`static String`	`EXP_UNBLOCKIO` The exception message indicating that a blocked read method has been unblocked and made to return to caller explicitly (irrespective there was data to read or not).
`static int`	`InputStream` The value indicating instance of SerialComInByteStream class is desired.
`static String`	`JAVA_LIB_VERSION` Production release version of the SerialPundit.
`static int`	`LOOP` Loop indicator mask bit constant for UART control line.
`static int`	`OutputStream` The value indicating instance of SerialComOutByteStream class is desired.
`static int`	`RI` Ring indicator mask bit constant for UART control line.
`static int`	`RTS` Request to send mask bit constant for UART control line.

Constructor Summary

Constructors
Constructor and Description
`SerialComManager()` Allocates a new SerialComManager object.
`SerialComManager(String loadedLibName, String directoryPath, boolean createDirectory, boolean hotDeploy)` Allocates a new SerialComManager object.

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`clearPortIOBuffers(long handle, boolean clearRxBuffer, boolean clearTxBuffer)` Discards data sent to port but not transmitted, or data received but not read.
`boolean`	`closeComPort(long handle)` Close the serial port.
`boolean`	`configureComPortControl(long handle, SerialComManager.FLOWCONTROL flowctrl, char xon, char xoff, boolean ParFraError, boolean overFlowErr)` This method configures the way data communication will be controlled between DTE and DCE.
`boolean`	`configureComPortData(long handle, SerialComManager.DATABITS dataBits, SerialComManager.STOPBITS stopBits, SerialComManager.PARITY parity, SerialComManager.BAUDRATE baudRate, int custBaud)` This method configures the rate at which communication will occur and the format of UART frame.
`long`	`createBlockingIOContext()` Prepares a context that should be passed to readBytesBlocking, writeBytesBlocking, readBytes, unblockBlockingIOOperation and destroyBlockingIOContext methods.
`boolean`	`destroyBlockingIOContext(long context)` Destroys the context that was created by a call to createBlockingIOContext method for blocking I/O operations uses.
`String`	`findDriverServingComPort(String comPortName)` Gives the name of the driver who is driving the given serial port.
`String`	`findIRQnumberForComPort(long handle)` Gives the address and IRQ number associated with the given serial port.
`boolean`	`fineTuneReadBehaviour(long handle, int vmin, int vtime, int rit, int rttm, int rttc)` This method gives more fine tune control to application for tuning performance and behavior of read operations to leverage OS specific facility for read operation.
`int[]`	`getByteCountInPortIOBuffer(long handle)` Get number of bytes in input and output port buffers used by operating system for instance tty buffers in Unix like systems.
`String[]`	`getCurrentConfiguration(long handle)` This method gives currently applicable settings associated with particular serial port.
`int`	`getEventsMask(ISerialComEventListener eventListener)` This method return currently applicable mask for events on serial port.
`int[]`	`getInterruptCount(long handle)` This method gives the number of interrupts on serial line that have occurred.
`ISerialIOStream`	`getIOStreamInstance(int streamType, long handle, SerialComManager.SMODE streamMode)` Factory method to create stream of type specified by streamType in blocking or non-blocking mode.
`String`	`getLibraryVersions()` Gives library versions of java and native library implementations for serial port communication.
`int[]`	`getLinesStatus(long handle)` Gives status of serial port's control lines as supported by underlying operating system.
`String`	`getPortName(long handle)` This method gives the port name with which given handle is associated.
`SerialComDBRelease`	`getSerialComDBReleaseInstance(String directoryPath, String loadedLibName)` Allocate, initialize and return an instance of SerialComDBRelease class on whom APIs can be called to release COM ports in use.
`SerialComNullModem`	`getSerialComNullModemInstance()` Provides an instance of SerialComNullModem class for managing virtual serial device, null modem, loop back and custom pinout connected virtual serial devices.
`SerialComPortMapper`	`getSerialComPortMapperInstance(String directoryPath, String loadedLibName)` Allocate, initialize and return an instance of SerialComPortMapper class on whom APIs can be called to map or unmap a serial port alias.
`SerialComVendorLib`	`getVendorLibFromFactory(int vendorLibIdentifier, String libDirectory, String vlibName)` Gives an instance of the class which implements API defined by vendor in their propriety library.
`String[]`	`listAvailableComPorts()` Returns all available UART style ports available on this system, otherwise an empty array of strings, if no serial style port is found in the system.
`long`	`openComPort(String portName, boolean enableRead, boolean enableWrite, boolean exclusiveOwnerShip)` Opens a serial port for communication.
`boolean`	`pauseListeningEvents(ISerialComEventListener eventListener)` This pauses delivering events to application.
`byte[]`	`readBytes(long handle)` If user does not specify any count, library try to read DEFAULT_READBYTECOUNT (1024 bytes) bytes as default value.
`int`	`readBytes(long handle, byte[] buffer, int offset, int length, long context, SerialComLineErrors lineErr)` Reads data bytes from serial port into given buffer also providing info about framing, parity etc errors.
`byte[]`	`readBytes(long handle, int byteCount)` Read specified number of data bytes from the given serial port.
`byte[]`	`readBytesBlocking(long handle, int byteCount, long context)` Read specified number of bytes from given serial port and stay blocked till bytes arrive at serial port.
`int`	`readBytesDirect(long handle, ByteBuffer buffer, int offset, int length)` Reads the bytes from the serial port into the given direct byte buffer using facilities of the underlying JVM and operating system.
`byte[]`	`readSingleByte(long handle)` This is a utility method to read a single byte from serial port.
`String`	`readString(long handle)` This method reads data from serial port and converts it into string.
`String`	`readString(long handle, int byteCount)` Reads data from serial port and converts it into string.
`boolean`	`receiveFile(long handle, File fileToReceive, SerialComManager.FTPPROTO ftpProto, SerialComManager.FTPVAR ftpVariant, boolean textMode, ISerialComFTPProgress progressListener, SerialComFTPCMDAbort transferState)` Receives file using specified file transfer protocol.
`boolean`	`registerDataListener(long handle, ISerialComDataListener dataListener)` This method associate a data looper with the given listener.
`boolean`	`registerLineEventListener(long handle, ISerialComEventListener eventListener)` This method associate a event looper with the given listener.
`boolean`	`resumeListeningEvents(ISerialComEventListener eventListener)` Resume delivering events kept in queue to application.
`boolean`	`sendBreak(long handle, int duration)` Assert a break condition on the specified port for the duration expressed in milliseconds.
`boolean`	`sendFile(long handle, File[] fileToSend, SerialComManager.FTPPROTO ftpProto, SerialComManager.FTPVAR ftpVariant, boolean textMode, ISerialComFTPProgress progressListener, SerialComFTPCMDAbort transferState)` Send given file(s) using specified file transfer protocol.
`boolean`	`setDTR(long handle, boolean enabled)` This method assert/de-assert DTR line of serial port.
`boolean`	`setEventsMask(ISerialComEventListener eventListener, int newMask)` Defines for which line events registered event listener will be called.
`boolean`	`setRTS(long handle, boolean enabled)` This method assert/de-assert RTS line of serial port.
`boolean`	`unblockBlockingIOOperation(long context)` Unblocks any blocked operation if it exist.
`boolean`	`unregisterDataListener(long handle, ISerialComDataListener dataListener)` This method destroys complete java and native looper subsystem associated with this particular data listener.
`boolean`	`unregisterLineEventListener(long handle, ISerialComEventListener eventListener)` This method destroys complete java and native looper subsystem associated with this particular event listener.
`int`	`writeBytes(long handle, byte[] buffer)` Utility method to call writeBytes without delay between successive bytes.
`int`	`writeBytes(long handle, byte[] buffer, int delay)` This method writes bytes from the specified byte type buffer.
`int`	`writeBytesBlocking(long handle, byte[] buffer, long context)` Write bytes from given buffer to the given handle in blocking mode.
`int`	`writeBytesDirect(long handle, ByteBuffer buffer, int offset, int length)` Writes the bytes from the given direct byte buffer using facilities of the underlying JVM and operating system.
`int`	`writeIntArray(long handle, int[] buffer, int delay, SerialComManager.ENDIAN endianness, SerialComManager.NUMOFBYTES numOfBytes)` This method send an array of integers on the specified port.
`int`	`writeSingleByte(long handle, byte dataByte)` This method writes a single byte to the specified port.
`int`	`writeSingleInt(long handle, int data, int delay, SerialComManager.ENDIAN endianness, SerialComManager.NUMOFBYTES numOfBytes)` Different CPU and OS will have different endianness.
`boolean`	`writeString(long handle, String data, Charset charset, int delay)` This method writes a string to the specified port.
`boolean`	`writeString(long handle, String data, int delay)` This method writes a string to the specified port.

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

- Field Detail
  - JAVA_LIB_VERSION
```
public static final String JAVA_LIB_VERSION
```
    Production release version of the SerialPundit.
    
    See Also:
    Constant Field Values
  - DEFAULT_READBYTECOUNT
```
public static final int DEFAULT_READBYTECOUNT
```
    Default number of bytes (1024) to read from serial port.
    
    See Also:
    Constant Field Values
  - CTS
```
public static final int CTS
```
    Clear to send mask bit constant for UART control line. Integer constant with value 0x01.
    
    See Also:
    Constant Field Values
  - DSR
```
public static final int DSR
```
    Data set ready mask bit constant for UART control line. Integer constant with value 0x02.
    
    See Also:
    Constant Field Values
  - DCD
```
public static final int DCD
```
    Data carrier detect mask bit constant for UART control line. Integer constant with value 0x04.
    
    See Also:
    Constant Field Values
  - RI
```
public static final int RI
```
    Ring indicator mask bit constant for UART control line. Integer constant with value 0x08.
    
    See Also:
    Constant Field Values
  - LOOP
```
public static final int LOOP
```
    Loop indicator mask bit constant for UART control line. Integer constant with value 0x10.
    
    See Also:
    Constant Field Values
  - RTS
```
public static final int RTS
```
    Request to send mask bit constant for UART control line. Integer constant with value 0x20.
    
    See Also:
    Constant Field Values
  - DTR
```
public static final int DTR
```
    Data terminal ready mask bit constant for UART control line. Integer constant with value 0x40.
    
    See Also:
    Constant Field Values
  - InputStream
```
public static final int InputStream
```
    The value indicating instance of SerialComInByteStream class is desired. Integer constant with value 0x32.
    
    See Also:
    Constant Field Values
  - OutputStream
```
public static final int OutputStream
```
    The value indicating instance of SerialComOutByteStream class is desired. Integer constant with value 0x33.
    
    See Also:
    Constant Field Values
  - EXP_UNBLOCKIO
```
public static final String EXP_UNBLOCKIO
```
    The exception message indicating that a blocked read method has been unblocked and made to return to caller explicitly (irrespective there was data to read or not).
    
    See Also:
    Constant Field Values
- Constructor Detail
  - SerialComManager
```
public SerialComManager()
                 throws IOException
```
    Allocates a new SerialComManager object. Identify operating system type, CPU architecture, prepares environment required for running this library, initiates extraction and loading of native libraries.
    
    The native shared library will be extracted in folder named 'sp_tuartx1' inside system/user 'temp' folder or user home folder if access to 'temp' folder is denied.
    
    On ARM Linux embedded platform it is possible to run entire 32 bit user space on a 64 bit ARMv8 processor. In such scenarios, the 32 bit and 64 bit shared libraries must not be mixed. Consider either full 32 bit user space root file system or entire root file system to be 64 bit.
    
    Please contact author of this library if you want to use CPU optimized native shared libraries in your embedded product for achieving maximum performance.
    
    Throws:
    
    IOException - if file operations on "/proc/cpuinfo" fails for Linux on ARM platform, if java system properties can not be accessed, if file "/proc/cpuinfo" can not be found for Linux on ARM platform, if native libraries are not found or can not be loaded/linked and initialized. If appropriate files/directories can not be read or written.
    
    IllegalArgumentException - if directoryPath is null, directoryPath is empty, loadedLibName is null or empty.
  - SerialComManager
```
public SerialComManager(String loadedLibName,
                String directoryPath,
                boolean createDirectory,
                boolean hotDeploy)
                 throws IOException
```
    Allocates a new SerialComManager object. Identify operating system type, CPU architecture, prepares environment required for running this library, initiates extraction and loading of native libraries.
    
    By default native shared library will be extracted in temp folder. If this constructor is used then, It extracts native shared library in the folder specified by argument directoryPath and gives library name specified by loadedLibName. If the argument createDirectory is true, it will create directory (including parent if it does not exist) as specified by directoryPath, otherwise user should make sure that this directory exist before calling this constructor.
    - Sometimes system administrator may have put some restriction on tmp/temp folder or the there may some other inevitable situations like anti-virus program causing trouble when using temp folder. This constructor will help in handling such situations.
    - Two or more absolutely independent vendors may package this library into their product's jar file. Now when using default constructor both will extract and use the same folder and library name resulting in inconsistent software. This constructor handle this situation by providing vendor specific isolated environment.
    - This may also increase security as the folder may be given specific user permissions. To extract library in directory "/home/xxx/yyy", name it lib2 and create directory yyy an example is given below.
      SerialComManager scm = new SerialComManager("lib2", "/home/xxx/yyy", true);
    - If hotDeploy is true than a different strategy is used to load the shared native libraries. This option can be true if this software is used on tomcat server for hot deployment purpose or may be during development. If two or more web applications use this library and both do the hot deployment, than loadedLibName should be different for both the applications. This will prevent unnecessary conflicts or unforeseen side effects.
    Parameters:
    loadedLibName - library name without extension (do not append .so, .dll or .dylib etc.).
    directoryPath - absolute path of directory to be used for purpose of extraction.
    createDirectory - true if directory is to be created otherwise false if given directory already exist.
    hotDeploy - true if hot deployment is to be supported otherwise false.
    
    Throws:
    
    IOException - if file operations on "/proc/cpuinfo" fails for Linux on ARM platform, if java system properties can not be accessed, if file "/proc/cpuinfo" can not be found for Linux on ARM platform, if native libraries are not found or can not be loaded/linked and initialized. If appropriate files/directories can not be read or written.
    
    IllegalArgumentException - if directoryPath is null, directoryPath is empty, loadedLibName is null or empty.
- Method Detail
  - getLibraryVersions
```
public String getLibraryVersions()
                          throws com.serialpundit.core.SerialComException
```
    Gives library versions of java and native library implementations for serial port communication.
    
    Returns:
    Java and C library versions implementing this library.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if native library version could not be determined.
  - listAvailableComPorts
```
public String[] listAvailableComPorts()
                               throws com.serialpundit.core.SerialComException
```
    Returns all available UART style ports available on this system, otherwise an empty array of strings, if no serial style port is found in the system.
    
    This should find regular UART ports, hardware/software virtual COM ports, port server, USB-UART converter, bluetooth/3G dongles, ports connected through USB hub/expander, serial card, serial controller, pseudo terminals, printers and virtual modems etc.
    
    This method may be used to find valid serial ports for communications before opening them for writing more robust application.
    
    Note : The BIOS may ignore UART ports on a PCI card and therefore BIOS settings has to be corrected if you modified default BIOS in OS.
    
    Returns:
    Available serial ports name for windows, full path with name for Unix like OS, returns empty array if no ports are found.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
  - openComPort
```
public long openComPort(String portName,
               boolean enableRead,
               boolean enableWrite,
               boolean exclusiveOwnerShip)
                 throws com.serialpundit.core.SerialComException
```
    Opens a serial port for communication. If an attempt is made to open a port which is already opened, an exception will be thrown.
    - For Linux and Mac OS X, if exclusiveOwnerShip is true, before this method returns, the caller will either be exclusive owner or not. If the caller is successful in becoming exclusive owner than all the attempt to open the same port again will cause native code to return error. Note that a root owned process (root user) will still be able to open the port.
      For Windows the exclusiveOwnerShip must be true as it does not allow sharing COM ports. An exception is thrown if exclusiveOwnerShip is set to false. For Solaris, exclusiveOwnerShip should be set to false as of now. On Unix-like system this method uses ioctl command TIOCEXCL for exclusive access. and not lock files
    - This method will clear both input and output buffers of drivers (or operating system).
    - When the serial port is opened DTR and RTS lines will be raised by default by this library. Sometimes, DTR acts as a modem on-hook/off-hook control for other end. Modern modems are highly flexible in their dependency, working and configurations. It is best to consult modem manual. If the application design need DTR/RTS not to be asserted when port is opened custom drivers can be used or hardware can be modified for this purpose. Alternatively, if the application is to be run on Windows operating system only, then modifying INF file or registry key may help in not raising DTR/RTS when port is opened. Typically in Windows DTR/RTS is raised due to enumeration sequence (serenum).
      
      In Unix jargon a dial-in TTY device is used for terminals, modems and printers etc. and requires DCD to be high for operation. When used with a modem, the port will wait for carrier before sending out the login prompt to end user. It is for this reason typically DTR of one end is connected to DSR of other end. When the terminal is turned off, any associated jobs are killed, and the user is logged out. Unlike dial-in the dial-out TTY device does not require DCD to be high. Once connection is made DCD may go high. Loss of the DCD signal may cause the jobs to be killed and the user will be automatically logged off.
    - On some hardware when opening a serial port TXD, RXD, RTS or DTR lines may show glitch which may unintentionally trigger other end. This may be due to hardware or a driver bug.
    This method is thread safe.
    Parameters:
    portName - name of the port to be opened for communication.
    enableRead - allows application to read bytes from this port.
    enableWrite - allows application to write bytes to this port.
    exclusiveOwnerShip - application wants to become exclusive owner of this port or not.
    
    Returns:
    handle of the port successfully opened.
    
    Throws:
    
    IllegalStateException - if trying to become exclusive owner when port is already opened.
    
    IllegalArgumentException - if portName is null or invalid length, or if both enableRead and enableWrite are set to false, if trying to open port in Windows without being exclusive owner.
    
    com.serialpundit.core.SerialComException - if the port can be opened for some reason.
  - closeComPort
```
public boolean closeComPort(long handle)
                     throws com.serialpundit.core.SerialComException
```
    Close the serial port. Application should unregister listeners if it has registered any before calling this method.
    
    DTR line is dropped when port is closed.
    
    If a blocking operation is in progress like readBytesBlocking() etc. than first such operation must be unblocked and then only closeComPort() should be called. It is invalid application design to violate this rule.
    
    This method is thread safe.
    
    Parameters:
    handle - of the port to be closed.
    
    Returns:
    Return true if the serial port is closed.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid handle is passed or when it fails in closing the port.
    
    IllegalStateException - if application tries to close port while data/event listeners, or input/output byte streams exist.
  - writeBytes
```
public int writeBytes(long handle,
             byte[] buffer,
             int delay)
               throws com.serialpundit.core.SerialComException
```
    This method writes bytes from the specified byte type buffer. If the method returns false, the application should try to re-send bytes. The data has been transmitted out of serial port when this method returns.
    - When using flow control, if the transmission has been stopped because other serial port's buffer is getting full, this method may return 0, indicating that no data bytes were sent out of serial port.
    - If large amount of data need to be written, it is advisable to break it into chunks of data of size for example 2KB each.
    - Writing empty buffer i.e. zero length array is not allowed.
    - It should be noted that on Linux system reading from the terminal after a disconnect causes an end-of-file condition, and writing causes an EIO error to be returned. The terminal device must be closed and reopened to clear the condition.
    - The delay parameter may be used where explicit flow control is not implemented and the firmware is not fast enough to accommodate large and fast data sent to serial device. To control speed and amount of data sent to serial device either add delay between successive bytes or add delay after host has sent some particular number of bytes.
    Parameters:
    handle - handle of the opened port on which to write bytes.
    buffer - byte type buffer containing bytes to be written to port.
    delay - time gap (in milliseconds) between transmitting two successive bytes.
    
    Returns:
    number of bytes written.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
    
    IllegalArgumentException - if buffer is null or delay is negative.
  - writeBytes
```
public int writeBytes(long handle,
             byte[] buffer)
               throws com.serialpundit.core.SerialComException
```
    Utility method to call writeBytes without delay between successive bytes.
    
    The writeBytes(handle, buffer) method for class SerialComManager has the same effect as:
    
    writeBytes(handle, buffer, 0)
    
    Parameters:
    handle - handle of the opened port on which to write bytes.
    buffer - byte type buffer containing bytes to be written to port.
    
    Returns:
    number of bytes written.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
    
    IllegalArgumentException - if buffer is null.
  - writeSingleByte
```
public int writeSingleByte(long handle,
                  byte dataByte)
                    throws com.serialpundit.core.SerialComException
```
    This method writes a single byte to the specified port. The data has been transmitted out of serial port when this method returns.
    
    Parameters:
    handle - handle of the opened port on which to write byte.
    dataByte - byte to be written to port.
    
    Returns:
    number of bytes written.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
  - writeString
```
public boolean writeString(long handle,
                  String data,
                  int delay)
                    throws com.serialpundit.core.SerialComException
```
    This method writes a string to the specified port. The library internally converts string to byte buffer. The data has been transmitted out of serial port when this method returns.
    
    Parameters:
    handle - handle of the opened port on which to write byte.
    data - the string to be send to port.
    delay - interval between two successive bytes while sending string.
    
    Returns:
    true on success false otherwise.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
    
    IllegalArgumentException - if data is null or empty string.
  - writeString
```
public boolean writeString(long handle,
                  String data,
                  Charset charset,
                  int delay)
                    throws UnsupportedEncodingException,
                           com.serialpundit.core.SerialComException
```
    This method writes a string to the specified port. The library internally converts string to byte buffer. The data has been transmitted out of serial port when this method returns.
    
    Parameters:
    handle - handle of the opened port on which to write byte.
    data - the string to be send to port.
    charset - the character set into which given string will be encoded.
    delay - time gap between transmitting two successive bytes in this string.
    
    Returns:
    true on success false otherwise.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
    
    IllegalArgumentException - if data is null or empty string.
    
    UnsupportedEncodingException - if string encoding/decoding fails.
  - writeSingleInt
```
public int writeSingleInt(long handle,
                 int data,
                 int delay,
                 SerialComManager.ENDIAN endianness,
                 SerialComManager.NUMOFBYTES numOfBytes)
                   throws com.serialpundit.core.SerialComException
```
    Different CPU and OS will have different endianness. It is therefore we handle the endianness conversion as per the requirement. If the given integer is in range −32,768 to 32,767, only two bytes will be needed. In such case we might like to send only 2 bytes to serial port. On the other hand application might be implementing some custom protocol so that the data must be 4 bytes (irrespective of its range) in order to be interpreted correctly by the receiver terminal. This method assumes that integer value can be represented by 32 or less number of bits. On x86_64 architecture, loss of precision will occur if the integer value is of more than 32 bit.
    
    The data has been transmitted physically out of serial port when this method returns.
    
    In java numbers are represented in 2's complement, so number 650 whose binary representation is 0000001010001010 is printed byte by byte, then will be printed as 1 and -118, because 10001010 in 2's complement is negative number.
    
    Parameters:
    handle - handle of the opened port on which to write byte.
    data - an integer number to be sent to port.
    delay - interval between two successive bytes .
    endianness - big or little endian sequence to be followed while sending bytes representing this integer.
    numOfBytes - number of bytes this integer can be represented in.
    
    Returns:
    number of bytes written.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
    
    IllegalArgumentException - if endianness or numOfBytes is null.
  - writeIntArray
```
public int writeIntArray(long handle,
                int[] buffer,
                int delay,
                SerialComManager.ENDIAN endianness,
                SerialComManager.NUMOFBYTES numOfBytes)
                  throws com.serialpundit.core.SerialComException
```
    This method send an array of integers on the specified port. The data has been transmitted out of serial port when this method returns.
    
    Parameters:
    handle - handle of the opened port on which to write byte.
    buffer - an array of integers to be sent to port.
    delay - interval between two successive bytes .
    endianness - big or little endian sequence to be followed while sending bytes representing this integer.
    numOfBytes - number of bytes this integer can be represented in.
    
    Returns:
    number of bytes written.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
    
    IllegalArgumentException - if endianness or numOfBytes is null.
  - writeBytesDirect
```
public int writeBytesDirect(long handle,
                   ByteBuffer buffer,
                   int offset,
                   int length)
                     throws com.serialpundit.core.SerialComException
```
    Writes the bytes from the given direct byte buffer using facilities of the underlying JVM and operating system. When this method returns data would have sent out of serial port physically.
    
    Consider using this method when developing applications based on Bluetooth serial port profile or applications like printing document using printer.
    
    This method does not modify the direct byte buffer attributes position, capacity, limit and mark. The application design is expected to take care of this as and when required in appropriate manner. Further, this method does not consume or modify the data in the given buffer.
    
    Parameters:
    handle - handle of the serial port on which to write bytes.
    buffer - direct byte buffer containing bytes to be written to port.
    offset - location from where to start sending data out of serial port.
    length - number of bytes from offset to sent to serial port.
    
    Returns:
    number of bytes sent to serial port.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
    
    IllegalArgumentException - if buffer is null, or if position or limit is negative, or if given buffer is not direct byte buffer, or if length > (buffer.capacity() - offset).
  - writeBytesBlocking
```
public int writeBytesBlocking(long handle,
                     byte[] buffer,
                     long context)
                       throws com.serialpundit.core.SerialComException
```
    Write bytes from given buffer to the given handle in blocking mode.
    - Writing empty buffer i.e. zero length array is not allowed.
    - Same context should not be used for both reading and writing.
    Parameters:
    handle - handle of the opened port on which to write bytes.
    buffer - byte type buffer containing bytes to be written to port.
    context - context value obtained form call to createBlockingIOContext method.
    
    Returns:
    number of bytes sent to serial port.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
    
    IllegalArgumentException - if buffer is null.
  - readBytesDirect
```
public int readBytesDirect(long handle,
                  ByteBuffer buffer,
                  int offset,
                  int length)
                    throws com.serialpundit.core.SerialComException
```
    Reads the bytes from the serial port into the given direct byte buffer using facilities of the underlying JVM and operating system.
    
    This method does not modify the direct byte buffer attributes position, capacity, limit and mark. The application design is expected to take care of this as and when required in appropriate manner.
    
    Parameters:
    handle - handle of the serial port from which to read data bytes.
    buffer - direct byte buffer into which data bytes will be placed.
    offset - location in byte buffer from which to start saving data.
    length - number of bytes from offset to read in buffer.
    
    Returns:
    number of bytes read from serial port, 0 if length is 0.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
    
    IllegalArgumentException - if buffer is null, or if position or limit is negative, or if given buffer is not direct byte buffer.
  - createBlockingIOContext
```
public long createBlockingIOContext()
                             throws com.serialpundit.core.SerialComException
```
    Prepares a context that should be passed to readBytesBlocking, writeBytesBlocking, readBytes, unblockBlockingIOOperation and destroyBlockingIOContext methods.
    
    Returns:
    context value that should be passed to destroyBlockingIOContext, readBytesBlocking and writeBytesBlocking methods.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
  - unblockBlockingIOOperation
```
public boolean unblockBlockingIOOperation(long context)
                                   throws com.serialpundit.core.SerialComException
```
    Unblocks any blocked operation if it exist. This causes closing of serial port possible gracefully and return the worker thread that called blocking read/write to return and proceed as per application design.
    
    Parameters:
    context - context obtained from call to createBlockingIOContext method for blocking I/O operations.
    
    Returns:
    true if blocked operation was unblocked successfully.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
  - destroyBlockingIOContext
```
public boolean destroyBlockingIOContext(long context)
                                 throws com.serialpundit.core.SerialComException
```
    Destroys the context that was created by a call to createBlockingIOContext method for blocking I/O operations uses.
    
    Parameters:
    context - context obtained from call to createBlockingIOContext method for blocking I/O operations.
    
    Returns:
    true if the context gets destroyed successfully.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
  - readBytesBlocking
```
public byte[] readBytesBlocking(long handle,
                       int byteCount,
                       long context)
                         throws com.serialpundit.core.SerialComException
```
    Read specified number of bytes from given serial port and stay blocked till bytes arrive at serial port.
    
    1. If data is read from serial port, array of bytes containing data is returned.
    
    2. If there was no data in serial port to read, null is returned. Note that this case is not possible however for blocking read call.
    - The number of bytes to read must be greater than or equal to 1 and less than or equal to 2048 (1 <= byteCount <= 2048). This method may return less than the requested number of bytes due to reasons like, there is less data in operating system buffer (serial port) or operating system returned less data which is also legal.
    - When no data at serial port has arrived and application wishes to unblock and return the control to the caller for example because application now wants to close the serial port, it should call unblockBlockingIOOperation() passing the same context to this method.
    - If using blocking context, it is advised to catch SerialComException exception and check if this contain message SerialComManager.EXP_UNBLOCKIO. This message indicates that no error occurred while waiting/reading data from serial port but application has explicitly asked to return.
    Parameters:
    handle - of the serial port from which to read bytes.
    byteCount - number of bytes to read from serial port.
    context - context obtained by a call to createBlockingIOContext method.
    
    Returns:
    array of bytes read from port if read succeeds or null if read fails.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs or if byteCount is greater than 2048.
  - readBytes
```
public byte[] readBytes(long handle,
               int byteCount)
                 throws com.serialpundit.core.SerialComException
```
    Read specified number of data bytes from the given serial port.
    - If data is read from serial port, array of bytes containing data is returned.
    - If there was no data at serial port to read, null is returned.
    - The number of bytes to read must be greater than or equal to 1 and less than or equal to 2048 (1 <= byteCount <= 2048). This method may return less than the requested number of bytes due to reasons like, there is less data in operating system buffer (serial port) or operating system returned less data which is also legal.
    Parameters:
    handle - of the serial port from which to read bytes.
    byteCount - number of bytes to read from serial port.
    
    Returns:
    array of bytes read from port or null.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs or if byteCount is greater than 2048.
  - readBytes
```
public byte[] readBytes(long handle)
                 throws com.serialpundit.core.SerialComException
```
    If user does not specify any count, library try to read DEFAULT_READBYTECOUNT (1024 bytes) bytes as default value.
    
    It has same effect as readBytes(handle, 1024)
    
    Parameters:
    handle - of the port from which to read bytes.
    
    Returns:
    array of bytes read from port or null.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
  - readString
```
public String readString(long handle,
                int byteCount)
                  throws com.serialpundit.core.SerialComException
```
    Reads data from serial port and converts it into string.
    
    It constructs a new string by decoding the specified array of bytes using the platform's default character set. The length of the new string is a function of the character set, and hence may not be equal to the length of the byte array read from serial port.
    
    Parameters:
    handle - of port from which to read bytes.
    byteCount - number of bytes to read from this port.
    
    Returns:
    string constructed from data read from serial port or null.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs or if byteCount is greater than 2048.
  - readString
```
public String readString(long handle)
                  throws com.serialpundit.core.SerialComException
```
    This method reads data from serial port and converts it into string.
    
    It Constructs a new string by decoding the specified array of bytes using the platform's default character set. The length of the new string is a function of the charset, and hence may not be equal to the length of the byte array read from serial port.
    
    Note that the length of data bytes read using this method can not be greater than DEFAULT_READBYTECOUNT i.e. 1024.
    
    Parameters:
    handle - of the port from which to read bytes.
    
    Returns:
    string constructed from data read from serial port or null.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
  - readSingleByte
```
public byte[] readSingleByte(long handle)
                      throws com.serialpundit.core.SerialComException
```
    This is a utility method to read a single byte from serial port.
    
    Its effect is same as readBytes(handle, 1)
    
    Parameters:
    handle - of the port from which to read byte.
    
    Returns:
    array of length 1 representing 1 byte data read from serial port or null.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
  - readBytes
```
public int readBytes(long handle,
            byte[] buffer,
            int offset,
            int length,
            long context,
            SerialComLineErrors lineErr)
              throws com.serialpundit.core.SerialComException
```
    Reads data bytes from serial port into given buffer also providing info about framing, parity etc errors. This method may be used in application design which needs to poll serial port continuously for presence of data.
    - This method can be used in blocking mode or non-blocking mode. If context is -1, this method will not block. For blocking behavior pass context value obtained from a call to createBlockingIOContext method. If a valid context is passed, this method will block until there is data to read from serial port.
    - When no data at serial port has arrived and application wishes to unblock and return the control to the caller for example because application now wants to close the serial port, it should call unblockBlockingIOOperation() passing the same context which is passed to this method.
    - If using blocking context, it is advised to catch SerialComException exception and check if this contain message SerialComManager.EXP_UNBLOCKIO. This message indicates that no error occurred while waiting/reading data from serial port but application has explicitly asked to return.
    - To find if a framing or parity errors has happened while receiving data or not, call methods as appropriate on lineErr reference.
    Parameters:
    handle - of the port from which to read data bytes.
    buffer - data byte buffer in which bytes from serial port will be saved.
    offset - index in given byte array at which first data byte will be placed.
    length - number of bytes to read into given buffer (0 <= length <= 2048).
    context - context obtained by call to createBlockingIOContext method for blocking behavior or -1 for non-blocking behavior.
    lineErr - instance of class SerialComLineErrors that will carry line error information or null if parity/framing errors should not be checked.
    
    Returns:
    number of bytes read from serial port.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an I/O error occurs.
    
    NullPointerException - if buffer is null.
    
    IndexOutOfBoundsException - if offset is negative, length is negative, or length is greater than buffer.length - offset.
  - configureComPortData
```
public boolean configureComPortData(long handle,
                           SerialComManager.DATABITS dataBits,
                           SerialComManager.STOPBITS stopBits,
                           SerialComManager.PARITY parity,
                           SerialComManager.BAUDRATE baudRate,
                           int custBaud)
                             throws com.serialpundit.core.SerialComException
```
    This method configures the rate at which communication will occur and the format of UART frame. This method must be called before configureComPortControl method.
    - [1] Most of the DTE/DCE (hardware) does not support different baud rates for transmission and reception and therefore this method takes only single value applicable to both transmission and reception.
    - All serial devices/drivers/operating systems does not support all the baud rates (maximum change in signal per second), stop bits, data bits etc. Please consult hardware and software manuals as appropriate.
    - If parity is enabled, the parity bit will be removed from UART frame before passing it to this library. All hardware/driver/operating systems does not support all parity. Please check your manual. Note that the datasheet of some uart devices does not mention that mark/space parity is supported, however they properly support it as mentioned in their register setting details. If a parity error is detected in received data, the error is not cleared until LSR/LCR registers are read by driver. So if parity detection is used application should enquire its status.
    - Some USB-UART devices supports non-standard baudrates. How to set these baudrate is device/driver and operating system specific.
    Parameters:
    handle - of opened port to which this configuration applies to.
    dataBits - number of data bits in one frame (refer DATABITS enum in SerialComManager class for this).
    stopBits - number of stop bits in one frame (refer STOPBITS enum in SerialComManager class for this).
    parity - of the frame (refer PARITY enum in SerialComManager class for this).
    baudRate - of the frame (refer BAUDRATE enum in SerialComManager class for this).
    custBaud - custom baudrate if the desired rate is not included in BAUDRATE enum.
    
    Returns:
    true on success false otherwise.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid handle is passed or an error occurs in configuring the port.
    
    IllegalArgumentException - if dataBits or stopBits or parity or baudRate is null, or if custBaud is zero or negative.
  - configureComPortControl
```
public boolean configureComPortControl(long handle,
                              SerialComManager.FLOWCONTROL flowctrl,
                              char xon,
                              char xoff,
                              boolean ParFraError,
                              boolean overFlowErr)
                                throws com.serialpundit.core.SerialComException
```
    This method configures the way data communication will be controlled between DTE and DCE. This specifies flow control and actions that will be taken when an error is encountered in communication.
    - Some serial devices does not support some flow controls scheme. Please refer to their manuals.
    - It is advisable not to use same XON and XOFF character as opertaing system framework or driver may check for special characters one after the other and will process them. For example while processing data received at serial port, if driver sees XON it will instruct device to start transmission. But when moving further in the processing function, it checks for XOFF and sees that XOFF character has been received and therefore it will stop the transmission.
    Parameters:
    handle - of opened port to which need to be configured.
    flowctrl - flow control, how data flow will be controlled (refer FLOWCONTROL enum for this).
    xon - character representing on condition if software flow control is used.
    xoff - character representing off condition if software flow control is used.
    ParFraError - true if parity and frame errors are to be checked false otherwise.
    overFlowErr - true if overflow error is to be detected false otherwise.
    
    Returns:
    true on success false otherwise.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid handle is passed or an error occurs in configuring the port.
    
    IllegalArgumentException - if flowctrl is null.
  - getCurrentConfiguration
```
public String[] getCurrentConfiguration(long handle)
                                 throws com.serialpundit.core.SerialComException
```
    This method gives currently applicable settings associated with particular serial port. The values are bit mask so that application can manipulate them to get required information.
    
    For Unix-like OS the order is : c_iflag, c_oflag, c_cflag, c_lflag, c_line, c_cc[0], c_cc[1], c_cc[2], c_cc[3] c_cc[4], c_cc[5], c_cc[6], c_cc[7], c_cc[8], c_cc[9], c_cc[10], c_cc[11], c_cc[12], c_cc[13], c_cc[14], c_cc[15], c_cc[16], c_ispeed and c_ospeed.
    
    For Windows OS the order is :DCBlength, BaudRate, fBinary, fParity, fOutxCtsFlow, fOutxDsrFlow, fDtrControl, fDsrSensitivity, fTXContinueOnXoff, fOutX, fInX, fErrorChar, fNull, fRtsControl, fAbortOnError, fDummy2, wReserved, XonLim, XoffLim, ByteSize, Parity, StopBits, XonChar, XoffChar, ErrorChar, StopBits, EvtChar, wReserved1.
    
    Parameters:
    handle - of the opened port.
    
    Returns:
    array of string giving configuration.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid handle is passed or an error occurs while reading current settings.
  - setRTS
```
public boolean setRTS(long handle,
             boolean enabled)
               throws com.serialpundit.core.SerialComException
```
    This method assert/de-assert RTS line of serial port. Set "true" for asserting signal, false otherwise. This changes the state of RTS line electrically.
    - RTS and DTR lines can be asserted or de-asserted even when using no flow control on serial port.
    - The RS-232 standard defines the voltage levels that correspond to logical one and logical zero levels for the data transmission and the control signal lines. Valid signals are either in the range of +3 to +15 volts or the range −3 to −15 volts with respect to the ground/common pin; consequently, the range between −3 to +3 volts is not a valid RS-232 level.
    - In asserted condition, voltage at pin number 7 (RTS signal) will be greater than 3 volts. Voltage 5.0 volts was observed when using USB-UART converter : http://www.amazon.in/Bafo-USB-Serial-Converter-DB9/dp/B002SCRCDG.
    - On some hardware IC, signals may be active low and therefore for actual voltage datasheet should be consulted. Also please check if the driver supports setting RTS/DTR lines or not.
    Parameters:
    handle - of the opened port.
    enabled - if true RTS will be asserted and vice-versa.
    
    Returns:
    true on success.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if system is unable to complete requested operation.
  - setDTR
```
public boolean setDTR(long handle,
             boolean enabled)
               throws com.serialpundit.core.SerialComException
```
    This method assert/de-assert DTR line of serial port. Set "true" for asserting signal, false otherwise. This changes the state of RTS line electrically.
    - RTS and DTR lines can be asserted or de-asserted even when a serial port is configured as 'flow control none'.
    - It is possible to establish PPP connections to transmit binary data over a two (or more) wire interface with full handshaking and modem control signaling if the driver is configured for this. Refer application note from FTDI for details : AN232B-09 Using the Modem Emulation Mode in FTDI's VCP Driver.
    - If the DTR/DSR line is not used DTR can be connected to DSR locally like a loop back connection. The vendor written firmware treats change in DSR line as hardware interrupt and executes interrupt service routine. The application firmware can lower/raise the DTR line whenever needed.
    Parameters:
    handle - of the opened port.
    enabled - if true DTR will be asserted and vice-versa.
    
    Returns:
    true on success.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if system is unable to complete requested operation.
  - registerDataListener
```
public boolean registerDataListener(long handle,
                           ISerialComDataListener dataListener)
                             throws com.serialpundit.core.SerialComException
```
    This method associate a data looper with the given listener. This looper will keep delivering new data whenever it is made available from native data collection and dispatching subsystem. Note that listener will start receiving new data, even before this method returns.
    
    Application (listener) should implement ISerialComDataListener and override onNewSerialDataAvailable method.
    
    The SerialPundit can manage upto 1024 listeners corresponding to 1024 port handles. Application should not register data listener more than once for the same port otherwise it will lead to inconsistent state.
    
    This method is thread safe.
    
    Parameters:
    handle - of the serial port for which given listener will listen for availability of data bytes.
    dataListener - instance of class which implements ISerialComDataListener interface.
    
    Returns:
    true on success false otherwise.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid handle passed, handle is null or data listener already exist for this handle.
    
    IllegalArgumentException - if dataListener is null.
  - unregisterDataListener
```
public boolean unregisterDataListener(long handle,
                             ISerialComDataListener dataListener)
                               throws com.serialpundit.core.SerialComException
```
    This method destroys complete java and native looper subsystem associated with this particular data listener. This has no effect on event looper subsystem. This method returns only after native thread has been terminated successfully.
    
    This method is thread safe.
    
    Parameters:
    handle - handle of the serial port for which this data listener was registered.
    dataListener - instance of class which implemented ISerialComDataListener interface.
    
    Returns:
    true on success false otherwise.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if null value is passed in dataListener field.
    
    IllegalArgumentException - if dataListener is null.
  - registerLineEventListener
```
public boolean registerLineEventListener(long handle,
                                ISerialComEventListener eventListener)
                                  throws com.serialpundit.core.SerialComException
```
    This method associate a event looper with the given listener. This looper will keep delivering new event whenever it is made available from native event collection and dispatching subsystem.
    
    Application (listener) should implement ISerialComEventListener and override onNewSerialEvent method.
    
    By default all four events are dispatched to listener. However, application can mask events through setEventsMask() method. In current implementation, native code sends all the events irrespective of mask and we actually filter them in java layers, to decide whether this should be sent to application or not (as per the mask set by setEventsMask() method).
    
    Before calling this method, make sure that port has been configured for hardware flow control using configureComPortControl method. Application should not register event listener more than once for the same port otherwise it will lead to inconsistent state.
    
    This method is thread safe.
    
    Parameters:
    handle - of the port opened.
    eventListener - instance of class which implements ISerialComEventListener interface.
    
    Returns:
    true on success false otherwise.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid handle passed, handle is null or event listener already exist for this handle.
    
    IllegalArgumentException - if eventListener is null.
  - unregisterLineEventListener
```
public boolean unregisterLineEventListener(long handle,
                                  ISerialComEventListener eventListener)
                                    throws com.serialpundit.core.SerialComException
```
    This method destroys complete java and native looper subsystem associated with this particular event listener. This has no effect on data looper subsystem.
    
    This method is thread safe.
    
    Parameters:
    handle - handle for which this listener was registered.
    eventListener - instance of class which implemented ISerialComEventListener interface.
    
    Returns:
    true on success false otherwise.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if an error occurs.
    
    IllegalArgumentException - if eventListener is null.
  - pauseListeningEvents
```
public boolean pauseListeningEvents(ISerialComEventListener eventListener)
                             throws com.serialpundit.core.SerialComException
```
    This pauses delivering events to application. The events kept accumulating in queue.
    
    Parameters:
    eventListener - instance of class which implemented ISerialComEventListener interface.
    
    Returns:
    true on success false otherwise.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if null is passed for eventListener field.
    
    IllegalArgumentException - if eventListener is null.
  - resumeListeningEvents
```
public boolean resumeListeningEvents(ISerialComEventListener eventListener)
                              throws com.serialpundit.core.SerialComException
```
    Resume delivering events kept in queue to application.
    
    Parameters:
    eventListener - is an instance of class which implements ISerialComEventListener.
    
    Returns:
    true on success false otherwise.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if error occurs.
    
    IllegalArgumentException - if eventListener is null.
  - fineTuneReadBehaviour
```
public boolean fineTuneReadBehaviour(long handle,
                            int vmin,
                            int vtime,
                            int rit,
                            int rttm,
                            int rttc)
                              throws com.serialpundit.core.SerialComException
```
    This method gives more fine tune control to application for tuning performance and behavior of read operations to leverage OS specific facility for read operation. The read operations can be optimized for receiving for example high volume data speedily or low volume data but received in burst mode.
    
    If more than one client has opened the same port, then all the clients will be affected by new settings. When this method is called application should make sure that previous read or write operation is not in progress.
    
    Under multithreading scenarios, if thread is blocked on read method due to timeout configured using this method and other thread tries to close port, the read method may cause the the thread which called read methid not to return. It is therefore either timeout should be kept short or two threads must be synchronized etc.
    
    [1] Time out for read call for unix like OS can be set using vtime. Use formula vtime = time out in milliseconds / 100. For example to wait for 100 milliseconds, vtime = 1 and vmin = 0.
    
    Parameters:
    handle - of the opened port.
    vmin - c_cc[VMIN] field of termios structure (applicable for unix like OS only).
    vtime - c_cc[VTIME] field of termios structure (10th of a second, applicable for unix like OS only).
    rit - ReadIntervalTimeout field of COMMTIMEOUTS structure (applicable for windows OS only).
    rttm - ReadTotalTimeoutMultiplier field of COMMTIMEOUTS structure (applicable for windows OS only).
    rttc - ReadTotalTimeoutConstant field of COMMTIMEOUTS structure (applicable for windows OS only).
    
    Returns:
    true on success false otherwise.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if wrong handle is passed or operation can not be done successfully.
    
    IllegalArgumentException - if invalid combination of arguments is passed.
  - setEventsMask
```
public boolean setEventsMask(ISerialComEventListener eventListener,
                    int newMask)
                      throws com.serialpundit.core.SerialComException
```
    Defines for which line events registered event listener will be called.
    
    In future we may shift modifying mask in the native code itself, so as to prevent JNI transitions. This filters what events should be sent to application. Note that, although we sent only those event for which user has set mask, however native code send all the events to java layer as of now.
    
    Parameters:
    eventListener - instance of class which implemented ISerialComEventListener interface.
    
    Returns:
    true on success false otherwise.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid listener is passed.
    
    IllegalArgumentException - if eventListener is null.
  - getEventsMask
```
public int getEventsMask(ISerialComEventListener eventListener)
                  throws com.serialpundit.core.SerialComException
```
    This method return currently applicable mask for events on serial port.
    
    Parameters:
    eventListener - instance of class which implemented ISerialComEventListener interface.
    
    Returns:
    an integer containing bit fields representing mask.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if null or wrong listener is passed.
    
    IllegalArgumentException - if eventListener is null.
  - clearPortIOBuffers
```
public boolean clearPortIOBuffers(long handle,
                         boolean clearRxBuffer,
                         boolean clearTxBuffer)
                           throws com.serialpundit.core.SerialComException
```
    Discards data sent to port but not transmitted, or data received but not read. Some device/OS/driver might not have support for this, but most of them may have. If there is some data to be pending for transmission, it will be discarded and therefore no longer sent. If the application wants to make sure that all data has been transmitted before discarding anything, it must first flush data and then call this method.
    
    Parameters:
    handle - of the opened port.
    clearRxBuffer - if true receive buffer will be cleared otherwise will be left untouched.
    clearTxBuffer - if true transmit buffer will be cleared otherwise will be left untouched.
    
    Returns:
    true on success.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid handle is passed or operation can not be completed successfully.
    
    IllegalArgumentException - if both purgeTxBuffer and purgeRxBuffer are false.
  - sendBreak
```
public boolean sendBreak(long handle,
                int duration)
                  throws com.serialpundit.core.SerialComException
```
    Assert a break condition on the specified port for the duration expressed in milliseconds. If the line is held in the logic low condition (space in UART jargon) for longer than a character time, this is a break condition that can be detected by the UART.
    - A "break condition" occurs when the receiver input is at the "space" level for longer than some duration of time, typically, for more than a character time. This is not necessarily an error, but appears to the receiver as a character of all zero bits with a framing error. The term "break" derives from current loop Signaling, which was the traditional signaling used for tele-typewriters. The "spacing" condition of a current loop line is indicated by no current flowing, and a very long period of no current flowing is often caused by a break or other fault in the line.
    - Recognizing break condition on line is the responsibility of the UART IC, but if for some reason (such as a limited UART that does not implement this functionality) the UART fails to do so, reception of a break will manifest itself as a large number of framing errors. Also sometimes default drivers built into operating system may not provide break detection facility.
    - If the duration parameter is 0, it will result in fastest way this library can set and unset break condition.
    - All UART devices (or driver) may not support all break timings. For example CP2105 can set break for from 1 to 125 ms or for infinite time. Developers should consult data sheet to know device capabilities. Sometimes hardware may also report break as all 0 bits byte data.
    - In some application designs break signals can be used for packet synchronization. For example; presence of break indicate start of packet or end of packet. If the host processor is in sleep mode, some UART hardware may wake the host processor when they detect a break condition or start bit.
    - Dedicated ICs like ELM627 can be used to detect break condition and toggle GPIO lines which may in turn be connected to reset pin of micro-controller. Such schemes are used where the hardware can not detect break condition on line.
    Parameters:
    handle - of the opened serial port.
    duration - the time in milliseconds for which break will be active.
    
    Returns:
    true on success.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid handle is passed or operation can not be successfully completed.
    
    IllegalArgumentException - if duration is negative.
  - getInterruptCount
```
public int[] getInterruptCount(long handle)
                        throws com.serialpundit.core.SerialComException
```
    This method gives the number of interrupts on serial line that have occurred. The interrupt count is in following order in array beginning from index 0 and ending at index 11 : CTS, DSR, RING, CARRIER DETECT, RECEIVER BUFFER, TRANSMIT BUFFER, FRAME ERROR, OVERRUN ERROR, PARITY ERROR, BREAK AND BUFFER OVERRUN.
    
    This is applicable for Linux onle. For other operating systems, this will return 0 for all the indexes.
    
    Parameters:
    handle - of the port opened on which interrupts might have occurred.
    
    Returns:
    array of integers containing values corresponding to each interrupt source.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid handle is passed or operation can not be performed successfully.
  - getLinesStatus
```
public int[] getLinesStatus(long handle)
                     throws com.serialpundit.core.SerialComException
```
    Gives status of serial port's control lines as supported by underlying operating system. The sequence of status in returned array is :
    
    Linux OS : CTS, DSR, DCD, RI, LOOP, RTS, DTR respectively.
    
    MAC OS X : CTS, DSR, DCD, RI, 0, RTS, DTR respectively.
    
    Windows OS : CTS, DSR, DCD, RI, 0, 0, 0 respectively.
    
    Parameters:
    handle - of the port whose status is to be read.
    
    Returns:
    status of UART port control lines.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid handle is passed or operation can not be completed successfully.
  - findDriverServingComPort
```
public String findDriverServingComPort(String comPortName)
                                throws com.serialpundit.core.SerialComException
```
    Gives the name of the driver who is driving the given serial port. The use case scenarios are:
    - Suppose exactly same two temperature sensors are connected to system via usb-uart converters. For example 1st sensor senses ambient temperature and is connected to computer via FT232. Second temperature sensor is connected via CP2102 to computer. Now when ft232 and cp2102 is plugged into computer we do not know which /dev/ttyUSBxx belong to which sensor (usb-uart). In this case use this API to find which device node belongs to which converter. For cp2102 driver will be cp210x where as for ft232 it will be ftdi_sio.
    - If exactly same usb-uart devices are used to connected two sensors then use findComPortFromUSBAttributes API in USB module giving unique serial numbers of ft232. This will tell which device node belongs to which sensor.
    - It can be used where legacy serial ports have to be found. For example in Windows suppose there is a permanent RS232 port on mother board and a FT232 USB-UART is also attached. Let us say FT232 is COM1 and the one on mother board is COM2. Now calling this method by passing COM1 and then COM2 can easily tell that COM2 is the port we need.
    - This can also be used where two end products based on same usb-uart converter are connected to the compueter and they use different drivers.
    Parameters:
    comPortName - name only for windows (for ex; COM52), full path for unix-like os (for ex; /dev/ttyUSB0).
    
    Returns:
    name of driver serving given serial port.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if operation can not be completed successfully.
    
    IllegalArgumentException - if argument comPortName is null or is an empty string.
  - findIRQnumberForComPort
```
public String findIRQnumberForComPort(long handle)
                               throws com.serialpundit.core.SerialComException
```
    Gives the address and IRQ number associated with the given serial port. Applicable manily for serial port built into the mother board itself.
    
    Parameters:
    handle - handle of the opened serial port.
    
    Returns:
    string containing address and irq number in hexadecimal represenation.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if operation can not be completed successfully.
  - getByteCountInPortIOBuffer
```
public int[] getByteCountInPortIOBuffer(long handle)
                                 throws com.serialpundit.core.SerialComException
```
    Get number of bytes in input and output port buffers used by operating system for instance tty buffers in Unix like systems. Sequence of data in array is : Input buffer byte count, Output buffer byte count.
    
    It should be noted that some chipset specially USB to UART converters might have FIFO buffers in chipset itself. For example FT232R has internal buffers controlled by FIFO CONTROLLERS. For this reason this method should be tested carefully if application is using USB-UART converters. This is driver and OS specific scenario.
    
    Parameters:
    handle - of the opened port for which counts need to be determined.
    
    Returns:
    array containing number of bytes in input and output buffer.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid handle is passed or operation can not be completed successfully.
  - getPortName
```
public String getPortName(long handle)
                   throws com.serialpundit.core.SerialComException
```
    This method gives the port name with which given handle is associated. If the given handle is unknown to this library, null is returned. A serial port is known to this if it was opened using SerialComManager's openComPort() method.
    
    Parameters:
    handle - for which the port name is to be found.
    
    Returns:
    port name corresponding to the given handle.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid handle is passed.
  - sendFile
```
public boolean sendFile(long handle,
               File[] fileToSend,
               SerialComManager.FTPPROTO ftpProto,
               SerialComManager.FTPVAR ftpVariant,
               boolean textMode,
               ISerialComFTPProgress progressListener,
               SerialComFTPCMDAbort transferState)
                 throws IOException
```
    Send given file(s) using specified file transfer protocol.
    
    For Xmodem trasnfer the element at 0th index of fileToSend array must represent a regular file. If the length of fileToSend array is more than one, only 1st file will be sent.
    
    For Ymodem transfer, the fileToSend array should contain all the files to be transffered to receiver end where all the elements in fileToSend array represent regular files.
    
    Xmodem protocol is widely used for flashing executable images in microcontroller via UART. For example the secondary bootloader in LPC2000 can update the user application code in on chip flash via UART with 1K XMODEM protocol. Xmodem protocol is also used for taling to network routers.
    
    If you want to make user defined firmware, consider creating an IDE where end user can place widget, define layout etc. graphically and then when he clicks on save button a firmware hex file gets generated. This file is then flashed into end product as firmware.
    
    Parameters:
    handle - of the port on which file is to be sent.
    fileToSend - File instance representing file to be sent.
    ftpProto - file transfer protocol to use for communication over serial port.
    ftpVariant - variant of file transfer protocol to use.
    textMode - if true file will be sent as text file (ASCII mode), if false file will be sent as binary file. The text file must contain only valid ASCII characters.
    progressListener - object of class which implements ISerialComXmodemProgress interface and is interested in knowing how many blocks have been sent to file receiver till now. If progressListener is null, update will not be delivered to application.
    transferState - if application wish to abort sending file at instant of time due to any reason, it can call abortTransfer method on this object. If the application does not wishes to abort sending file explicitly transferState can be null.
    
    Returns:
    true on success, false if application instructed to abort.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid handle is passed, if receiver sent abort command.
    
    SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file.
    
    FileNotFoundException - if the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading.
    
    SerialComTimeOutException - if timeout occurs as per file transfer protocol.
    
    IOException - if error occurs while reading data from file to be sent.
    
    IllegalArgumentException - if fileToSend or ftpProto or ftpVariant or ftpMode argument is null.
  - receiveFile
```
public boolean receiveFile(long handle,
                  File fileToReceive,
                  SerialComManager.FTPPROTO ftpProto,
                  SerialComManager.FTPVAR ftpVariant,
                  boolean textMode,
                  ISerialComFTPProgress progressListener,
                  SerialComFTPCMDAbort transferState)
                    throws IOException
```
    Receives file using specified file transfer protocol.
    
    For Xmodem transfer the fileToReceive must represent a regular file. For Ymodem transfer fileToReceive must represent a directory in which received files will be saved.
    
    Parameters:
    handle - of the serial port on which file is to be sent.
    fileToReceive - File instance representing file/folder to be sent.
    ftpProto - file transfer protocol (FTPPROTO_XXX) to use for communication over serial port.
    ftpVariant - variant of file transfer protocol (FTPVAR_XXX) to use.
    textMode - if true file will be received as text file (ASCII mode), if false file will be received as binary file.
    progressListener - object of class which implements ISerialComXmodemProgress interface and is interested in knowing how many blocks have been received from file sender till now. If progressListener is null, update will not be delivered to application.
    transferState - if application wish to abort receiving file at instant of time due to any reason, it can call abortTransfer method on this object. If the application does not wishes to abort receiving file explicitly transferState can be null.
    
    Returns:
    true on success, false if application instructed to abort.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if invalid handle is passed, if sender sent abort command.
    
    SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file.
    
    FileNotFoundException - if the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading.
    
    SerialComTimeOutException - if timeout occurs as per file transfer protocol.
    
    IOException - if error occurs while reading data from file to be sent.
    
    IllegalArgumentException - if fileToReceive or ftpProto or ftpVariant or ftpMode argument is null.
  - getIOStreamInstance
```
public ISerialIOStream getIOStreamInstance(int streamType,
                                  long handle,
                                  SerialComManager.SMODE streamMode)
                                    throws com.serialpundit.core.SerialComException
```
    Factory method to create stream of type specified by streamType in blocking or non-blocking mode.
    
    If streamType is SerialComManager.OutputStream, an instance of class SerialComOutByteStream is returned. If streamType is SerialComManager.InputStream, an instance of class SerialComInByteStream is returned.
    
    If streamMode is SMODE.NONBLOCKING, read/write to serial port is non-blocking. If streamMode is SMODE.BLOCKING, read/write to serial port is blocking.
    
    Parameters:
    streamType - one of the values; SerialComManager.OutputStream or SerialComManager.InputStream.
    handle - handle of the opened serial port which this stream will wrap internally.
    streamMode - enum value SMODE.BLOCKING or SMODE.NONBLOCKING.
    
    Returns:
    instance of stream (SerialComInByteStream/SerialComOutByteStream) as per given streamType.
    
    Throws:
    
    com.serialpundit.core.SerialComException - if input stream already exist for this handle or invalid handle is passed.
    
    IllegalArgumentException - if streamMode is null or invalid streamType is passed.
  - getVendorLibFromFactory
```
public SerialComVendorLib getVendorLibFromFactory(int vendorLibIdentifier,
                                         String libDirectory,
                                         String vlibName)
                                           throws IOException
```
    Gives an instance of the class which implements API defined by vendor in their propriety library.
    
    For example; if vendorLibIdentifier is SerialComVendorLib.VLIB_FTDI_D2XX, an instance of SerialComFTDID2XX class is returned.
    
    Parameters:
    vendorLibIdentifier - one of the constant VLIB_XXXX_XXXX in SerialComVendorLib class.
    libDirectory - absolute directory path where vendor library is placed.
    vlibName - full name of the vendor library (for ex. libftd2xx.so.1.1.12).
    
    Returns:
    an object of SerialComVendorLib class on which vendor specific API calls can be made otherwise null.
    
    Throws:
    
    IOException - if java system properties can not be accessed, if invalid vendorLibIdentifier is passed. if native libraries are not found or can not be loaded/linked, if libDirectory does not exist, or is not a regular directory or is not writtable, If native library can not be initialized.
    
    IllegalArgumentException - if vlibName is null or empty string.
  - getSerialComPortMapperInstance
```
public SerialComPortMapper getSerialComPortMapperInstance(String directoryPath,
                                                 String loadedLibName)
                                                   throws com.serialpundit.core.SerialComException
```
    Allocate, initialize and return an instance of SerialComPortMapper class on whom APIs can be called to map or unmap a serial port alias.
    
    This method will extract native library in directory as specified by directoryPath argument or default directory will be used if directoryPath is null. The native library loaded will be given name as specified by loadedLibName argument or default name will be used if loadedLibName is null.
    
    Parameters:
    directoryPath - absolute path of directory to be used for extraction.
    loadedLibName - library name without extension (do not append .so, .dll or .dylib etc.).
    
    Returns:
    instance of SerialComPortMapper class on which various methods can be invoked.
    
    Throws:
    
    IOException - if file operations on "/proc/cpuinfo" fails for Linux on ARM platform, if java system properties can not be accessed, if file "/proc/cpuinfo" can not be found for Linux on ARM platform, if native libraries are not found or can not be loaded/linked. If appropriate files/directories can not be read or written, If native library can not be initialized.
    
    IllegalArgumentException - if directoryPath is null, directoryPath is empty, loadedLibName is null or empty.
    
    com.serialpundit.core.SerialComException
  - getSerialComDBReleaseInstance
```
public SerialComDBRelease getSerialComDBReleaseInstance(String directoryPath,
                                               String loadedLibName)
                                                 throws IOException
```
    Allocate, initialize and return an instance of SerialComDBRelease class on whom APIs can be called to release COM ports in use. This methed is applicable for Windows operating system only.
    
    The Windows operating system maintains a database of all COM ports. This database is typically supports com port numbers from 1(COM1) to 256(COM256). This database can get exhausted for example if more than 256 USB-UART devices are connected one after the other in system. This generally happens in factory testing environment. Using the APIs in SerialComDBRelease class, test application can manage the port assignment and its release programatically making production testing faster and less cumbersome.
    
    This method will extract native library in directory as specified by directoryPath argument or default directory will be used if directoryPath is null. The native library loaded will be given name as specified by loadedLibName argument or default name will be used if loadedLibName is null.
    
    Parameters:
    directoryPath - absolute path of directory to be used for extraction.
    loadedLibName - library name without extension (do not append .so, .dll or .dylib etc.).
    
    Returns:
    instance of SerialComDBRelease on which various methods can be invoked.
    
    Throws:
    
    IOException - if file operations on "/proc/cpuinfo" fails for Linux on ARM platform, if java system properties can not be accessed, if file "/proc/cpuinfo" can not be found for Linux on ARM platform, if native libraries are not found or can not be loaded/linked. If appropriate files/directories can not be read or written, If native library can not be initialized.
    
    IllegalArgumentException - if directoryPath is null, directoryPath is empty, loadedLibName is null or empty.
  - getSerialComNullModemInstance
```
public SerialComNullModem getSerialComNullModemInstance()
                                                 throws IOException
```
    Provides an instance of SerialComNullModem class for managing virtual serial device, null modem, loop back and custom pinout connected virtual serial devices.
    
    Returns:
    an instance of SerialComNullModem class.
    
    Throws:
    
    IOException - if any error occurs while handling null modem driver specific files.

Class SerialComManager

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

JAVA_LIB_VERSION

DEFAULT_READBYTECOUNT

CTS

DSR

DCD

RI

LOOP

RTS

DTR

InputStream

OutputStream

EXP_UNBLOCKIO

Constructor Detail

SerialComManager

SerialComManager

Method Detail

getLibraryVersions

listAvailableComPorts

openComPort

closeComPort

writeBytes

writeBytes

writeSingleByte

writeString

writeString

writeSingleInt

writeIntArray

writeBytesDirect

writeBytesBlocking

readBytesDirect

createBlockingIOContext

unblockBlockingIOOperation

destroyBlockingIOContext

readBytesBlocking

readBytes

readBytes

readString

readString

readSingleByte

readBytes

configureComPortData

configureComPortControl

getCurrentConfiguration

setRTS

setDTR

registerDataListener

unregisterDataListener

registerLineEventListener

unregisterLineEventListener

pauseListeningEvents

resumeListeningEvents

fineTuneReadBehaviour

setEventsMask

getEventsMask

clearPortIOBuffers

sendBreak

getInterruptCount

getLinesStatus

findDriverServingComPort

findIRQnumberForComPort

getByteCountInPortIOBuffer

getPortName

sendFile

receiveFile

getIOStreamInstance

getVendorLibFromFactory

getSerialComPortMapperInstance

getSerialComDBReleaseInstance

getSerialComNullModemInstance