com.datecs.universalreader

## Class UniversalReader

- java.lang.Object
- - com.datecs.universalreader.UniversalReader

-     public final class UniversalReader
      extends java.lang.Object

  This class provides functionality for CAC2, PDA+, SCP10, PP-55 Smart Card Reader, PP-55/DPP-250/DPP-350 Universal Readers and any other device that supports Universal Reader protocol.

  Any instance of class is object associated with a given `InputStream` and `OutputStream`, which are used to transmit data. The `InputStream` instance must provide a proper implementation of `InputStream.available()` method.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `UniversalReader.BarcodeListener` Interface definition for a callbacks to notify for barcode event.
    `class` | `UniversalReader.BarcodeReader` This class provides functionality for Barcode reader.
    `static interface` | `UniversalReader.ButtonListener` Interface definition for a callbacks to notify for button event.
    `static interface` | `UniversalReader.CardListener` Interface definition for a callbacks to notify for card event.
    `static interface` | `UniversalReader.ConnectionListener` Interface definition for a Printer event callback.
    `class` | `UniversalReader.MifareReader` This class provides functionality for the Mifare reader.
    `class` | `UniversalReader.SmartCardReader` This class provides functionality for the Smart Card reader.
    `class` | `UniversalReader.TouchScreen` This class provides functionality for the Touchscreen.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BUTTON_MODE_BARCODE`
    `static int` | `BUTTON_MODE_NONE`
    `static int` | `BUTTON_MODE_STATUS`
    `static int` | `CAPABILITY_BARCODE` Barcode reader capability.
    `static int` | `CAPABILITY_BUTTON` Button capability.
    `static int` | `CAPABILITY_DEBUG` Debug version capability.
    `static int` | `CAPABILITY_EV15` Barcode reader EV15 capability.
    `static int` | `CAPABILITY_FIRMWARE` Firmware download capability.
    `static int` | `CAPABILITY_GSM` GSM module capability.
    `static int` | `CAPABILITY_LCD2X16` LCD 2x16 capability.
    `static int` | `CAPABILITY_MAGNETIC` Magnetic reader capability.
    `static int` | `CAPABILITY_MIFARE` Mifare reader capability.
    `static int` | `CAPABILITY_SMARTCARD` Smart card reader capability.
    `static int` | `CAPABILITY_TOUCHSCREEN` Touch screen capability.
    `static int` | `ERROR_0K` Operation successful.
    `static int` | `ERROR_BARCODE` Barcode reader communication error.
    `static int` | `ERROR_BARCODE_INVALID` Barcode reader invalid command.
    `static int` | `ERROR_BARCODE_NODATA` No barcode read.
    `static int` | `ERROR_BARCODE_NOTPRESENT` Barcode reader not present.
    `static int` | `ERROR_CARD` Card error.
    `static int` | `ERROR_INVALID` Invalid command code.
    `static int` | `ERROR_MIFARE_ACCESS` Mifare access error.
    `static int` | `ERROR_MIFARE_AUTHENTICATION` Mifare authentication error.
    `static int` | `ERROR_MIFARE_BIT` Mifare bit count error.
    `static int` | `ERROR_MIFARE_CODE` Mifare code error.
    `static int` | `ERROR_MIFARE_COLLISION` Mifare collision error.
    `static int` | `ERROR_MIFARE_CRC` Mifare CRC error.
    `static int` | `ERROR_MIFARE_EEPROM` Mifare EEPROM error.
    `static int` | `ERROR_MIFARE_FIFO` Mifare FIFO overflow.
    `static int` | `ERROR_MIFARE_FRAME` Mifare frame error.
    `static int` | `ERROR_MIFARE_GENERIC` Mifare generic error.
    `static int` | `ERROR_MIFARE_KEY` Mifare invalid key.
    `static int` | `ERROR_MIFARE_PARITY` Mifare parity error.
    `static int` | `ERROR_MIFARE_TIMEOUT` Mifare timeout error.
    `static int` | `ERROR_MIFARE_VALUE` Mifare value error.
    `static int` | `ERROR_NODATA` No data available.
    `static int` | `ERROR_NORESPONCE` No response from device.
    `static int` | `ERROR_NOTPERMITTED` Command not permitted.
    `static int` | `ERROR_SYNTAX` Syntax error.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UniversalReader(java.io.InputStream in, java.io.OutputStream out)` Constructs a new instance of this class from a given `InputStream` and `OutputStream`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close the streams and release all associated resources.
    `void` | `displayText(java.lang.String first, java.lang.String second)` Display text.
    `void` | `enableMagneticCardReader(boolean enable)` Enables magnetic card reader.
    `void` | `enableMagneticCardReaderEvents(boolean enable)`
    `UniversalReader.BarcodeReader` | `getBarcodeReader()` Returns an instance of `BarcodeReader` class.
    `int` | `getCapabilities()` Gets device capabilities.
    `java.lang.String` | `getIdentification()` Gets the device identification string.
    `UniversalReader.MifareReader` | `getMifareReader()` Returns an instance of `MifareReader` class.
    `java.lang.String` | `getSerialNumber()` Gets the device serial number.
    `UniversalReader.SmartCardReader` | `getSmartCardReader()` Returns an instance of `SmartCardReader` class.
    `UniversalReader.TouchScreen` | `getTouchScreen()` Returns an instance of `Touchscreen` class.
    `boolean` | `isButtonPressed()` Gets the current state of the button.
    `boolean` | `isButtonPressed(boolean update)` Gets the current state of the button.
    `void` | `playSound(int frequency, int duration)` Plays sound via device buzzer.
    `byte[]` | `readTrackData(int track)` Read track data.
    `void` | `setAutoOff(int time)` Set auto off time.
    `void` | `setBarcodeListener(UniversalReader.BarcodeListener listener)` Set a callback listener to notify for barcode event.
    `void` | `setButton(int mode)` Set button function mode
    `void` | `setButtonListener(UniversalReader.ButtonListener listener)` Set a callback listener to notify for button state changed.
    `void` | `setCardListener(UniversalReader.CardListener listener)` Set a callback listener to notify for card event.
    `void` | `setConnectionListener(UniversalReader.ConnectionListener listener)` Set a callback listener to notify the connection state is changed.
    `static void` | `setDebug(boolean on)` Specify whether the object can output debug information
    `void` | `turnOff()` Turn off the device.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### ERROR_0K

          public static final int ERROR_0K

      Operation successful.
      See Also:
        Constant Field Values

    - #### ERROR_INVALID

          public static final int ERROR_INVALID

      Invalid command code.
      See Also:
        Constant Field Values

    - #### ERROR_NOTPERMITTED

          public static final int ERROR_NOTPERMITTED

      Command not permitted.
      See Also:
        Constant Field Values

    - #### ERROR_CARD

          public static final int ERROR_CARD

      Card error.
      See Also:
        Constant Field Values

    - #### ERROR_SYNTAX

          public static final int ERROR_SYNTAX

      Syntax error.
      See Also:
        Constant Field Values

    - #### ERROR_NORESPONCE

          public static final int ERROR_NORESPONCE

      No response from device.
      See Also:
        Constant Field Values

    - #### ERROR_NODATA

          public static final int ERROR_NODATA

      No data available.
      See Also:
        Constant Field Values

    - #### ERROR_BARCODE

          public static final int ERROR_BARCODE

      Barcode reader communication error.
      See Also:
        Constant Field Values

    - #### ERROR_BARCODE_NODATA

          public static final int ERROR_BARCODE_NODATA

      No barcode read.
      See Also:
        Constant Field Values

    - #### ERROR_BARCODE_INVALID

          public static final int ERROR_BARCODE_INVALID

      Barcode reader invalid command.
      See Also:
        Constant Field Values

    - #### ERROR_BARCODE_NOTPRESENT

          public static final int ERROR_BARCODE_NOTPRESENT

      Barcode reader not present.
      See Also:
        Constant Field Values

    - #### ERROR_MIFARE_TIMEOUT

          public static final int ERROR_MIFARE_TIMEOUT

      Mifare timeout error.
      See Also:
        Constant Field Values

    - #### ERROR_MIFARE_COLLISION

          public static final int ERROR_MIFARE_COLLISION

      Mifare collision error.
      See Also:
        Constant Field Values

    - #### ERROR_MIFARE_PARITY

          public static final int ERROR_MIFARE_PARITY

      Mifare parity error.
      See Also:
        Constant Field Values

    - #### ERROR_MIFARE_FRAME

          public static final int ERROR_MIFARE_FRAME

      Mifare frame error.
      See Also:
        Constant Field Values

    - #### ERROR_MIFARE_CRC

          public static final int ERROR_MIFARE_CRC

      Mifare CRC error.
      See Also:
        Constant Field Values

    - #### ERROR_MIFARE_FIFO

          public static final int ERROR_MIFARE_FIFO

      Mifare FIFO overflow.
      See Also:
        Constant Field Values

    - #### ERROR_MIFARE_EEPROM

          public static final int ERROR_MIFARE_EEPROM

      Mifare EEPROM error.
      See Also:
        Constant Field Values

    - #### ERROR_MIFARE_KEY

          public static final int ERROR_MIFARE_KEY

      Mifare invalid key.
      See Also:
        Constant Field Values

    - #### ERROR_MIFARE_GENERIC

          public static final int ERROR_MIFARE_GENERIC

      Mifare generic error.
      See Also:
        Constant Field Values

    - #### ERROR_MIFARE_AUTHENTICATION

          public static final int ERROR_MIFARE_AUTHENTICATION

      Mifare authentication error.
      See Also:
        Constant Field Values

    - #### ERROR_MIFARE_CODE

          public static final int ERROR_MIFARE_CODE

      Mifare code error.
      See Also:
        Constant Field Values

    - #### ERROR_MIFARE_BIT

          public static final int ERROR_MIFARE_BIT

      Mifare bit count error.
      See Also:
        Constant Field Values

    - #### ERROR_MIFARE_ACCESS

          public static final int ERROR_MIFARE_ACCESS

      Mifare access error.
      See Also:
        Constant Field Values

    - #### ERROR_MIFARE_VALUE

          public static final int ERROR_MIFARE_VALUE

      Mifare value error.
      See Also:
        Constant Field Values

    - #### CAPABILITY_DEBUG

          public static final int CAPABILITY_DEBUG

      Debug version capability.
      See Also:
        Constant Field Values

    - #### CAPABILITY_SMARTCARD

          public static final int CAPABILITY_SMARTCARD

      Smart card reader capability.
      See Also:
        Constant Field Values

    - #### CAPABILITY_BARCODE

          public static final int CAPABILITY_BARCODE

      Barcode reader capability.
      See Also:
        Constant Field Values

    - #### CAPABILITY_TOUCHSCREEN

          public static final int CAPABILITY_TOUCHSCREEN

      Touch screen capability.
      See Also:
        Constant Field Values

    - #### CAPABILITY_GSM

          public static final int CAPABILITY_GSM

      GSM module capability.
      See Also:
        Constant Field Values

    - #### CAPABILITY_MIFARE

          public static final int CAPABILITY_MIFARE

      Mifare reader capability.
      See Also:
        Constant Field Values

    - #### CAPABILITY_BUTTON

          public static final int CAPABILITY_BUTTON

      Button capability.
      See Also:
        Constant Field Values

    - #### CAPABILITY_LCD2X16

          public static final int CAPABILITY_LCD2X16

      LCD 2x16 capability.
      See Also:
        Constant Field Values

    - #### CAPABILITY_FIRMWARE

          public static final int CAPABILITY_FIRMWARE

      Firmware download capability.
      See Also:
        Constant Field Values

    - #### CAPABILITY_MAGNETIC

          public static final int CAPABILITY_MAGNETIC

      Magnetic reader capability.
      See Also:
        Constant Field Values

    - #### CAPABILITY_EV15

          public static final int CAPABILITY_EV15

      Barcode reader EV15 capability.
      See Also:
        Constant Field Values

    - #### BUTTON_MODE_NONE

          public static final int BUTTON_MODE_NONE

      See Also:
        Constant Field Values

    - #### BUTTON_MODE_BARCODE

          public static final int BUTTON_MODE_BARCODE

      See Also:
        Constant Field Values

    - #### BUTTON_MODE_STATUS

          public static final int BUTTON_MODE_STATUS

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### UniversalReader

          public UniversalReader(java.io.InputStream in,
                                 java.io.OutputStream out)

      Constructs a new instance of this class from a given `InputStream` and `OutputStream`.

      The `InputStream` and `OutputStream` must provides direct row data access to hardware device.

      If `in` or `out` is `null`, a `NullPointerException` is thrown.

      Parameters:
        `in` - the input stream.
        `out` - the output stream.

  - ### Method Detail

    - #### close

          public void close()

      Close the streams and release all associated resources.

    - #### setDebug

          public static void setDebug(boolean on)

      Specify whether the object can output debug information
      Parameters:
        `on` - True to enable debbuging; otherwise false.

    - #### setBarcodeListener

          public void setBarcodeListener(UniversalReader.BarcodeListener listener)

      Set a callback listener to notify for barcode event.
      Parameters:
        `listener` - the listener.

    - #### setCardListener

          public void setCardListener(UniversalReader.CardListener listener)

      Set a callback listener to notify for card event.
      Parameters:
        `listener` - the listener.

    - #### setButtonListener

          public void setButtonListener(UniversalReader.ButtonListener listener)

      Set a callback listener to notify for button state changed.
      Parameters:
        `listener` - the listener.

    - #### setConnectionListener

          public void setConnectionListener(UniversalReader.ConnectionListener listener)

      Set a callback listener to notify the connection state is changed.
      Parameters:
        `listener` - the listener.

    - #### enableMagneticCardReader

          public void enableMagneticCardReader(boolean enable)
                                        throws java.io.IOException,
                                               UniversalReaderException

      Enables magnetic card reader.
      Parameters:
        `enable` - true to enable; otherwise disable it.
      Throws:
        `java.io.IOException` - if an I/O error occurs.
        `UniversalReaderException` - if an error occurs during execution.

    - #### enableMagneticCardReaderEvents

          public void enableMagneticCardReaderEvents(boolean enable)
                                              throws java.io.IOException,
                                                     UniversalReaderException

      Throws:
        `java.io.IOException`
        `UniversalReaderException`

    - #### setButton

          public void setButton(int mode)
                         throws java.io.IOException,
                                UniversalReaderException

      Set button function mode
      Parameters:
        `mode` - the function mode. It can be one of BUTTON_MODE_* constant values.
      Throws:
        `java.io.IOException` - if an I/O error occurs.
        `UniversalReaderException` - if an error occurs during execution.

    - #### readTrackData

          public byte[] readTrackData(int track)
                               throws java.io.IOException,
                                      UniversalReaderException

      Read track data.
      Parameters:
        `track` - the track mode.
      Returns:
        the track data.
      Throws:
        `java.io.IOException` - if an I/O error occurs.
        `UniversalReaderException` - if an error occurs during execution.

    - #### getIdentification

          public java.lang.String getIdentification()
                                             throws java.io.IOException,
                                                    UniversalReaderException

      Gets the device identification string.
      Returns:
        the identification string in format: [device name and version];[build date];[firmware checksum];
      Throws:
        `java.io.IOException` - if an I/O error occurs.
        `UniversalReaderException` - if an error occurs during execution.

    - #### isButtonPressed

          public boolean isButtonPressed()
                                  throws java.io.IOException,
                                         UniversalReaderException

      Gets the current state of the button.
      Returns:
        `true` if the button is pressed; otherwise returns false.
      Throws:
        `UniversalReaderException` - if an error occurs during execution.
        `java.io.IOException`

    - #### isButtonPressed

          public boolean isButtonPressed(boolean update)
                                  throws java.io.IOException,
                                         UniversalReaderException

      Gets the current state of the button.
      Parameters:
        `update` - the flag indicates where to update button status from or returns using the status from last operation.
      Returns:
        `true` if the button is pressed; otherwise returns false.
      Throws:
        `UniversalReaderException` - if an error occurs during execution.
        `java.io.IOException`

    - #### turnOff

          public void turnOff()
                       throws java.io.IOException,
                              UniversalReaderException

      Turn off the device.
      Throws:
        `java.io.IOException` - if an I/O error occurs.
        `UniversalReaderException` - if an error occurs during execution.

    - #### setAutoOff

          public void setAutoOff(int time)
                          throws java.io.IOException,
                                 UniversalReaderException

      Set auto off time.
      Parameters:
        `time` - the new auto off time in seconds.
      Throws:
        `java.io.IOException` - if an I/O error occurs.
        `UniversalReaderException` - if an error occurs during execution.

    - #### playSound

          public void playSound(int frequency,
                                int duration)
                         throws java.io.IOException,
                                UniversalReaderException

      Plays sound via device buzzer.
      Parameters:
        `frequency` - the frequency of sound in Hz.
        `duration` - the duration of sound in milliseconds.
      Throws:
        `java.io.IOException` - if an I/O error occurs.
        `UniversalReaderException` - if an error occurs during execution.

    - #### displayText

          public void displayText(java.lang.String first,
                                  java.lang.String second)
                           throws java.io.IOException,
                                  UniversalReaderException

      Display text.
      Parameters:
        `first` - the text on first line.
        `second` - the text on second line.
      Throws:
        `java.io.IOException` - if an I/O error occurs.
        `UniversalReaderException` - if an error occurs during execution.

    - #### getSerialNumber

          public java.lang.String getSerialNumber()
                                           throws java.io.IOException,
                                                  UniversalReaderException

      Gets the device serial number.
      Returns:
        the device serial number.
      Throws:
        `java.io.IOException` - if an I/O error occurs.
        `UniversalReaderException` - if an error occurs during execution.

    - #### getCapabilities

          public int getCapabilities()
                              throws java.io.IOException,
                                     UniversalReaderException

      Gets device capabilities.
      Returns:
        the device capabilities bits value. For more information please refers to the `CAPABILITIES_`* constant field values.
      Throws:
        `java.io.IOException` - if an I/O error occurs.
        `UniversalReaderException` - if an error occurs during execution.

    - #### getBarcodeReader

          public UniversalReader.BarcodeReader getBarcodeReader()

      Returns an instance of `BarcodeReader` class.
      Returns:
        an instance of `BarcodeReader` class.

    - #### getSmartCardReader

          public UniversalReader.SmartCardReader getSmartCardReader()

      Returns an instance of `SmartCardReader` class.
      Returns:
        an instance of `SmartCardReader` class.

    - #### getTouchScreen

          public UniversalReader.TouchScreen getTouchScreen()

      Returns an instance of `Touchscreen` class.
      Returns:
        an instance of `Touchscreen` class.

    - #### getMifareReader

          public UniversalReader.MifareReader getMifareReader()

      Returns an instance of `MifareReader` class.
      Returns:
        an instance of `MifareReader` class.