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.Shareable;
036:
037: /**
038: * This interface must be implemented by a Toolkit applet (which extends
039: * the <code>javacard.framework.Applet</code> class) so that it can be
040: * triggered by the Toolkit Handler according to the registration information.
041: * The Toolkit applet will have to implement the processToolkit shared method
042: * so that it can be notified of the following events :
043: *
044: * EVENT_PROFILE_DOWNLOAD
045: * EVENT_FORMATTED_SMS_PP_ENV
046: * EVENT_FORMATTED_SMS_PP_UPD
047: * EVENT_UNFORMATTED_SMS_PP_ENV
048: * EVENT_UNFORMATTED_SMS_PP_UPD
049: * EVENT_UNFORMATTED_SMS_CB
050: * EVENT_MENU_SELECTION
051: * EVENT_MENU_SELECTION_HELP_REQUEST
052: * EVENT_CALL_CONTROL_BY_SIM
053: * EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM
054: * EVENT_TIMER_EXPIRATION
055: * EVENT_EVENT_DOWNLOAD_MT_CALL
056: * EVENT_EVENT_DOWNLOAD_CALL_CONNECTED
057: * EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED
058: * EVENT_EVENT_DOWNLOAD_LOCATION_STATUS
059: * EVENT_EVENT_DOWNLOAD_USER_ACTIVITY
060: * EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE
061: * EVENT_EVENT_DOWNLOAD_CARD_READER_STATUS
062: * EVENT_STATUS_COMMAND
063: * EVENT_UNRECOGNIZED_ENVELOPE
064: *
065: *
066: * Toolkit applet example :<pre><code>
067: * import javacard.framework.*;
068: * import sim.toolkit.*;
069: * //
070: * // The HelloWorld class is a simple Toolkit applet, which may be used as an
071: * // example to show how such an applet will be installed and registered and
072: * // how it will be triggered.
073: * //
074: * public class HelloWorld extends Applet implements
075: * ToolkitInterface,ToolkitConstants {
076: * // data fields
077: * private static final byte CMD_QUALIFIER = (byte)0x80;
078: * private byte[] menuEntry = {'S','e','r','v','i','c','e','1'};
079: * private byte[] textBuf = {'H','e','l','l','o',' ',
080: * 'w','o','r','l','d',' ','!'};
081: * private ToolkitRegistry reg;
082: * //
083: * // Constructor of applet
084: * //
085: * public HelloWorld() {
086: * // get a Registry object...
087: * // ...and initialize it according to the applet characteristics
088: * reg.initMenuEntry(menuEntry, (short)0, (short)menuEntry.length,
089: * PRO_CMD_DISPLAY_TEXT, false, 0, 0);
090: * }
091: * //
092: * // Install method
093: * // *param bArray the array containing installation parameters
094: * // *param bOffset the starting offset in bArray
095: * // *param bLength the length in bytes of the parameter data in bArray
096: * //
097: * public static void install(byte bArray[], short bOffset, byte bLength)
098: * throws ISOException {
099: * // create and register applet
100: * HelloWorld HelloWorldApplet = new HelloWorld();
101: * HelloWorldApplet.register();
102: * }
103: * //
104: * // Process toolkit events
105: * // *param event the type of event to be processed
106: * // *exception ToolkitException
107: * //
108: * public void processToolkit(byte event) throws ToolkitException {
109: * // get the ProactiveHandler system instance
110: * ProactiveHandler proHdlr = ProactiveHandler.getTheHandler();
111: *
112: * if (event == EVENT_MENU_SELECTION) {
113: * // prepare a Display Text command
114: * proHdlr.init((byte) PRO_CMD_DISPLAY_TEXT,
115: * (byte)CMD_QUALIFIER, (byte)0x02);
116: * proHdlr.appendTLV((byte)(TAG_TEXT_STRINGTAG_SET_CR), textBuf,
117: * (short)0, (short)textBuf.length);
118: * proHdlr.send();
119: * }
120: * }
121: * }
122: * </code></pre>
123: *
124: * @version 8.3.0
125: *
126: * @see ToolkitRegistry
127: * @see ToolkitException
128: * @see ToolkitConstants
129: */
130: public interface ToolkitInterface extends Shareable {
131:
132: // ------------------------------- Public methods -------------------------
133:
134: /**
135: * This method is the standard toolkit event handling method of a Toolkit
136: * applet and
137: * is called by the Toolkit Handler to process the current Toolkit event.
138: * This method is invoked for notification of registered events.
139: *
140: * @param event the type of event to be processed.
141: *
142: * @exception ToolkitException
143: *
144: * @see sim.toolkit.ToolkitRegistry#getEntry()
145: */
146: public void processToolkit(byte event) throws ToolkitException;
147:
148: /**
149: * Returns the APDUBuffer.
150: * @return apdu buffer
151: * @throws ToolkitException if an error occures
152: */
153: public byte[] getAPDUBuffer() throws ToolkitException;
154:
155: /**
156: * Returns the ToolkitException instance.
157: * @return ToolkitException instance
158: */
159: public ToolkitException getToolkitExceptionInstance();
160: }
|