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: import javacard.framework.Util;
036:
037: /**
038: *
039: * The EnvelopeHandler class contains basic methods to handle the <b>Envelope
040: * </b>data field. This class will be used by the Toolkit applet in order to
041: * have access to the current Envelope information. No constructor is available
042: * for the Toolkit applet. The EnvelopeHandler class is a <b>Temporary JCRE
043: * Entry Point Object</b>. The only way to get a EnvelopeHandler reference is
044: * through the <code>getTheHandler()</code> static method.<p>
045: *
046: * Toolkit Applet Example:<pre><code>
047: * private static final byte MY_TAG = (byte)0x54;
048: * private byte[] data;
049: * data = new byte[32];
050: *
051: * void processToolkit(byte event) throws ToolkitException {
052: * // get the EnvelopeHandler system instance
053: * EnvelopeHandler theEnv = EnvelopeHandler.getTheHandler();
054: * // look for MY_TAG TLV
055: * if (theEnv.findTLV(MY_TAG, (byte)1) != TLV_NOT_FOUND) {
056: * // check first element byte
057: * if (theEnv.getValueByte((short)0) == (byte)1) {
058: * // copy element part into data buffer
059: * theEnv.copyValue((short)1,
060: * data,
061: * (short)0,
062: * (short)(theEnv.getValueLength() - 1));
063: * }
064: * }
065: * }
066: * </code></pre>
067: *
068: * @version 8.3.0
069: *
070: * @see ViewHandler
071: * @see EnvelopeResponseHandler
072: * @see ProactiveHandler
073: * @see ToolkitException
074: */
075: public final class EnvelopeHandler extends ViewHandler {
076:
077: // ------------------------------- Constructors ---------------------------
078: /**
079: * constructor
080: */
081: private EnvelopeHandler() {
082: }
083:
084: // ------------------------------- Public methods -------------------------
085: /**
086: * Returns the single system instance of the EnvelopeHandler class.
087: * The applet shall get the reference of the handler at its triggering,
088: * the beginning of the processToolkit method.
089: *
090: * @return reference of the system instance
091: *
092: * @exception ToolkitException with the following reason codes: <ul>
093: * <li><code>HANDLER_NOT_AVAILABLE</code> if the handler is busy.</ul>
094: */
095: public static EnvelopeHandler getTheHandler()
096: throws ToolkitException {
097: EnvelopeHandler theEnvelopeHandler = new EnvelopeHandler();
098: // BER TLV offset is 5 in the buffer
099: // offset for the first TLV would be BER TLV offset + 2
100: theEnvelopeHandler.firstTLVOffset = (short) (BER_TLV_TAG_OFFSET + 2);
101: theEnvelopeHandler.currentTLVOffset = (short) (BER_TLV_TAG_OFFSET + 2);
102:
103: return theEnvelopeHandler;
104: }
105:
106: /**
107: * Returns the Envelope BER-TLV tag.
108: *
109: * @return Envelope BER-TLV tag
110: */
111: public byte getEnvelopeTag() {
112: byte[] buffer = ViewHandler.getAPDUBuffer();
113: return buffer[BER_TLV_TAG_OFFSET];
114: }
115:
116: /**
117: * Looks for the TP-UDL field in the first TPDU TLV element in the Envelope
118: * data field. This method can be used on the events
119: * EVENT_FORMATTED_SMS_PP_ENV,
120: * EVENT_FORMATTED_SMS_PP_UPD, EVENT_UNFORMATTED_SMS_PP_ENV,
121: * EVENT_UNFORMATTED_SMS_PP_UPD.
122: * If the element is available it becomes the TLV selected.
123: *
124: * @return TPUDL offset in the first TPDU TLV element if TPUDL exists.
125: * The TPUD length can be recovered by using the getValueByte method
126: * in Handler class.
127: *
128: * @exception ToolkitException with the following reason codes: <ul>
129: * <li><code>UNAVAILABLE_ELEMENT</code> in case of unavailable TPDU
130: * TLV element or if the TPUDL field does not exist</ul>
131: */
132: public short getTPUDLOffset() throws ToolkitException {
133: // get to the SMS TLV
134: byte[] buffer = ViewHandler.getAPDUBuffer();
135: short Lc = buffer[OFFSET_LC];
136: short SMSTLVOffset = getTLVOffset(buffer,
137: ToolkitConstants.TAG_SMS_TPDU, Lc, (byte) 1);
138: if (SMSTLVOffset >= Lc)
139: ToolkitException
140: .throwIt(ToolkitException.UNAVAILABLE_ELEMENT);
141:
142: currentTLVOffset = SMSTLVOffset;
143:
144: return 0;
145: }
146:
147: /**
148: * Looks for the Secured Data from the Command Packet in the first SMS
149: * TPDU or Cell Broadcast Page Simple TLV contained in the Envelope
150: * handler. This can be used on the events:
151: * - EVENT_FORMATTED_SMS_PP_ENV, EVENT_FORMATTED_SMS_PP_UPD,
152: * if the SMS TP-UD is formatted according to GSM03.48 Single
153: * Short Message.
154: * - EVENT_FORMATTED_SMS_CB, if the Cell Broadcast Page is formatted
155: * according to GSM 03.48.
156: * If the element is available it becomes the TLV selected.
157: *
158: * @return the offset of the Secured Data first byte in the first
159: * SMS TPDU or Cell Broadcast Page TLV element. If the Secured Data
160: * length is zero the value returned shall be the SMS TPDU TLV length.
161: *
162: * @exception ToolkitException with the following reason codes: <ul>
163: * <li><code>UNAVAILABLE_ELEMENT</code> in case of unavailable
164: * SMS TPDU or Cell Broadcast Page TLV element or
165: * wrong data format </ul>
166: */
167:
168: public short getSecuredDataOffset() throws ToolkitException {
169: return 0;
170: }
171:
172: /**
173: * Looks for the length of the Secured Data from the Command Packet
174: * in the first SMS TPDU or Cell Broadcast Page Simple TLV contained
175: * in the Envelope handler. This can be used on the events:
176: * - EVENT_FORMATTED_SMS_PP_ENV, EVENT_FORMATTED_SMS_PP_UPD,
177: * if the SMS TP-UD is formatted according to GSM03.48 Single
178: * Short Message.
179: * - EVENT_FORMATTED_SMS_CB, if the Cell Broadcast Page is formatted
180: * according to GSM 03.48.
181: * If the element is available it becomes the TLV selected.
182: *
183: * @return the length of the Secured Data contained in the first SMS
184: * TPDU or Cell Broadcast Page TLV element (without padding bytes).
185: * If the Secured Data length is zero, no exception shall be thrown.
186: *
187: * @exception ToolkitException with the following reason codes: <ul>
188: * <li><code>UNAVAILABLE_ELEMENT</code> in case of unavailable
189: * SMS TPDU or Cell Broadcast Page TLV element or wrong data
190: * format </ul>
191: */
192:
193: public short getSecuredDataLength() throws ToolkitException {
194: return 0;
195: }
196:
197: /**
198: * Returns the item identifier byte value from the first Item
199: * Identifier TLV element in the current Envelope data field.
200: * If the element is available it becomes the TLV selected.
201: *
202: * @return item identifier
203: *
204: * @exception ToolkitException with the following reason codes: <ul>
205: * <li><code>UNAVAILABLE_ELEMENT</code> in case of unavailable
206: * TLV element
207: * <li><code>OUT_OF_TLV_BOUNDARIES</code> if the item identifier
208: * byte is missing in the Item Identifier Simple TLV </ul>
209: */
210: public byte getItemIdentifier() throws ToolkitException {
211: byte[] buffer = ViewHandler.getAPDUBuffer();
212: currentTLVOffset = firstTLVOffset;
213: return buffer[firstTLVOffset];
214: }
215: }
|