Package uicc.toolkit

Interface ProactiveResponseHandler

All Superinterfaces:
ViewHandler
public interface ProactiveResponseHandler extends ViewHandler
The ProactiveResponseHandler interface 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. A class implementing the ProactiveResponseHandler interface is a Temporary JCRE Entry Point Object. The only way to get a ProactiveResponseHandler reference is through the getTheHandler() static method from ProactiveResponseHandlerSystem

Example of use:



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

 ProactiveResponseHandler ProRespHdlr;            // get the system instance
 ProRespHdlr = ProactiveResponseHandlerSystem.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));
     }
 }
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    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
    copyChannelData(byte[] dstBuffer, short dstOffset, short dstLength)
    Copies parts of the Channel data string field from the first Channel data 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
    getChannelIdentifier()
    Returns the channelIdentifier value from the first Channel status TLV element in the current response data field.
    short
    getChannelStatus(byte channelIdentifier)
    Returns the value of the first Channel Status TLV element whose channel identifier is equal to the channelIdentifier parameter.
    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.

    Methods inherited from interface uicc.toolkit.ViewHandler

    compareValue, copy, copyValue, findAndCompareValue, findAndCompareValue, findAndCopyValue, findAndCopyValue, findTLV, getCapacity, getLength, getValueByte, getValueLength, getValueShort

  • Method Details

    • getGeneralResult

      byte getGeneralResult() throws ToolkitException
      Returns the general result byte of the Proactive command. If the element is available it becomes the TLV selected, else no 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 Comprehension TLV

    • getAdditionalInformationLength

      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, else no TLV is selected.
      Returns:
      additional information length
      Throws:
      ToolkitException - with the following reason codes:
      • UNAVAILABLE_ELEMENT in case of unavailable Result TLV element

    • copyAdditionalInformation

      short copyAdditionalInformation(byte[] dstBuffer, short dstOffset, short dstLength) throws NullPointerException, 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, else no TLV is selected.
      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:
      NullPointerException - if dstBuffer is null
      ArrayIndexOutOfBoundsException - if dstOffset or dstLength or both would cause access 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

      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, else no TLV is 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 Comprehension TLV

    • getTextStringLength

      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, else no TLV is selected.
      Returns:
      text string length
      Throws:
      ToolkitException - with the following reason codes:
      • UNAVAILABLE_ELEMENT in case of unavailable Text String TLV element

    • getTextStringCodingScheme

      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, else no TLV is 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

      short copyTextString(byte[] dstBuffer, short dstOffset) throws NullPointerException, 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, else no TLV is selected.
      Parameters:
      dstBuffer - a reference to the destination buffer
      dstOffset - the position in the destination buffer
      Returns:
      dstOffset + length of the copied value
      Throws:
      NullPointerException - if dstBuffer is null
      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

    • getChannelIdentifier

      byte getChannelIdentifier() throws ToolkitException
      Returns the channelIdentifier value from the first Channel status TLV element in the current response data field. If the element is available it becomes the currently selected TLV, else no TLV is selected..
      Returns:
      channelIdentifier
      Throws:
      ToolkitException - - with the following reason codes:
      • UNAVAILABLE_ELEMENT in case of unavailable TLV element.
      • OUT_OF_TLV_BOUNDARIES if the Comprehension TLV Channel Status length is equal to zero.

    • getChannelStatus

      short getChannelStatus(byte channelIdentifier) throws ToolkitException
      Returns the value of the first Channel Status TLV element whose channel identifier is equal to the channelIdentifier parameter. If the element is available it becomes the currently selected TLV element, else no TLV is selected.
      Parameters:
      channelIdentifier - the identifier of the channel
      Returns:
      channel identifier and status : MSB = byte 1 of the Channel Status TLV value (byte 3 of the Channel Status TLV element), LSB = byte 2 of the Channel Status TLV value (byte 4 of the Channel Status TLV element).
      Throws:
      ToolkitException - with the following reason codes:
      • UNAVAILABLE_ELEMENT if no Channel Status TLV element with the right identifier could be found
      • OUT_OF_TLV_BOUNDARIES if a Channel Status TLV element with the right identifier could be found but its value is less than 2 bytes long

    • copyChannelData

      short copyChannelData(byte[] dstBuffer, short dstOffset, short dstLength) throws NullPointerException, ArrayIndexOutOfBoundsException, ToolkitException
      Copies parts of the Channel data string field from the first Channel data TLV element of the current response data field. If the element is available it becomes the currently selected TLV, else no TLV is selected.
      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:
      NullPointerException - - if dstBuffer is null
      ArrayIndexOutOfBoundsException - - if dstOffset or dstLength or both would cause access 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