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:
    `ViewHandler`, `ProactiveHandler`, `ToolkitException`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and 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 Detail

    - #### 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 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, 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:
        `java.lang.NullPointerException` - if `dstBuffer` is `null`
        `java.lang.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 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, 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:
        `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

    - #### 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 java.lang.NullPointerException,
                                java.lang.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:
        `java.lang.NullPointerException` - - if dstBuffer is null
        `java.lang.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