uicc.toolkit

## Interface ViewHandler

- All Known Subinterfaces:
    BERTLVEditHandler, BERTLVViewHandler, EditHandler, EnvelopeHandler, EnvelopeResponseHandler, ProactiveHandler, ProactiveResponseHandler

      public interface ViewHandler

  The `ViewHandler` class offers basic services and contains basic methods to handle a Comprehension TLV List, such as in a Terminal Response data field or in a BER-TLV element (Envelope data field or Proactive command). The byte at offset 0 of a handler is the tag of the first Comprehension TLV.
  See Also:
    `ToolkitException`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `byte` | `compareValue(short valueOffset, byte[] compareBuffer, short compareOffset, short compareLength)` Compares the last found TLV element with a buffer.
    `short` | `copy(byte[] dstBuffer, short dstOffset, short dstLength)` Copies the Comprehension TLV list contained in the handler to the destination byte array.
    `short` | `copyValue(short valueOffset, byte[] dstBuffer, short dstOffset, short dstLength)` Copies a part of the last TLV element which has been found, into a destination buffer.
    `byte` | `findAndCompareValue(byte tag, byte[] compareBuffer, short compareOffset)` Looks for the first occurrence of a TLV element from beginning of a TLV list and compare its value with a buffer.
    `byte` | `findAndCompareValue(byte tag, byte occurrence, short valueOffset, byte[] compareBuffer, short compareOffset, short compareLength)` Looks for the indicated occurrence of a TLV element from the beginning of a TLV list and compare its value with a buffer.
    `short` | `findAndCopyValue(byte tag, byte[] dstBuffer, short dstOffset)` Looks for the first occurrence of a TLV element from the beginning of a TLV list and copy its value into a destination buffer.
    `short` | `findAndCopyValue(byte tag, byte occurrence, short valueOffset, byte[] dstBuffer, short dstOffset, short dstLength)` Looks for the indicated occurrence of a TLV element from the beginning of a TLV list and copy its value into a destination buffer.
    `byte` | `findTLV(byte tag, byte occurrence)` Looks for the indicated occurrence of a TLV element from the beginning of the TLV list (handler buffer).
    `short` | `getCapacity()` Returns the maximum size of the Comprehension TLV list managed by the handler.
    `short` | `getLength()` Returns the length of the TLV list.
    `byte` | `getValueByte(short valueOffset)` Gets a byte from the last TLV element which has been found in the handler.
    `short` | `getValueLength()` Gets the binary length of the value field for the last TLV element which has been found in the handler.
    `short` | `getValueShort(short valueOffset)` Gets a short from the last TLV element which has been found in the handler.

- - ### Method Detail

    - #### getLength

          short getLength()
                   throws ToolkitException

      Returns the length of the TLV list.
      Returns:
        length in bytes
      Throws:
        `ToolkitException` - with the following reason codes:
        - `HANDLER_NOT_AVAILABLE` if the handler is busy

    - #### copy

          short copy(byte[] dstBuffer,
                     short dstOffset,
                     short dstLength)
              throws java.lang.NullPointerException,
                     java.lang.ArrayIndexOutOfBoundsException,
                     ToolkitException

      Copies the Comprehension TLV list contained in the handler to the destination byte array.
      Parameters:
        `dstBuffer` - a reference to the destination buffer
        `dstOffset` - the position in the destination buffer
        `dstLength` - the data length to be copied
      Returns:
        `dstOffset+dstLength`
      Throws:
        `java.lang.NullPointerException` - if `dstBuffer` is `null`
        `java.lang.ArrayIndexOutOfBoundsException` - if `dstOffset` or `dstLength` or both would cause access outside array bounds, or if `dstLength` is negative.
        `ToolkitException` - with the following reason codes:
        - `HANDLER_NOT_AVAILABLE` if the handler is busy
        - `OUT_OF_TLV_BOUNDARIES` if `dstLength` is grater than the length of the Comprehension TLV List.

    - #### findTLV

          byte findTLV(byte tag,
                       byte occurrence)
                throws ToolkitException

      Looks for the indicated occurrence of a TLV element from the beginning of the TLV list (handler buffer). If the method is successful then the corresponding TLV becomes current, else no TLV is selected. This search method is Comprehension Required flag independent.
      Parameters:
        `tag` - the tag of the TLV element to search
        `occurrence` - the occurrence number of the TLV element (1 for the first, 2 for the second...)
      Returns:
        result of the method:
        - `TLV_NOT_FOUND` if the required occurrence of the TLV element does not exist
        - `TLV_FOUND_CR_SET` if the required occurrence exists and Comprehension Required flag is set
        - `TLV_FOUND_CR_NOT_SET` if the required occurrence exists and Comprehension Required flag is not set
      Throws:
        `ToolkitException` - with the following reason codes:
        - `HANDLER_NOT_AVAILABLE` if the handler is busy
        - `BAD_INPUT_PARAMETER` if an input parameter is not valid (e.g. occurrence = 0)

    - #### getValueLength

          short getValueLength()
                        throws ToolkitException

      Gets the binary length of the value field for the last TLV element which has been found in the handler.
      Returns:
        length of the value field
      Throws:
        `ToolkitException` - with the following reason codes:
        - `HANDLER_NOT_AVAILABLE` if the handler is busy
        - `UNAVAILABLE_ELEMENT` in case of unavailable TLV element

    - #### getValueByte

          byte getValueByte(short valueOffset)
                     throws ToolkitException

      Gets a byte from the last TLV element which has been found in the handler.
      Parameters:
        `valueOffset` - the offset of the byte to return in the TLV element
      Returns:
        element value (1 byte)
      Throws:
        `ToolkitException` - with the following reason codes:
        - `HANDLER_NOT_AVAILABLE` if the handler is busy
        - `UNAVAILABLE_ELEMENT` in case of unavailable TLV element
        - `OUT_OF_TLV_BOUNDARIES` if `valueOffset` is out of the current TLV

    - #### getValueShort

          short getValueShort(short valueOffset)
                       throws ToolkitException

      Gets a short from the last TLV element which has been found in the handler.
      Parameters:
        `valueOffset` - the offset of the short to return in the TLV element
      Returns:
        element value (1 short)
      Throws:
        `ToolkitException` - with the following reason codes:
        - `HANDLER_NOT_AVAILABLE` if the handler is busy
        - `UNAVAILABLE_ELEMENT` in case of unavailable TLV element
        - `OUT_OF_TLV_BOUNDARIES` if `valueOffset` is out of the current TLV

    - #### copyValue

          short copyValue(short valueOffset,
                          byte[] dstBuffer,
                          short dstOffset,
                          short dstLength)
                   throws java.lang.NullPointerException,
                          java.lang.ArrayIndexOutOfBoundsException,
                          ToolkitException

      Copies a part of the last TLV element which has been found, into a destination buffer.
      Parameters:
        `valueOffset` - the offset of the first byte in the source TLV element
        `dstBuffer` - a reference to the destination buffer
        `dstOffset` - the position in the destination buffer
        `dstLength` - the data length to be copied
      Returns:
        `dstOffset+dstLength`
      Throws:
        `java.lang.NullPointerException` - if `dstBuffer` is `null`
        `java.lang.ArrayIndexOutOfBoundsException` - if `dstOffset` or `dstLength` or both would cause access outside array bounds, or if `dstLength` is negative.
        `ToolkitException` - with the following reason codes:
        - `HANDLER_NOT_AVAILABLE` if the handler is busy
        - `UNAVAILABLE_ELEMENT` in case of unavailable TLV element
        - `OUT_OF_TLV_BOUNDARIES` if `valueOffset`, `dstLength` or both are out of the current TLV

    - #### compareValue

          byte compareValue(short valueOffset,
                            byte[] compareBuffer,
                            short compareOffset,
                            short compareLength)
                     throws java.lang.NullPointerException,
                            java.lang.ArrayIndexOutOfBoundsException,
                            ToolkitException

      Compares the last found TLV element with a buffer.
      Parameters:
        `valueOffset` - the offset of the first byte to compare in the TLV element
        `compareBuffer` - a reference to the comparison buffer
        `compareOffset` - the position in the comparison buffer
        `compareLength` - the length to be compared
      Returns:
        the result of the comparison as follows:
        - `0` if identical
        - `-1` if the first miscomparing byte in Comprehension TLV List is less than that in `compareBuffer`,
        - `1` if the first miscomparing byte in Comprehension TLV List is greater than that in `compareBuffer`.
      Throws:
        `java.lang.NullPointerException` - if `compareBuffer` is `null`
        `java.lang.ArrayIndexOutOfBoundsException` - if `compareOffset` or `compareLength` or both would cause access outside array bounds, or if `compareLength` is negative.
        `ToolkitException` - with the following reason codes:
        - `HANDLER_NOT_AVAILABLE` if the handler is busy
        - `UNAVAILABLE_ELEMENT` in case of unavailable TLV element
        - `OUT_OF_TLV_BOUNDARIES` if `valueOffset`, `compareLength` or both are out of the current TLV

    - #### findAndCopyValue

          short findAndCopyValue(byte tag,
                                 byte[] dstBuffer,
                                 short dstOffset)
                          throws java.lang.NullPointerException,
                                 java.lang.ArrayIndexOutOfBoundsException,
                                 ToolkitException

      Looks for the first occurrence of a TLV element from the beginning of a TLV list and copy its value into a destination buffer. If no TLV element is found, the `UNAVAILABLE_ELEMENT` exception is thrown. If the method is successful then the corresponding TLV becomes current, else no TLV is selected. This search method is Comprehension Required flag independent.
      Parameters:
        `tag` - the tag of the TLV element to search
        `dstBuffer` - a reference to the destination buffer
        `dstOffset` - the position in the destination buffer
      Returns:
        `dstOffset` + length of the copied value
      Throws:
        `java.lang.NullPointerException` - if `dstBuffer` is `null`
        `java.lang.ArrayIndexOutOfBoundsException` - if `dstOffset` would cause access outside array bounds
        `ToolkitException` - with the following reason codes:
        - `HANDLER_NOT_AVAILABLE` if the handler is busy
        - `UNAVAILABLE_ELEMENT` in case of unavailable TLV element

    - #### findAndCopyValue

          short findAndCopyValue(byte tag,
                                 byte occurrence,
                                 short valueOffset,
                                 byte[] dstBuffer,
                                 short dstOffset,
                                 short dstLength)
                          throws java.lang.NullPointerException,
                                 java.lang.ArrayIndexOutOfBoundsException,
                                 ToolkitException

      Looks for the indicated occurrence of a TLV element from the beginning of a TLV list and copy its value into a destination buffer. If no TLV element is found, the `UNAVAILABLE_ELEMENT` exception is thrown. If the method is successful then the corresponding TLV becomes current, else no TLV is selected. This search method is Comprehension Required flag independent.
      Parameters:
        `tag` - the tag of the TLV element to search
        `valueOffset` - the offset of the first byte in the source TLV element
        `dstBuffer` - a reference to the destination buffer
        `dstOffset` - the position in the destination buffer
        `dstLength` - the data length to be copied
        `occurrence` - the occurrence number of the TLV element (1 for the first, 2 for the second ...)
      Returns:
        `dstOffset + dstLength`
      Throws:
        `java.lang.NullPointerException` - if `dstBuffer` is `null`
        `java.lang.ArrayIndexOutOfBoundsException` - if `dstOffset` or `dstLength` or both would cause access outside array bounds, or if `dstLength` is negative.
        `ToolkitException` - with the following reason codes:
        - `HANDLER_NOT_AVAILABLE` if the handler is busy
        - `UNAVAILABLE_ELEMENT` in case of unavailable TLV element
        - `OUT_OF_TLV_BOUNDARIES` if `valueOffset`, `dstLength` or both are out of the current TLV
        - `BAD_INPUT_PARAMETER` if an input parameter is not valid (e.g. `occurrence = 0`)

    - #### findAndCompareValue

          byte findAndCompareValue(byte tag,
                                   byte[] compareBuffer,
                                   short compareOffset)
                            throws java.lang.NullPointerException,
                                   java.lang.ArrayIndexOutOfBoundsException,
                                   ToolkitException

      Looks for the first occurrence of a TLV element from beginning of a TLV list and compare its value with a buffer. If no TLV element is found, the `UNAVAILABLE_ELEMENT` exception is thrown. If the method is successful then the corresponding TLV becomes current, else no TLV is selected. This search method is Comprehension Required flag independent.
      Parameters:
        `tag` - the tag of the TLV element to search
        `compareBuffer` - a reference to the comparison buffer
        `compareOffset` - the position in the comparison buffer
      Returns:
        the result of the comparison as follows:
        - `0` if identical
        - `-1` if the first miscomparing byte in Comprehension TLV is less than that in `compareBuffer`,
        - `1` if the first miscomparing byte in Comprehension TLV is greater than that in `compareBuffer`.
      Throws:
        `java.lang.NullPointerException` - if `compareBuffer` is `null`
        `java.lang.ArrayIndexOutOfBoundsException` - if `compareOffset` would cause access outside array bounds
        `ToolkitException` - with the following reason codes:
        - `HANDLER_NOT_AVAILABLE` if the handler is busy
        - `UNAVAILABLE_ELEMENT` in case of unavailable TLV element

    - #### findAndCompareValue

          byte findAndCompareValue(byte tag,
                                   byte occurrence,
                                   short valueOffset,
                                   byte[] compareBuffer,
                                   short compareOffset,
                                   short compareLength)
                            throws java.lang.NullPointerException,
                                   java.lang.ArrayIndexOutOfBoundsException,
                                   ToolkitException

      Looks for the indicated occurrence of a TLV element from the beginning of a TLV list and compare its value with a buffer. If no TLV element is found, the `UNAVAILABLE_ELEMENT` exception is thrown. If the method is successful then the corresponding TLV becomes current, else no TLV is selected. This search method is Comprehension Required flag independent.
      Parameters:
        `tag` - the tag of the TLV element to search
        `valueOffset` - the offset of the first byte in the source TLV element
        `compareBuffer` - a reference to the comparison buffer
        `compareOffset` - the position in the comparison buffer
        `compareLength` - the length to be compared
        `occurrence` - the occurrence number of the TLV element (1 for the first, 2 for the second ...)
      Returns:
        the result of the comparison as follows:
        - `0` if identical
        - `-1` if the first miscomparing byte in Comprehension TLV is less than that in `compareBuffer`,
        - `1` if the first miscomparing byte in Comprehension TLV is greater than that in `compareBuffer`.
      Throws:
        `java.lang.NullPointerException` - if `compareBuffer` is `null`
        `java.lang.ArrayIndexOutOfBoundsException` - if `compareOffset` or `compareLength` or both would cause access outside array bounds, or if `compareLength` is negative.
        `ToolkitException` - with the following reason codes:
        - `HANDLER_NOT_AVAILABLE` if the handler is busy
        - `UNAVAILABLE_ELEMENT` in case of unavailable TLV element
        - `OUT_OF_TLV_BOUNDARIES` if `valueOffset`, `compareLength` or both are out of the current TLV
        - `BAD_INPUT_PARAMETER` if an input parameter is not valid (e.g. `occurence = 0`)

    - #### getCapacity

          short getCapacity()
                     throws ToolkitException

      Returns the maximum size of the Comprehension TLV list managed by the handler.
      Returns:
        size in byte
      Throws:
        `ToolkitException` - - with the following reason codes:
        - HANDLER_NOT_AVAILABLE if the handler is busy