sim.toolkit
Class ViewHandler

java.lang.Object
  |
  +--sim.toolkit.ViewHandler
Direct Known Subclasses:
EditHandler, EnvelopeHandler, ProactiveResponseHandler

public abstract class ViewHandler
extends java.lang.Object

The ViewHandler class offers basic services and contains basic methods to handle a Simple 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 Simple TLV.

Version:
5.1.0
See Also:
ToolkitException

Method Summary
 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 simple 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 occurence of a TLV element from beginning of a TLV list and compare its value with a buffer.
 byte findAndCompareValue(byte tag, byte occurence, short valueOffset, byte[] compareBuffer, short compareOffset, short compareLength)
          Looks for the indicated occurence 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 occurence of a TLV element from the beginning of a TLV list and copy its value into a destination buffer.
 short findAndCopyValue(byte tag, byte occurence, short valueOffset, byte[] dstBuffer, short dstOffset, short dstLength)
          Looks for the indicated occurence 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 occurence of a TLV element from the beginning of the TLV list (handler buffer).
 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.
 
Methods inherited from class java.lang.Object
equals
 

Method Detail

getLength

public 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

public short copy(byte[] dstBuffer,
                  short dstOffset,
                  short dstLength)
           throws java.lang.NullPointerException,
                  java.lang.ArrayIndexOutOfBoundsException,
                  ToolkitException
Copies the simple TLV list contained in the handler to the destination byte array.

Notes:

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 copy would cause access of data outside array bounds.
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 simple TLV List.

findTLV

public byte findTLV(byte tag,
                    byte occurrence)
             throws ToolkitException
Looks for the indicated occurence 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 occurence exists and Comprehension Required flag is set
  • TLV_FOUND_CR_NOT_SET if the required occurence 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. occurence = 0)

getValueLength

public 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

public 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

copyValue

public 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.

Notes:

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 copyValue would cause access of data 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
  • OUT_OF_TLV_BOUNDARIES if valueOffset, dstLength or both are out of the current TLV

compareValue

public 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.

Notes:

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 simple TLV List is less than that in compareBuffer,
  • 1 if the first miscomparing byte in simple TLV List is greater than that in compareBuffer.
Throws:
java.lang.NullPointerException - if compareBuffer is null
java.lang.ArrayIndexOutOfBoundsException - if compareValue would cause access of data 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
  • OUT_OF_TLV_BOUNDARIES if valueOffset, compareLength or both are out of the current TLV

findAndCopyValue

public short findAndCopyValue(byte tag,
                              byte[] dstBuffer,
                              short dstOffset)
                       throws java.lang.NullPointerException,
                              java.lang.ArrayIndexOutOfBoundsException,
                              ToolkitException
Looks for the first occurence 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.

Notes:

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 findAndCopyValue would cause access of data 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

public short findAndCopyValue(byte tag,
                              byte occurence,
                              short valueOffset,
                              byte[] dstBuffer,
                              short dstOffset,
                              short dstLength)
                       throws java.lang.NullPointerException,
                              java.lang.ArrayIndexOutOfBoundsException,
                              ToolkitException
Looks for the indicated occurence 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.

Notes:

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...)
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 findAndCopyValue would cause access of data 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
  • 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. occurence = 0)

findAndCompareValue

public byte findAndCompareValue(byte tag,
                                byte[] compareBuffer,
                                short compareOffset)
                         throws java.lang.NullPointerException,
                                java.lang.ArrayIndexOutOfBoundsException,
                                ToolkitException
Looks for the first occurence 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.

Notes:

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 simple TLV is less than that in compareBuffer,
  • 1 if the first miscomparing byte in simple TLV is greater than that in compareBuffer.
Throws:
java.lang.NullPointerException - if compareBuffer is null
java.lang.ArrayIndexOutOfBoundsException - if findAndCompareValue would cause access of data 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

public byte findAndCompareValue(byte tag,
                                byte occurence,
                                short valueOffset,
                                byte[] compareBuffer,
                                short compareOffset,
                                short compareLength)
                         throws java.lang.NullPointerException,
                                java.lang.ArrayIndexOutOfBoundsException,
                                ToolkitException
Looks for the indicated occurence 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.

Notes:

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...)
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
Returns:
the result of the comparison as follows:
  • 0 if identical
  • -1 if the first miscomparing byte in simple TLV is less than that in compareBuffer,
  • 1 if the first miscomparing byte in simple TLV is greater than that in compareBuffer.
Throws:
java.lang.NullPointerException - if compareBuffer is null
java.lang.ArrayIndexOutOfBoundsException - if findAndCompareValue would cause access of data 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
  • 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)