/*
*
*
* Copyright 1990-2009 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
//-----------------------------------------------------------------------------
import javacard.framework.Shareable;
/**
* This interface must be implemented by a Toolkit applet (which extends
* the <code>javacard.framework.Applet</code> class) so that it can be
* triggered by the Toolkit Handler according to the registration information.
* The Toolkit applet will have to implement the processToolkit shared method
* so that it can be notified of the following events :
*
* EVENT_PROFILE_DOWNLOAD
* EVENT_FORMATTED_SMS_PP_ENV
* EVENT_FORMATTED_SMS_PP_UPD
* EVENT_UNFORMATTED_SMS_PP_ENV
* EVENT_UNFORMATTED_SMS_PP_UPD
* EVENT_UNFORMATTED_SMS_CB
* EVENT_MENU_SELECTION
* EVENT_MENU_SELECTION_HELP_REQUEST
* EVENT_CALL_CONTROL_BY_SIM
* EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM
* EVENT_TIMER_EXPIRATION
* EVENT_EVENT_DOWNLOAD_MT_CALL
* EVENT_EVENT_DOWNLOAD_CALL_CONNECTED
* EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED
* EVENT_EVENT_DOWNLOAD_LOCATION_STATUS
* EVENT_EVENT_DOWNLOAD_USER_ACTIVITY
* EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE
* EVENT_EVENT_DOWNLOAD_CARD_READER_STATUS
* EVENT_STATUS_COMMAND
* EVENT_UNRECOGNIZED_ENVELOPE
*
*
* Toolkit applet example :<pre><code>
* import javacard.framework.*;
* import sim.toolkit.*;
* //
* // The HelloWorld class is a simple Toolkit applet, which may be used as an
* // example to show how such an applet will be installed and registered and
* // how it will be triggered.
* //
* public class HelloWorld extends Applet implements
* ToolkitInterface,ToolkitConstants {
* // data fields
* private static final byte CMD_QUALIFIER = (byte)0x80;
* private byte[] menuEntry = {'S','e','r','v','i','c','e','1'};
* private byte[] textBuf = {'H','e','l','l','o',' ',
* 'w','o','r','l','d',' ','!'};
* private ToolkitRegistry reg;
* //
* // Constructor of applet
* //
* public HelloWorld() {
* // get a Registry object...
* // ...and initialize it according to the applet characteristics
* reg.initMenuEntry(menuEntry, (short)0, (short)menuEntry.length,
* PRO_CMD_DISPLAY_TEXT, false, 0, 0);
* }
* //
* // Install method
* // *param bArray the array containing installation parameters
* // *param bOffset the starting offset in bArray
* // *param bLength the length in bytes of the parameter data in bArray
* //
* public static void install(byte bArray[], short bOffset, byte bLength)
* throws ISOException {
* // create and register applet
* HelloWorld HelloWorldApplet = new HelloWorld();
* HelloWorldApplet.register();
* }
* //
* // Process toolkit events
* // *param event the type of event to be processed
* // *exception ToolkitException
* //
* public void processToolkit(byte event) throws ToolkitException {
* // get the ProactiveHandler system instance
* ProactiveHandler proHdlr = ProactiveHandler.getTheHandler();
*
* if (event == EVENT_MENU_SELECTION) {
* // prepare a Display Text command
* proHdlr.init((byte) PRO_CMD_DISPLAY_TEXT,
* (byte)CMD_QUALIFIER, (byte)0x02);
* proHdlr.appendTLV((byte)(TAG_TEXT_STRINGTAG_SET_CR), textBuf,
* (short)0, (short)textBuf.length);
* proHdlr.send();
* }
* }
* }
* </code></pre>
*
* @version 8.3.0
*
* @see ToolkitRegistry
* @see ToolkitException
* @see ToolkitConstants
*/
public interface ToolkitInterface extends Shareable {
// ------------------------------- Public methods -------------------------
/**
* This method is the standard toolkit event handling method of a Toolkit
* applet and
* is called by the Toolkit Handler to process the current Toolkit event.
* This method is invoked for notification of registered events.
*
* @param event the type of event to be processed.
*
* @exception ToolkitException
*
* @see sim.toolkit.ToolkitRegistry#getEntry()
*/
public void processToolkit(byte event) throws ToolkitException;
/**
* Returns the APDUBuffer.
* @return apdu buffer
* @throws ToolkitException if an error occures
*/
public byte[] getAPDUBuffer() throws ToolkitException;
/**
* Returns the ToolkitException instance.
* @return ToolkitException instance
*/
public ToolkitException getToolkitExceptionInstance();
}