sim.toolkit
Class ProactiveResponseHandler

java.lang.Object
  |
  +--sim.toolkit.ViewHandler
        |
        +--sim.toolkit.ProactiveResponseHandler

public final class ProactiveResponseHandler
extends ViewHandler

The ProactiveResponseHandler class contains basic methods to handle the Terminal Response data field. This class will be used by the Toolkit applet to get the response to the Proactive commands. No constructor is available for the Toolkit applet. The ProactiveResponseHandler class is a Temporary JCRE Entry Point Object. The only way to get a ProactiveResponseHandler reference is through the getTheHandler() static method.

Example of use:



 private byte[] data;
 data = new byte[32];                 // build a buffer

 ProactiveResponseHandler ProRespHdlr;            // get the system instance
 ProRespHdlr = ProactiveResponseHandler.getTheHandler();

 // get General Result
 byte result = ProRespHdlr.getGeneralResult();

 respHdlr.findTLV(TAG_DEVICE_IDENTITIES, 1);          // look for Device Identities
 byte sourceDev = ProRespHdlr.getValueByte((short)0);    // read Device Identities
 byte destinDev = ProRespHdlr.getValueByte((short)1);

                                                      // look for Text String element
 if (ProRespHdlr.findTLV(TAG_TEXT_STRING, (byte)1) == TLV_FOUND_CR_SET) {
     if ((short len = ProRespHdlr.getValueLength()) > 1) {
         // not empty string: to be copied
         ProRespHdlr.copyValue((short)1, data, (short)0, (short)(len - 1));
     }
 }
 

Version:
8.1.0
See Also:
ViewHandler, ProactiveHandler, ToolkitException

Method Summary
 short copyAdditionalInformation(byte[] dstBuffer, short dstOffset, short dstLength)
          Copies a part of the additional information field from the first Result TLV element of the current response data field.
 short copyTextString(byte[] dstBuffer, short dstOffset)
          Copies the text string value from the first Text String TLV element of the current response data field.
 short getAdditionalInformationLength()
          Returns the length of the additional information field from the first Result TLV element of the current response data field.
 byte getGeneralResult()
          Returns the general result byte of the Proactive command.
 byte getItemIdentifier()
          Returns the item identifier byte value from the first Item Identifier TLV element of the current response data field.
 byte getTextStringCodingScheme()
          Returns the data coding scheme byte from the first Text String TLV element of the current response data field.
 short getTextStringLength()
          Returns the text string length value from the first Text String TLV element of the current response data field.
static ProactiveResponseHandler getTheHandler()
          Returns the single system instance of the ProactiveResponseHandler class.
 
Methods inherited from class sim.toolkit.ViewHandler
compareValue, copy, copyValue, findAndCompareValue, findAndCompareValue, findAndCopyValue, findAndCopyValue, findTLV, getLength, getValueByte, getValueLength
 
Methods inherited from class java.lang.Object
equals
 

Method Detail

getTheHandler

public static ProactiveResponseHandler getTheHandler()
                                              throws ToolkitException
Returns the single system instance of the ProactiveResponseHandler class. The applet shall get the reference of the handler at its triggering, the beginning of the processToolkit method.
Returns:
reference of the system instance
Throws:
ToolkitException - with the following reason codes:
  • HANDLER_NOT_AVAILABLE if the handler is busy.

getGeneralResult

public byte getGeneralResult()
                      throws ToolkitException
Returns the general result byte of the Proactive command. If the element is available it becomes the TLV selected.
Returns:
general result of the command (first byte of Result TLV in Terminal Response)
Throws:
ToolkitException - with the following reason codes:
  • UNAVAILABLE_ELEMENT in case of unavailable Result TLV element
  • OUT_OF_TLV_BOUNDARIES if the general result byte is missing in the Result Simple TLV

getAdditionalInformationLength

public short getAdditionalInformationLength()
                                     throws ToolkitException
Returns the length of the additional information field from the first Result TLV element of the current response data field. If the element is available it becomes the TLV selected.
Returns:
additional information length
Throws:
ToolkitException - with the following reason codes:
  • UNAVAILABLE_ELEMENT in case of unavailable Result TLV element

copyAdditionalInformation

public short copyAdditionalInformation(byte[] dstBuffer,
                                       short dstOffset,
                                       short dstLength)
                                throws java.lang.NullPointerException,
                                       java.lang.ArrayIndexOutOfBoundsException,
                                       ToolkitException
Copies a part of the additional information field from the first Result TLV element of the current response data field. If the element is available it becomes the TLV selected.

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 copyAdditionalInformation would cause access of data outside array bounds.
ToolkitException - with the following reason codes:
  • UNAVAILABLE_ELEMENT in case of unavailable Result TLV element
  • OUT_OF_TLV_BOUNDARIES if dstLength is greater than the value field of the available TLV

getItemIdentifier

public byte getItemIdentifier()
                       throws ToolkitException
Returns the item identifier byte value from the first Item Identifier TLV element of the current response data field. If the element is available it becomes the TLV selected.
Returns:
item identifier
Throws:
ToolkitException - with the following reason codes:
  • UNAVAILABLE_ELEMENT in case of unavailable Item Identifier TLV element
  • OUT_OF_TLV_BOUNDARIES if the item identifier byte is missing in the Item Identifier Simple TLV

getTextStringLength

public short getTextStringLength()
                          throws ToolkitException
Returns the text string length value from the first Text String TLV element of the current response data field. The Data Coding Scheme byte is not taken into account. If the element is available it becomes the TLV selected.
Returns:
text string length
Throws:
ToolkitException - with the following reason codes:
  • UNAVAILABLE_ELEMENT in case of unavailable Text String TLV element

getTextStringCodingScheme

public byte getTextStringCodingScheme()
                               throws ToolkitException
Returns the data coding scheme byte from the first Text String TLV element of the current response data field. If the element is available it becomes the TLV selected.
Returns:
text string coding scheme
Throws:
ToolkitException - with the following reason codes:
  • UNAVAILABLE_ELEMENT in case of unavailable Text String TLV element
  • OUT_OF_TLV_BOUNDARIES if the Text String TLV is present with a length of 0 (no DCS byte)

copyTextString

public short copyTextString(byte[] dstBuffer,
                            short dstOffset)
                     throws java.lang.NullPointerException,
                            java.lang.ArrayIndexOutOfBoundsException,
                            ToolkitException
Copies the text string value from the first Text String TLV element of the current response data field. The Data Coding Scheme byte is not copied. If the element is available it becomes the TLV selected.
Parameters:
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 or dstOffset + (length of the TextString to be copied, without the Data Coding Scheme included), as specified for the returned value, would cause access outside array bounds.
ToolkitException - with the following reason codes:
  • UNAVAILABLE_ELEMENT in case of unavailable Text String TLV element