/*
*
*
* Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License version
* 2 only, as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License version 2 for more details (a copy is
* included at /legal/license.txt).
*
* You should have received a copy of the GNU General Public License
* version 2 along with this work; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 or visit www.sun.com if you need additional
* information or have any questions.
*/
//-----------------------------------------------------------------------------
// PACKAGE DEFINITION
//-----------------------------------------------------------------------------
package sim.toolkit;
//-----------------------------------------------------------------------------
// IMPORTS
//-----------------------------------------------------------------------------
/**
*
* This class is the basic class for the definition of
* <b>Proactive commands
* </b>. Low level methods, as <code>init()</code>, <code>appendTLV()</code>...
* will be used to handle generic Proactive commands (standard or future
* definitions...). The ProactiveHandler class is a <b>Temporary JCRE Entry
* Point Object</b>.
* The Toolkit applets, which need to send Proactive commands,
* shall call the <code>getTheHandler()</code> static method to get the
* reference of this system instance.<p>
*
* Example of use:<pre><code>
* // 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();
* </code></pre>
*
* @version 8.3.0
*
* @see ViewHandler
* @see EditHandler
* @see ProactiveResponseHandler
* @see ToolkitException
*/
public final class ProactiveHandler extends EditHandler {
// ------------------------------- Constructors ---------------------------
/**
* Constructor
*/
private ProactiveHandler() {
}
// ------------------------------- Public methods -------------------------
/**
* 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.
*
* @return reference of the system instance
*
* @exception ToolkitException with the following reason codes: <ul>
* <li><code>HANDLER_NOT_AVAILABLE</code> if the handler is busy.</ul>
*/
public static ProactiveHandler getTheHandler() throws ToolkitException {
return null;
}
/**
* 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.
*
* @param type the command type
* @param qualifier the command qualifier
* @param dstDevice the destination device
*/
public void init(byte type,
byte qualifier,
byte dstDevice) {
}
/**
* Sends the current Proactive command.
*
* @return general result of the command (first byte of Result TLV in
* Terminal Response)
*
* @exception ToolkitException with the following reason codes: <ul>
* <li><code>UNAVAILABLE_ELEMENT</code> if the Result Simple TLV
* is missing.
* <li><code>OUT_OF_TLV_BOUNDARIES</code> if the general result
* byte is missing in the Result Simple TLV.</ul>
*/
public byte send() throws ToolkitException {
return 0;
}
/**
* 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.
*
* <p>
* Notes:<ul>
* <li><em>If </em><code>offset</code><em> or </em><code>length</code><em>
* parameter is negative an
* </em><code>ArrayIndexOutOfBoundsException</code>
* <em> exception is thrown and no proactive command is build.</em>
* <li><em>If </em><code>offset+length</code><em> is greater than
* </em><code>buffer.length</code><em>, the length
* of the </em><code>buffer</code><em> array an
* </em><code>ArrayIndexOutOfBoundsException</code><em> exception is thrown
* and no proactive command is build.</em>
* </ul>
*
* @param qualifier Display Text command qualifier
* @param dcs data coding scheme
* @param buffer reference to the text string source buffer
* @param offset offset of the text string in the source buffer
* @param length length of the text string in the source buffer
*
* @exception NullPointerException if <code>buffer</code> is
* <code>null</code>
* @exception ArrayIndexOutOfBoundsException if initDisplayText would
* cause access of data outside array bounds
* @exception ToolkitException with the following reason codes: <ul>
* <li><code>HANDLER_OVERFLOW</code> if the ProactiveHandler buffer
* is to small to put the requested data </ul>
*/
public void initDisplayText(byte qualifier,
byte dcs,
byte[] buffer,
short offset,
short length) throws NullPointerException,
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.
*
* <p>
* Notes:<ul>
* <li><em>If </em><code>offset</code><em> or
* </em><code>length</code><em> parameter is negative an
* </em><code>ArrayIndexOutOfBoundsException</code>
* <em> exception is thrown and no proactive command is build.</em>
* <li><em>If </em><code>offset+length</code><em> is greater than
* </em><code>buffer.length</code><em>, the length
* of the </em><code>buffer</code><em> array an
* </em><code>ArrayIndexOutOfBoundsException</code><em> exception
* is thrown and no proactive command is build.</em>
* </ul>
*
* @param qualifier Get Inkey command qualifier
* @param dcs data coding scheme
* @param buffer reference to the displayed text string source buffer
* @param offset offset of the displayed text string in the source buffer
* @param length length of the displayed text string in the source buffer
*
* @exception NullPointerException if <code>buffer</code> is
* <code>null</code>
* @exception ArrayIndexOutOfBoundsException if initGetInkey would
* cause access of data outside array bounds.
* @exception ToolkitException with the following reason codes: <ul>
* <li><code>HANDLER_OVERFLOW</code> if the ProactiveHandler buffer
* is to small to put the requested data</ul>
*/
public void initGetInkey(byte qualifier,
byte dcs,
byte[] buffer,
short offset,
short length) throws NullPointerException,
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.
*
* <p>
* Notes:<ul>
* <li><em>If </em><code>offset</code><em> or </em><code>length</code><em>
* parameter is negative an
* </em><code>ArrayIndexOutOfBoundsException</code>
* <em> exception is thrown and no proactive command is build.</em>
* <li><em>If </em><code>offset+length</code><em>is greater than
* </em><code>buffer.length</code><em>, the length
* of the </em><code>buffer</code><em> array an
* </em><code>ArrayIndexOutOfBoundsException</code><em> exception is thrown
* and no proactive command is build.</em>
* </ul>
*
* @param qualifier Get Input command qualifier
* @param dcs data coding scheme
* @param buffer reference to the displayed text string source buffer
* @param offset offset of the displayed text string in the source buffer
* @param length length of the displayed text string in the source buffer
* @param minRespLength minimal length of the response text string
* @param maxRespLength maximal length of the response text string
*
* @exception NullPointerException if <code>buffer</code> is
* <code>null</code>
* @exception ArrayIndexOutOfBoundsException if initGetInput would cause
* access of data outside array bounds.
* @exception ToolkitException with the following reason codes: <ul>
* <li><code>HANDLER_OVERFLOW</code> if the ProactiveHandler buffer
* is to small to put the requested data</ul>
*/
public void initGetInput(byte qualifier,
byte dcs,
byte[] buffer,
short offset,
short length,
short minRespLength,
short maxRespLength) throws NullPointerException,
ArrayIndexOutOfBoundsException,
ToolkitException {
}
}
|
