uicc.toolkit

## Interface ProactiveHandler

- All Superinterfaces:
    EditHandler, ViewHandler

      public interface ProactiveHandler
      extends EditHandler

  This interface is the basic class for the definition of Proactive commands . Low level methods, as `init()`, `appendTLV()`... will be used to handle generic Proactive commands (standard or future definitions...). The ProactiveHandler class is a Temporary JCRE Entry Point Object. The Toolkit Applets, which need to send Proactive commands, shall call the `getTheHandler()` static method to get the reference of this system instance.
  See Also:
    `ViewHandler`, `EditHandler`, `ProactiveResponseHandler`, `ToolkitException`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `init(byte type, byte qualifier, byte dstDevice)` Initializes the next Proactive command with Command Details and Device Identities TLV.
    `void` | `initCloseChannel(byte bChannelId)` Builds a Close Channel Proactive command without sending the command.
    `void` | `initDisplayText(byte qualifier, byte dcs, byte[] buffer, short offset, short length)` Builds a Display Text Proactive command without sending the command.
    `void` | `initGetInkey(byte qualifier, byte dcs, byte[] buffer, short offset, short length)` Builds a Get Inkey Proactive command without sending the command.
    `void` | `initGetInput(byte qualifier, byte dcs, byte[] buffer, short offset, short length, short minRespLength, short maxRespLength)` Initialize the building of a Get Input Proactive command.
    `void` | `initMoreTime()` Builds a More Time Proactive command without sending the command.
    `byte` | `send()` Sends the current Proactive command.

    - ### Methods inherited from interface uicc.toolkit.EditHandler

      `appendArray, appendTLV, appendTLV, appendTLV, appendTLV, appendTLV, appendTLV, appendTLV, appendTLV, clear`

    - ### Methods inherited from interface uicc.toolkit.ViewHandler

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

- - ### Method Detail

    - #### init

          void init(byte type,
                    byte qualifier,
                    byte dstDevice)

      Initializes the next Proactive command with Command Details and Device Identities TLV. The source device is always the UICC card. The command number is generated by the method. The Comprehension Required flags are set. After the method invocation no TLV is selected.
      Parameters:
        `type` - the command type
        `qualifier` - the command qualifier
        `dstDevice` - the destination device

    - #### send

          byte send()
             throws ToolkitException

      Sends the current Proactive command.
      Returns:
        general result of the command (first byte of Result TLV in Terminal Response)
      Throws:
        `ToolkitException` - with the following reason codes:
        - `UNAVAILABLE_ELEMENT` if the Result Comprehension TLV is missing.
        - `OUT_OF_TLV_BOUNDARIES` if the general result byte is missing in the Result Comprehension TLV.
        - `COMMAND_NOT_ALLOWED` if the Proactive command to be sent or one of its parameter is not allowed by the CAT Runtime Environment.

    - #### initDisplayText

          void initDisplayText(byte qualifier,
                               byte dcs,
                               byte[] buffer,
                               short offset,
                               short length)
                        throws java.lang.NullPointerException,
                               java.lang.ArrayIndexOutOfBoundsException,
                               ToolkitException

      Builds a Display Text Proactive command without sending the command. The Comprehension Required flags are all set to 1. After the method invocation no TLV is selected.
      Parameters:
        `qualifier` - Display Text command qualifier
        `dcs` - data coding scheme
        `buffer` - reference to the text string source buffer
        `offset` - offset of the text string in the source buffer
        `length` - length of the text string in the source buffer
      Throws:
        `java.lang.NullPointerException` - if `buffer` is `null`
        `java.lang.ArrayIndexOutOfBoundsException` - if `offset` or `length` or both would cause access outside array bounds
        `ToolkitException` - with the following reason codes:
        - `HANDLER_OVERFLOW` if the ProactiveHandler buffer is to small to put the requested data

    - #### initGetInkey

          void initGetInkey(byte qualifier,
                            byte dcs,
                            byte[] buffer,
                            short offset,
                            short length)
                     throws java.lang.NullPointerException,
                            java.lang.ArrayIndexOutOfBoundsException,
                            ToolkitException

      Builds a Get Inkey Proactive command without sending the command. The Comprehension Required flags are all set to 1. After the method invocation no TLV is selected.
      Parameters:
        `qualifier` - Get Inkey command qualifier
        `dcs` - data coding scheme
        `buffer` - reference to the displayed text string source buffer
        `offset` - offset of the displayed text string in the source buffer
        `length` - length of the displayed text string in the source buffer
      Throws:
        `java.lang.NullPointerException` - if `buffer` is `null`
        `java.lang.ArrayIndexOutOfBoundsException` - if `offset` or `length` or both would cause access outside array bounds
        `ToolkitException` - with the following reason codes:
        - `HANDLER_OVERFLOW` if the ProactiveHandler buffer is to small to put the requested data

    - #### initGetInput

          void initGetInput(byte qualifier,
                            byte dcs,
                            byte[] buffer,
                            short offset,
                            short length,
                            short minRespLength,
                            short maxRespLength)
                     throws java.lang.NullPointerException,
                            java.lang.ArrayIndexOutOfBoundsException,
                            ToolkitException

      Initialize the building of a Get Input Proactive command. The Comprehension Required flags are all set to 1. The following command parameters (i.e. TLVs) may be appended to the command before sending it: Default Text. After the method invocation no TLV is selected.
      Parameters:
        `qualifier` - Get Input command qualifier
        `dcs` - data coding scheme
        `buffer` - reference to the displayed text string source buffer
        `offset` - offset of the displayed text string in the source buffer
        `length` - length of the displayed text string in the source buffer
        `minRespLength` - minimal length of the response text string
        `maxRespLength` - maximal length of the response text string
      Throws:
        `java.lang.NullPointerException` - if `buffer` is `null`
        `java.lang.ArrayIndexOutOfBoundsException` - if `offset` or `length` or both would cause access outside array bounds
        `ToolkitException` - with the following reason codes:
        - `HANDLER_OVERFLOW` if the ProactiveHandler buffer is to small to put the requested data

    - #### initCloseChannel

          void initCloseChannel(byte bChannelId)

      Builds a Close Channel Proactive command without sending the command. The Comprehension Required flags are all set to 1. After the method invocation no TLV is selected.
      Parameters:
        `bChannelId` - the channel identifier to be closed.

    - #### initMoreTime

          void initMoreTime()

      Builds a More Time Proactive command without sending the command. The Comprehension Required flags are all set to 1. After the method invocation no TLV is selected.

Copyright © 2017 ETSI All Rights Reserved.