sim.toolkit
Class ProactiveHandler

java.lang.Object
  |
  +--sim.toolkit.ViewHandler
        |
        +--sim.toolkit.EditHandler
              |
              +--sim.toolkit.ProactiveHandler

public final class ProactiveHandler
extends EditHandler

This class 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.

Example of use:


                                      // constants definition
 private static final byte MY_COMMAND = (byte)0x33;
 private static final byte MY_TAG     = (byte)0x45;

 ProactiveHandler proHdlr;            // get the system instance
 proHdlr = ProactiveHandler.getTheHandler();

                                      // build and send a new Proactive command
 proHdlr.init(MY_COMMAND, (byte)0, DEV_ID_ME);
 proHdlr.appendTLV((byte)(MY_TAG | TAG_SET_CR),
                (byte)0);
 short len = proHdlr.getLength();     // length should be 14 !
 byte result = proHdlr.send();

 private byte[] text = new byte[12];  // byte array definition
 text[0] = (byte)'S';                 // text, in 8-bit format, is "SAT"
 text[1] = (byte)'A';
 text[2] = (byte)'T';
                                      // build and send a DisplayText command
 result = proHdlr.initDisplayText((byte)0x80, DCS_8_BIT_DATA, text, (short)0, (short)3);
 result = proHdlr.send();
 

Version:
8.0.0
See Also:
ViewHandler, EditHandler, ProactiveResponseHandler, ToolkitException

Method Summary
static ProactiveHandler getTheHandler()
          Returns the single system instance of the ProactiveHandler class.
 void init(byte type, byte qualifier, byte dstDevice)
          Initializes the next Proactive command with Command Details and Device Identities TLV.
 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.
 byte send()
          Sends the current Proactive command.
 
Methods inherited from class sim.toolkit.EditHandler
appendArray, appendTLV, appendTLV, appendTLV, appendTLV, clear
 
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 ProactiveHandler getTheHandler()
                                      throws ToolkitException
Returns the single system instance of the ProactiveHandler 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.

init

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

public 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 Simple TLV is missing.
  • OUT_OF_TLV_BOUNDARIES if the general result byte is missing in the Result Simple TLV.

initDisplayText

public 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

public 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

public 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