001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: //-----------------------------------------------------------------------------
028: // PACKAGE DEFINITION
029: //-----------------------------------------------------------------------------
030: package sim.toolkit;
031:
032: //-----------------------------------------------------------------------------
033: // IMPORTS
034: //-----------------------------------------------------------------------------
035:
036: /**
037: *
038: * This class is the basic class for the definition of
039: * <b>Proactive commands
040: * </b>. Low level methods, as <code>init()</code>, <code>appendTLV()</code>...
041: * will be used to handle generic Proactive commands (standard or future
042: * definitions...). The ProactiveHandler class is a <b>Temporary JCRE Entry
043: * Point Object</b>.
044: * The Toolkit applets, which need to send Proactive commands,
045: * shall call the <code>getTheHandler()</code> static method to get the
046: * reference of this system instance.<p>
047: *
048: * Example of use:<pre><code>
049: * // constants definition
050: * private static final byte MY_COMMAND = (byte)0x33;
051: * private static final byte MY_TAG = (byte)0x45;
052: *
053: * ProactiveHandler proHdlr; // get the system instance
054: * proHdlr = ProactiveHandler.getTheHandler();
055: *
056: * // build and send a new Proactive
057: * // command
058: * proHdlr.init(MY_COMMAND, (byte)0, DEV_ID_ME);
059: * proHdlr.appendTLV((byte)(MY_TAG | TAG_SET_CR),
060: * (byte)0);
061: * short len = proHdlr.getLength(); // length should be 14 !
062: * byte result = proHdlr.send();
063: *
064: * private byte[] text = new byte[12]; // byte array definition
065: * text[0] = (byte)'S'; // text, in 8-bit format, is "SAT"
066: * text[1] = (byte)'A';
067: * text[2] = (byte)'T';
068: * // build and send a DisplayText command
069: * result = proHdlr.initDisplayText((byte)0x80, DCS_8_BIT_DATA,
070: * text, (short)0, (short)3);
071: * result = proHdlr.send();
072: * </code></pre>
073: *
074: * @version 8.3.0
075: *
076: * @see ViewHandler
077: * @see EditHandler
078: * @see ProactiveResponseHandler
079: * @see ToolkitException
080: */
081: public final class ProactiveHandler extends EditHandler {
082:
083: // ------------------------------- Constructors ---------------------------
084: /**
085: * Constructor
086: */
087: private ProactiveHandler() {
088: }
089:
090: // ------------------------------- Public methods -------------------------
091: /**
092: * Returns the single system instance of the ProactiveHandler class.
093: * The applet shall get the reference of the handler at its triggering,
094: * the beginning of the processToolkit method.
095: *
096: * @return reference of the system instance
097: *
098: * @exception ToolkitException with the following reason codes: <ul>
099: * <li><code>HANDLER_NOT_AVAILABLE</code> if the handler is busy.</ul>
100: */
101: public static ProactiveHandler getTheHandler()
102: throws ToolkitException {
103: return null;
104: }
105:
106: /**
107: * Initializes the next Proactive command with Command Details and Device
108: * Identities TLV.
109: * The source device is always the SIM card. The command number is
110: * generated by the method. The Comprehension Required flags are set.
111: * After the method invocation no TLV is selected.
112: *
113: * @param type the command type
114: * @param qualifier the command qualifier
115: * @param dstDevice the destination device
116: */
117: public void init(byte type, byte qualifier, byte dstDevice) {
118: }
119:
120: /**
121: * Sends the current Proactive command.
122: *
123: * @return general result of the command (first byte of Result TLV in
124: * Terminal Response)
125: *
126: * @exception ToolkitException with the following reason codes: <ul>
127: * <li><code>UNAVAILABLE_ELEMENT</code> if the Result Simple TLV
128: * is missing.
129: * <li><code>OUT_OF_TLV_BOUNDARIES</code> if the general result
130: * byte is missing in the Result Simple TLV.</ul>
131: */
132: public byte send() throws ToolkitException {
133: return 0;
134: }
135:
136: /**
137: * Builds a Display Text Proactive command without sending the command.
138: * The Comprehension
139: * Required flags are all set to 1.
140: * After the method invocation no TLV is selected.
141: *
142: * <p>
143: * Notes:<ul>
144: * <li><em>If </em><code>offset</code><em> or </em><code>length</code><em>
145: * parameter is negative an
146: * </em><code>ArrayIndexOutOfBoundsException</code>
147: * <em> exception is thrown and no proactive command is build.</em>
148: * <li><em>If </em><code>offset+length</code><em> is greater than
149: * </em><code>buffer.length</code><em>, the length
150: * of the </em><code>buffer</code><em> array an
151: * </em><code>ArrayIndexOutOfBoundsException</code><em> exception is thrown
152: * and no proactive command is build.</em>
153: * </ul>
154: *
155: * @param qualifier Display Text command qualifier
156: * @param dcs data coding scheme
157: * @param buffer reference to the text string source buffer
158: * @param offset offset of the text string in the source buffer
159: * @param length length of the text string in the source buffer
160: *
161: * @exception NullPointerException if <code>buffer</code> is
162: * <code>null</code>
163: * @exception ArrayIndexOutOfBoundsException if initDisplayText would
164: * cause access of data outside array bounds
165: * @exception ToolkitException with the following reason codes: <ul>
166: * <li><code>HANDLER_OVERFLOW</code> if the ProactiveHandler buffer
167: * is to small to put the requested data </ul>
168: */
169: public void initDisplayText(byte qualifier, byte dcs,
170: byte[] buffer, short offset, short length)
171: throws NullPointerException,
172: ArrayIndexOutOfBoundsException, ToolkitException {
173: }
174:
175: /**
176: * Builds a Get Inkey Proactive command without sending the command.
177: * The Comprehension
178: * Required flags are all set to 1.
179: * After the method invocation no TLV is selected.
180: *
181: * <p>
182: * Notes:<ul>
183: * <li><em>If </em><code>offset</code><em> or
184: * </em><code>length</code><em> parameter is negative an
185: * </em><code>ArrayIndexOutOfBoundsException</code>
186: * <em> exception is thrown and no proactive command is build.</em>
187: * <li><em>If </em><code>offset+length</code><em> is greater than
188: * </em><code>buffer.length</code><em>, the length
189: * of the </em><code>buffer</code><em> array an
190: * </em><code>ArrayIndexOutOfBoundsException</code><em> exception
191: * is thrown and no proactive command is build.</em>
192: * </ul>
193: *
194: * @param qualifier Get Inkey command qualifier
195: * @param dcs data coding scheme
196: * @param buffer reference to the displayed text string source buffer
197: * @param offset offset of the displayed text string in the source buffer
198: * @param length length of the displayed text string in the source buffer
199: *
200: * @exception NullPointerException if <code>buffer</code> is
201: * <code>null</code>
202: * @exception ArrayIndexOutOfBoundsException if initGetInkey would
203: * cause access of data outside array bounds.
204: * @exception ToolkitException with the following reason codes: <ul>
205: * <li><code>HANDLER_OVERFLOW</code> if the ProactiveHandler buffer
206: * is to small to put the requested data</ul>
207: */
208: public void initGetInkey(byte qualifier, byte dcs, byte[] buffer,
209: short offset, short length) throws NullPointerException,
210: ArrayIndexOutOfBoundsException, ToolkitException {
211: }
212:
213: /**
214: * Initialize the building of a Get Input Proactive command. The
215: * Comprehension Required flags are all set to 1.
216: * The following command parameters (i.e. TLVs) may be appended to the
217: * command before sending it: Default Text.
218: * After the method invocation no TLV is selected.
219: *
220: * <p>
221: * Notes:<ul>
222: * <li><em>If </em><code>offset</code><em> or </em><code>length</code><em>
223: * parameter is negative an
224: * </em><code>ArrayIndexOutOfBoundsException</code>
225: * <em> exception is thrown and no proactive command is build.</em>
226: * <li><em>If </em><code>offset+length</code><em>is greater than
227: * </em><code>buffer.length</code><em>, the length
228: * of the </em><code>buffer</code><em> array an
229: * </em><code>ArrayIndexOutOfBoundsException</code><em> exception is thrown
230: * and no proactive command is build.</em>
231: * </ul>
232: *
233: * @param qualifier Get Input command qualifier
234: * @param dcs data coding scheme
235: * @param buffer reference to the displayed text string source buffer
236: * @param offset offset of the displayed text string in the source buffer
237: * @param length length of the displayed text string in the source buffer
238: * @param minRespLength minimal length of the response text string
239: * @param maxRespLength maximal length of the response text string
240: *
241: * @exception NullPointerException if <code>buffer</code> is
242: * <code>null</code>
243: * @exception ArrayIndexOutOfBoundsException if initGetInput would cause
244: * access of data outside array bounds.
245: * @exception ToolkitException with the following reason codes: <ul>
246: * <li><code>HANDLER_OVERFLOW</code> if the ProactiveHandler buffer
247: * is to small to put the requested data</ul>
248: */
249: public void initGetInput(byte qualifier, byte dcs, byte[] buffer,
250: short offset, short length, short minRespLength,
251: short maxRespLength) throws NullPointerException,
252: ArrayIndexOutOfBoundsException, ToolkitException {
253: }
254: }
|