GSM 03.19
-
Upload
goutam-kumar-rana -
Category
Documents
-
view
143 -
download
13
Transcript of GSM 03.19
ETSI SMG #28 Tdoc P-99-1828- 12February, 1999Milano, Italy
European Telecommunications Standards Institute
GSM 03.19 V1.0.0 (1999-01)Technical Specification
Digital cellular telecommunications system (Phase 2+);Subscriber Identity Module Application Programming Interface
(SIM API);SIM API for Java Card™ ;
Stage 2
GLOBAL SYSTEM FOR MOBILE COMMUNICATIONS
R
GSM 03.19 V1.0.0 (1999-01)2
ReferenceDTS/SMG-090219N (2100001f.PDF)
KeywordsDigital cellular telecommunications system,
Global System for Mobile communications (GSM)
ETSI Secretariat
Postal addressF-06921 Sophia Antipolis Cedex - FRANCE
Office address650 Route des Lucioles - Sophia Antipolis
Valbonne - FRANCETel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16
Siret N° 348 623 562 00017 - NAF 742 CAssociation à but non lucratif enregistrée à laSous-Préfecture de Grasse (06) N° 7803/88
[email protected]://www.etsi.fr
http://www.etsi.org
Copyright Notification
No part may be reproduced except as authorized by written permission.The copyright and the foregoing restriction extend to reproduction in all media.
© European Telecommunications Standards Institute 1998.All rights reserved.
GSM 03.19 V1.0.0 (1999-01)3
Contents
Intellectual Property Rights ............................................................................................................................... 4
Foreword............................................................................................................................................................ 4
1 Scope ....................................................................................................................................................... 5
2 References ............................................................................................................................................... 52.1 Normative references .........................................................................................................................................5
3 Definitions and abbreviations.................................................................................................................. 63.1 Definitions..........................................................................................................................................................63.2 Abbreviations .....................................................................................................................................................6
4 Description .............................................................................................................................................. 74.1 GSM Java Card Architecture .............................................................................................................................74.2 Java Card Selection Mechanism.........................................................................................................................8
5 GSM framework...................................................................................................................................... 85.1 Overview............................................................................................................................................................85.2 GSM file data access..........................................................................................................................................85.3 Access control ....................................................................................................................................................85.4 GSM low Level API...........................................................................................................................................8
6 SIM Toolkit framework........................................................................................................................... 96.1 Overview............................................................................................................................................................96.2 Applet Triggering...............................................................................................................................................96.3 Registration ......................................................................................................................................................116.4 Proactive command handling ...........................................................................................................................116.5 Envelope response handling.............................................................................................................................12
7 SIM Toolkit applet ................................................................................................................................ 127.1 Applet Loading.................................................................................................................................................127.2 Object Sharing..................................................................................................................................................12
Annex A (normative): Java Card SIM API ................................................................................................ 13
Annex B (normative): Java Card SIM API identifiers .............................................................................. 14
Annex C (informative): toolkit applet example .......................................................................................... 15
History ............................................................................................................................................................. 17
GSM 03.19 V1.0.0 (1999-01)4
Intellectual Property RightsIPRs essential or potentially essential to the present document may have been declared to ETSI. The informationpertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be foundin ETR 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in respect ofETSI standards", which is available free of charge from the ETSI Secretariat. Latest updates are available on the ETSIWeb server (http://www.etsi.fr/ipr).
Pursuant to the ETSI Interim IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. Noguarantee can be given as to the existence of other IPRs not referenced in ETR 314 (or the updates onhttp://www.etsi.fr/ipr) which are, or may be, or may become, essential to the present document.
Java and Java Card are trademarks of SUN Microsystems.
ForewordThis draft ETSI Technical Specification has been produced by Special Mobile Group (SMG) of the EuropeanTelecommunications Standards Institute (ETSI).
In analogy with CCITT Recommendations I.130, the first stage of the following three level structure is used to describethe telecommunications services as provided by European public telecommunications operators:
Stage 1 is an overall service description, from the service subscriber's and user's standpoint;
Stage 2 identifies the functional capabilities and information flows needed to support the service describedin stage 1; and
Stage 3 defines the signalling system protocols and switching functions needed to implement the servicedescribed in stage 1.
This TS details the stage 2 aspects (functional capabilities) for the support of a Subscriber Identity Module ApplicationProgramming Interface (SIM API)
The contents of this TS are subject to continuing work within SMG and may change following formal SMG approval.Should SMG modify the contents of this TS it will then be republished by ETSI with an identifying change of releasedate and an increase in version number as follows:
Version 5.x.y
where:
y the third digit is incremented when editorial only changes have been incorporated in the specification;
x the second digit is incremented for all other types of changes, i.e. technical enhancements, corrections,updates, etc.
GSM 03.19 V1.0.0 (1999-01)5
1 ScopeThis ETSI Technical Specification defines the stage two description of the Subscriber Identity Module ApplicationProgramming Interface (SIM API) internal to the SIM.
This stage two describes the functional capabilities and the information flow for the SIM API implemented on the JavaCard 2.1 API specification [6].
This TS includes information applicable to network operators, service providers and SIM, server and databasemanufacturers.
2 ReferencesReferences may be made to:
a) specific versions of publications (identified by date of publication, edition number, version number, etc.), inwhich case, subsequent revisions to the referenced document do not apply; or
b) all versions up to and including the identified version (identified by "up to and including" before the versionidentity); or
c) all versions subsequent to and including the identified version (identified by "onwards" following the versionidentity); or
d) publications without mention of a specific version, in which case the latest version applies.
A non-specific reference to an ETS shall also be taken to refer to later versions published as an EN with the samenumber.
2.1 Normative references[1] GSM 01.04 (ETR 350): “Digital cellular telecommunications system (Phase 2+); Abbreviations
and acronyms”.
[2] GSM 11.11 (ETS 300 977): “Digital cellular telecommunications system (Phase 2+); Specificationof the Subscriber Identity Module - Mobile Equipment (SIM - ME) interface”.
[3] GSM 11.14 “Digital cellular telecommunication system (Phase 2+, Release 97); Specification ofthe SIM Application Toolkit for the Subscriber Identity Module - Mobile Equipment (SIM - ME)interface”.
[4] GSM 03.48 "Digital cellular telecommunications system (Phase 2+); Security Mechanisms for theSIM application toolkit; Stage 2"
[5] ISO/IEC 7816-3 (1997) " Identification cards - Integrated circuit(s) cards with contacts, Part 3:Electronic signals and transmission protocols"
[6] GSM 02.19 " Digital cellular telecommunications system (Phase 2+); Subscriber Identity ModuleApplication Programming Interface (SIM API); Service description; Stage 1"
[7] SUN Java Card Specification "Java Card 2.1 API Specification "
[8] SUN Java Card Specification "Java Card 2.1 Runtime Environment Specification"
[9] SUN Java Card Specification "Java Card 2.1 VM Architecture Specification"
SUN Java Card Specifications can be downloaded at http://java.sun.com/products/javacard
GSM 03.19 V1.0.0 (1999-01)6
3 Definitions and abbreviations
3.1 DefinitionsFor the purposes of this TS the following definitions apply:
Applet: An Applet is an application built up using a number of classes which will run under the control of the Java Cardvirtual machine. Applets designed for smart cards are sometimes referred to as Cardlets.
Bytecode: Machine independent code generated by a Java compiler and executed by the Java interpreter.
Class: The Class is a type that defines the implementation of a particular kind of object. A Class definition definesinstance and class variables and methods.
Framework: A framework defines a set of Application Programming Interface (API) classes for developingapplications and for providing system services to those applications.
GSM applet: The GSM application conforming to GSM 11.11. It might be a Java Card applet or native application.
Java: An object oriented programming language developed by Sun Microsystems designed to be platform independent.
Method: A Method is a piece of executable code that can be invoked, possibly passing it certain values as arguments.Every Method definition belongs to some class.
Object:The principal building block of object oriented programs. Each object is a programming unit consisting of data(variables) and functionality (methods)
Package: A group of classes. Packages are declared when writing a Java Card program
Proactive applet: Applet loaded onto the SIM card seen by the Mobile as being part of the SIM Toolkit application andcontaining only the code necessary to run the application. These applets might be downloaded over the radio interface.
Toolkit Framework: Part of the SIM card responsible for the handling of applications (including triggering andloading). It also contains the library for the proactive API.
Virtual Machine: The part of the Run-time environment responsible for interpreting the bytecode.
3.2 AbbreviationsFor the purposes of this TS the following abbreviations apply:
AC Application CodeAPDU Application Protocol Data UnitAPI Application Programming InterfaceCAD Card Acceptance DeviceFFS For Further StudyIFD Interface DeviceJCRE Java Card™ Run Time EnvironmentJVM Java Virtual MachineME Mobile EquipmentMS Mobile StationSIM Subscriber Identity ModuleSE Sending EntitySMS-CB Short Message Service – Cell BroadcastSMS-PP Short Message Service – Point to PointUSSD Unstructured Supplementary Services DataVM Virtual Machine
Further GSM related abbreviations are given in GSM 01.04 [1].
GSM 03.19 V1.0.0 (1999-01)7
4 DescriptionThis document describes an API for the GSM SIM. This API allows application programmers access to the functionsand data described in GSM 11.11 [2] and GSM 11.14 [3], such that SIM based services can be developed and loadedonto SIMs, quickly and, if necessarily, remotely, after the card has been issued.
This API is an extension to the Java Card 2.1 API [7] based on the Java Card 2.1 Runtime Environment [8].
4.1 GSM Java Card ArchitectureThe over all architecture of the SIM Toolkit API based on Java Card 2.1 is:
Applet n
…
Applet 1
JCRE
GSM
Applet Triggering
Toolkit
Figure 1: GSM Java Card architecture
GSM : this corresponds to the GSM application.
Toolkit : this handles the SIM Application Toolkit protocol, provides services to the applet to construct proactivecommands. The Applet Triggering based on the information provided by that layer will trigger the correspondingApplet.
Applet : Can be any kind of applet either using the GSM/toolkit facilities or just handling APDU.
Two selection mechanisms are available:
- JCRE : this handles all the applet as defined in Java Card 2.1 Runtime Environment Specification [8] it will be able toselect a any specific applet and send to it the corresponding APDU, the GSM application is the default applet.
- Applet Triggering : this is the GSM/toolkit method of selecting an applet according to the event appeared in the lowerlayer (GSM, Toolkit).
Applets loaded into a SIM Toolkit Java Card derives from either of the following classes:- javacard.framework.Applet- sim.toolkit.ToolkitApplet (which derives from javacard.framework.Applet)
Such an applet can handle two kinds entry points:- Java Card (i.e. process, select, deselect, install )- GSM/Toolkit activation events (i.e. processToolkit )
Applet n
processToolkit
select
process
Applet ..
processToolkit
select
process
Applet 1
processToolkit
select
process
JCRE
GSM
Toolkit
Figure 2: Toolkit applet entry points
GSM 03.19 V1.0.0 (1999-01)8
4.2 Java Card Selection MechanismThe Java Card selection mechanism is defined in the Java Card Runtime Environment Specification [8].
5 GSM framework
5.1 OverviewThe GSM Application is the default application, it owns the GSM files/data, handles all the GSM APDUs and passes allToolkit APDUs to the Toolkit framework.
The GSM framework is based on two packages:
- The GSM low level package [FFS];
- The sim.access package, which allows the GSM application to share data with the applets.
5.2 GSM file data accessThe following methods shall be offered by the API to card applets, to allow access to the GSM data:
select Select a file without changing the current file of any other applet or of the subscriber session. Atthe beginning of an entry point of an applet, the current file is the MF. This method returns theselected file information;
status Read the file status information of the current DF;readBinary Read data bytes of the transparent EF currently selected by the applet;readRecord Read data bytes of the linear fixed or cyclic EF currently selected by the applet without changing
the current record pointer of any other applet / subscriber. This method allows reading part of arecord;
updateBinary Modify data bytes of the transparent EF currently selected by the applet. The applet shall send thecorresponding refresh ;
updateRecord Modify data bytes of the linear fixed or cyclic EF currently selected by the applet. The currentrecord pointer of other applets / subscriber shall not be changed in case of linear fixed EF but therecord pointer of a cyclic EF shall be changed for all other applets / subscriber to the recordnumber 1. This method allows updating part of a record. The applet shall send the correspondingrefresh ;
seek Search a record of the linear fixed file currently selected by the applet starting with a given pattern.The current record pointer of any other applet or of the subscriber session shall not be changed;
increase Increase the value of the last updated record of the cyclic EF currently selected. It becomes thanrecord number 1 for every other applet and subscriber session. This method returns the increasedvalue. The applet shall send the corresponding refresh;
rehabilitate Rehabilitate the EF currently selected by the applet with effect for all other applets / subscriber.The applet shall send the corresponding refresh;
invalidate Invalidate the EF currently selected by the applet with effect for all other applets / subscriber. Theapplet shall send the corresponding refresh
These methods are described in the sim.access.SIMView interface in Annex A.
5.3 Access controlThe Access Control privileges of the applet are granted during installation according to the level of trust.
[FFS]
5.4 GSM low Level API[FFS. This API allows the implementation of the GSM application]
GSM 03.19 V1.0.0 (1999-01)9
6 SIM Toolkit framework
6.1 OverviewThe SIM API shall consist of APIs for GSM 11.14 [3] (pro-active functions) and GSM 11.11 [2] (transport functions).
ToolkitApplet 1 Applet 2
ToolkitApplet 3 Applet n
ProactiveCommand handler
GSM Framework Files
Toolkit Framework
Appletinstall/uninstall
Security
Applettriggering
Applet securitymanager
Activation
Proactivecommands
P/Cresponses
InstallUninstall
APDU
JCRE
APDUe.g.Envelopes
Proactive polling, 91XX, Fetch,Proactive commands,Terminal Response
Fileaccess
File access
…
(see NOTE 1)
NOTE 1: The install / uninstallprocess is defined inGSM xx.yy [ ]
sim.access packagesim.toolkit package
Figure 3: Toolkit framework architecture
In this model, the GSM data field structure is viewed as a series of data objects to the API. In the physical model ofcourse, they may still be stored in elementary fields, but classes will access these data as part of the objects within thoseclasses.
6.2 Applet TriggeringThe application triggering portion of the SIM Toolkit framework is responsible for the activation of toolkit applets,based on the APDU received by the GSM application.
APDU Applet Triggering
Menu Selected
SMS Received
Terminal Profile
...
GSM 03.19 V1.0.0 (1999-01)10
Figure 4: applet triggering diagram
The ME shall not be adversely affected by the presence of applets on the SIM card. For instance a syntactically correctEnvelope shall not result in an error status word in case of a failure of an applet. The only application as seen by the MEis the SIM application. As a result, a SIM Toolkit applet may throw an error, but this error will not be sent to the ME.
The difference between a Java Card applet and a Toolkit applet is that the latter does not handle APDUs directly. It willhandle higher level messages. Furthermore the execution of a method could span over multiple APDUs, in particular,the proactive protocol commands (Fetch, Terminal Response).
As seen above, when the SIM is the selected application and when a Toolkit applet is trigged the select() method of theapplet shall not be launched since the applet itself is not really selected.
Here after are the events that can trigger a SIM toolkit applet :
EVENT_PROFILE_DOWNLOAD
Upon reception of the Terminal Profile command by the SIM, one or more applications could be run ifregistered.
EVENT_MENU_SELECTION, EVENT_MENU_SELECTION_HELP_REQUEST
A toolkit applet might be activated upon selection in the ME’s menu by the user, or request help on thisspecific menu.
In order to allow the user to choose in a menu, the Toolkit Framework shall have previously issued a SET UPMENU proactive command. When an application which could be activated by menu is loaded into the SIM, theToolkit framework shall automatically update the menu stored in the ME.
[The order of the items in the SET UP MENU proactive command is for further study]
EVENT_FORMATTED_SMS_PP, EVENT_UNFORMATTED_SMS_PP
An application may be activated upon the reception of a short message.
There are two ways for a card to receive an SMS : via the Envelope SMS-PP Data Download or the UpdateRecord EFsms instruction.
The reception of the SMS by the applet cannot be guaranteed for the Update Record EFsms instruction.
The received SMS may be :- formatted according to GSM 03.48 or an other protocol to identify explicitly the applet for which the messageis send ;- unformatted or using an applet specific protocol the SIM toolkit framework will pass this data to a specificapplet which may than dispatch the message.
EVENT_UNFORMATTED_SMS_CB
When the ME receives a new cell broadcast message, the cell broadcast page may be passed to the SIM usingthe envelope command. E.g. the application may then read the message and extract a meaningful piece ofinformation which could be displayed to the user, for instance.
EVENT_CALL_CONTROL_BY_SIM
When the SIM is in call control mode and when the user dials a number, this number is passed to the SIM.Only one toolkit applet can handle the answer to this command: call barred, modified or accepted.
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
The applet will be triggered by the registered event download trigger, upon reception of the correspondingEnvelope command.
[The order in which the applets are triggered is for further study.]
GSM 03.19 V1.0.0 (1999-01)11
In order to allow the applet to be triggered by these events, the Toolkit Framework shall have previously issueda SET UP EVENT LIST proactive command. When an application which could be activated by these events isloaded into the SIM, the Toolkit framework shall automatically update the event list stored in the ME.
EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM
Before sending an SMS MO entered by the user, the SMS is submitted to the SIM. Only one applet can registerto this event
EVENT_UNRECOGNIZED_ENVELOPE
The unrecognised Envelope event will allow an applet to handle the evolution of the GSM 11.14 specification.
EVENT_PROPRIETARY_EVENT
This event can be used to trigger an application on proprietary events
EVENT_CARD_RESET
The applet can request to be triggered at the card reset.
Note: This is a critical phase in the card operation. Applets Triggered by this events shall not send proactivecommands and shall be trusted by the card issuer.
EVENT_STATUS_COMMAND
At reception of a STATUS APDU command, the Toolkit framework shall trigger the registered applet.
The applet shall be triggered for the registered events upon reception, and shall be able to access to the data associatedto the event using the methods provided by the sim.toolkit.ViewHandler.EnvelopeHandler class.
6.3 RegistrationDuring it's installation the applet shall register to the JCRE and the Toolkit framework so that it can be triggered by bothselection mechanisms.
The applet will have to call a registerToolkit() method to get a reference to it's registry and then to explicitly register toeach event it requires.
The applet can change the events to which it is registered during it’s life cycle.
The applet will automatically register to some event e.g. EVENT_MENU_SELECTION by calling the correspondingmethod e.g. createMenuEntry.
The API is described in the sim.toolkit.Registry class in Annex A.
6.4 Proactive command handlingThe SIM application toolkit protocol (i.e. 91xx, Fetch, Terminal Response) is handled by the Toolkit framework, theapplet shall not handle those events.
The Toolkit Framework shall provide a reference of the sim.toolkit.ViewHandler.EditHandler.ProactiveHandler to theapplet so that when the applet is triggered it can :
- initialise the current proactive command with the init() method ;
- append several Simple TLV as defined in GSM 11.14 [3] to the current proactive command with the appendTLV()methods ;
- ask the Toolkit Framework to send this proactive command to the ME and wait for the reply, with the send()method.
The Toolkit Framework shall handle the transmission of the proactive command to the ME, and the reception of theresponse. The Toolkit Framework will then return in the applet just after the send() method. It shall then provide to theApplet the sim.toolkit.ViewHandler.ProactiveResponseHandler, so that the applet can analyse the response.
GSM 03.19 V1.0.0 (1999-01)12
6.5 Envelope response handlingTo allow an applet to answer to some specific events (e.g. EVENT_CALL_CONTROL_BY_SIM) the ToolkitFramework shall provide the sim.toolkit.ViewHandler.EditHandler.EnvelopeResponseHandler.
The applet can then post a response to some events with the post() or the postAsBERTLV() methods, the applet cancontinue it's processing (e.g. prepare a proactive command) the Toolkit Framework will return the response APDUdefined by the applet (i.e. 9F xx or 9E xx).
7 SIM Toolkit applet
7.1 Applet LoadingThe SIM API card shall be compliant to the Java Card 2.1 VM Architecture Specification [9] and to the Annex B toguarantee interoperability at byte code Level.
The applet loading mechanism, protocol and applet life cycle are defined in GSM xx.yy[]
7.2 Object SharingThe sharing mechanism defined in Java Card 2.1 API Specification [7] and Java Card 2.1 Runtime EnvironmentSpecification [8] shall be used by the applet to share data.
GSM 03.19 V1.0.0 (1999-01)13
Annex A (normative):Java Card SIM API
Document Acrobat
GSM 03.19 V1.0.0 (1999-01)14
Annex B (normative):Java Card SIM API identifiers[To be defined as soon as the byte code is defined for the Java Card API 2.1]
GSM 03.19 V1.0.0 (1999-01)15
Annex C (informative):toolkit applet example
/** * Example Applet */
import sim.toolkit.*;import sim.access.*;import javacard.framework.APDU;import javacard.framework.Util;import javacard.framework.ISOException;import javacard.framework.ISO;
public class MyToolkitApplet extends ToolkitApplet implements ToolkitConstants{
public static final byte MY_INSTRUCTION = (byte)0x46; public static final byte DEVICEID_ME = (byte) 0x82; public static final byte DEVICEID_DISPLAY = (byte) 0x02; public static final byte DCS8 = (byte)0xF4; public static final byte SMS_TPDU = (byte)0x8D; public static final byte SERVER_OPERATION = (byte)15;
private byte[] menuEntry ={(byte)'S',(byte)'e',(byte)'r',(byte)'v',(byte)'i',(byte)'c',(byte)'e',(byte)'1'}; private byte[] menuTitle= {(byte)'M',(byte)'y',(byte)'M',(byte)'e',(byte)'n' ,(byte)'u'}; private byte[] item1 = {(byte)'I',(byte)'T',(byte)'E',(byte)'M',(byte)'1' }; private byte[] item2 = {(byte)'I',(byte)'T',(byte)'E',(byte)'M',(byte)'2' }; private byte[] item3 = {(byte)'I',(byte)'T',(byte)'E',(byte)'M',(byte)'3' }; private byte[] item4 = {(byte)'I',(byte)'T',(byte)'E',(byte)'M',(byte)'4' }; private Object[] ItemList = { item1, item2, item3, item4 }; private byte[] textDText = {(byte)'H',(byte)'e',(byte)'l',(byte)'l',(byte)'o',(byte)' ', (byte)'w',(byte)'o',(byte)'r',(byte)'l',(byte)'d',(byte)'2'}; private byte[] textGInput = {(byte)'Y',(byte)'o',(byte)'u',(byte)'r',(byte)' ',(byte)'n', (byte)'a',(byte)'m',(byte)'e',(byte)'?'};
private Registry reg; private SIMView gsmFile; private byte buffer[] = new byte[10];
/** * Constructor of the applet */ public MyToolkitApplet() {
// get the GSM application reference gsmFile = SIMSystem.getTheSIMView();
// register to the the SIM toolkit framework reg = registerToolkit();
// Define the applet Menu Entry and register to the EVENT_MENU_SELECTION reg.createMenuEntry(menuEntry, (short)0, (short)menuEntry.length, PRO_CMD_DISPLAY_TEXT, false); // register to the EVENT_UNFORMATTED_SMS_PP reg.setEvent(EVENT_UNFORMATTED_SMS_PP); }
/** * Method called by the JCRE at the installation of the applet */ public static void install(byte bArray[], short bOffset, byte bLength) { MyToolkitApplet MyApplet = new MyToolkitApplet (); MyApplet.register(); }
/** * Method called by the SIM Toolkit Framework */ public void processToolkit(byte event) {
// get the handler reference EnvelopeHandler envHdlr = EnvelopeHandler.getTheHandler(); ProactiveHandler proHdlr = ProactiveHandler.getTheHandler(); ProactiveResponseHandler rspHdlr = ProactiveResponseHandler.getTheHandler();
switch(event) {
GSM 03.19 V1.0.0 (1999-01)16
case EVENT_MENU_SELECTION: // Prepare the Select Item proactive command proHdlr.init((byte) PRO_CMD_SELECT_ITEM,(byte)0,DEVICEID_ME); // Append the Menu Title proHdlr.appendTLV((byte) (TAG_ALPHA_IDENTIFIER | MASK_COMPREHENSION_REQUIRED), menuTitle,(short)0,(short)menuTitle.length); // add all the Item for (short i=(short)1;i<(short)5;i++) { proHdlr.appendTLV((byte) (TAG_ITEM | MASK_COMPREHENSION_REQUIRED), (byte)i,(byte[])ItemList[i],(short)0,(short)((byte[])ItemList[i]).length); } // ask the SIM Tooolkit Framework to send the proactive command proHdlr.send();
// SelectItem response handling switch (rspHdlr.getItemIdentifier()) { case 1: case 2: case 3: // DiplayText proHdlr.init((byte) PRO_CMD_DISPLAY_TEXT, (byte)CMD_QUALIFIER, (byte)DEVICEID_DISPLAY); proHdlr.appendTLV((byte)(TAG_TEXT_STRING|MASK_COMPREHENSION_REQUIRED), DCS8 textDText,(short)0, (short)textDText.length); proHdlr.send(); break; case 4: // GetInput followed by a DisplayText of the entered text proHdlr.initGetInput((byte)1,DCS8,textGInput,(byte)0, (short)textGInput.length,(short)1,(short)2); proHdlr.send(); rspHdlr.copyTextString(textDText,(short)0); proHdlr.initDisplayText((byte)0,DCS8,textHigh, (short)1,(short)textHigh.length); proHdlr.send(); break; } break;
case EVENT_UNFORMATTED_SMS_PP: // get the TP-UD field offset short TPUDOffset = envHdlr.getTPUDOffset()+ SERVER_OPERATION;
// start the action requested by the server switch (envHdlr.getValueByte((short)TPUDOffset) ) { case 0x41 : // Update of a gsm file // get the data from the received SMS envHdlr.copyValue((short)TPUDOffset,buffer,(short)0,(short)3); // write these data in the EFpuct gsmFile.select((short)0x7F20); gsmFile.select((short)0x6F41); gsmFile.updateBinary((short)0,buffer,(short)0,(short)3);
break;
case 0x36 : // change the MenuTitle for the SelectItem envHdlr.copyValue((short)TPUDOffset,menuTitle,(short)0,(short)6); break; } break; }
}
/** * Method called by the JCRE, once selected */ public void process(APDU apdu) { switch(apdu.getBuffer()[1]) { // specific APDU for this applet to configure the MenuTitle from SelectItem case (byte)MY_INSTRUCTION: Util.arrayCopy (apdu.getBuffer(),(short) 5, menuTitle,(short) 0 ,(short)6); break; default: ISOException.throwIt(ISO.SW_INS_NOT_SUPPORTED); } }}
GSM 03.19 V1.0.0 (1999-01)17
History
Document history
Date Version Comment
December 1998 0.1.0 Initial draft based on the outcome of JCF SIM API Task Force (December 98).
January 1999 0.1.1 Discussion document during the seventh SMG9 SIM API meeting (January 99)
January 1999 0.2.0 Outcome of the seventh SMG9 SIM API meeting (January 99)
January 1999 0.2.1 Outcome of the SIM API splinter group during SMG9#17 (January 99)
January 1999 0.2.2 Outcome of SMG9#17 (January 99)
January 1999 1.0.0 Submission to SMG #28 for info. (no technical changes compared to V0.2.2)
Rapporteur: Christian Dietrich, ([email protected])
The ETSI committee SMG9 is responsible for developing this specification. An email list has been set up for discussionabout this document. To subscribe to the list, send a message to [email protected] with a single line in the body of themessage: subscribe SMG9_API YourFirstName YourLastName
The latest draft version of this specification may be found at the location:http://docbox.etsi.fr/tech-org/smg/document/smg9/specs/drafts/
orhttp://docbox.etsi.org/tech-org/smg/document/smg9/specs/drafts/
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Table of Contents
Package Index ....................................................................................................................................................1
Class Hierarchy .................................................................................................................................................2
package sim.access ............................................................................................................................................3
Class sim.access.SIMSystem ............................................................................................................................4
Interface sim.access.SIMView .........................................................................................................................6
Class sim.access.SIMViewException .............................................................................................................16
package sim.toolkit .........................................................................................................................................21
Class sim.toolkit.ViewHandler ......................................................................................................................22
Class sim.toolkit.EnvelopeHandler ...............................................................................................................29
Class sim.toolkit.ProactiveResponseHandler ...............................................................................................32
Class sim.toolkit.EditHandler ........................................................................................................................37
Class sim.toolkit.EnvelopeResponseHandler ...............................................................................................42
Class sim.toolkit.ProactiveHandler ...............................................................................................................44
Class sim.toolkit.MEProfile ...........................................................................................................................49
Class sim.toolkit.Registry ...............................................................................................................................52
Class sim.toolkit.ToolkitApplet .....................................................................................................................58
Interface sim.toolkit.ToolkitConstants .........................................................................................................62
Class sim.toolkit.ToolkitException ................................................................................................................74
Index of all Fields and Methods .....................................................................................................................78
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
i
Package Index
Other Packages
• package sim.access• package sim.toolkit
Package Index 1
Class Hierarchy• class java.lang.Object
♦ class javacard.framework.Applet
◊ class sim.toolkit.ToolkitApplet♦ class sim.toolkit.MEProfile♦ class sim.toolkit.Registry♦ class sim.access.SIMSystem♦ interface sim.access.SIMView (extends javacard.framework.Shareable)♦ class java.lang.Throwable (implements java.io.Serializable)
◊ class java.lang.Exception
⋅ class java.lang.RuntimeException
• class javacard.framework.CardRuntimeException
♦ class sim.access.SIMViewException♦ class sim.toolkit.ToolkitException
♦ interface sim.toolkit.ToolkitConstants♦ class sim.toolkit.ViewHandler
◊ class sim.toolkit.EditHandler
⋅ class sim.toolkit.EnvelopeResponseHandler⋅ class sim.toolkit.ProactiveHandler
◊ class sim.toolkit.EnvelopeHandler◊ class sim.toolkit.ProactiveResponseHandler
Class Hierarchy 2
package sim.access
Interface Index
• SIMView
Class Index
• SIMSystem
Exception Index
• SIMViewException
package sim.access 3
Class sim.access.SIMSystemjava.lang.Object | +----sim.access.SIMSystem
public class SIMSystem
extends Object
The SIMSystem class provides a way to get a view of the GSM File system. In any case, the client applet(SIM Tookit or other) will only access to methods of the SIMView interface. No instance of this class isneeded.
Example of use in a standard applet: public class MyApplet extends Applet {
private SIMView theGsmApplet;
private byte[] buffer;
public MyApplet () {
theGsmApplet = SIMSystem.getTheSIMView(); // get a reference to the GSM interface
buffer = new byte[32]; // create the exchange buffer
}
public static void install(APDU apdu) throws ISOException {
MyApplet myAppletRef = new MyApplet(); // create and register the applet
myAppletRef.register();
}
public void getADN(short adnNumber) {
theGsmApplet.select(buffer, (short)0x7F10);
theGsmApplet.select(buffer, (short)0x6F3A);
theGsmApplet.readRecord((short)adnNumber, // record number
(byte)SIMView.MODE_ABSOLUTE, // mode
(short)0, // record offset
(byte[])buffer, // destination buffer
(short)0, // buffer offset
(short)32); // length to read
}
}
Constructor Index
SIMSystem()
Method Index
getTheSIMView()
Return a reference to the GSM interface
Class sim.access.SIMSystem 4
Constructors
SIMSystem public SIMSystem()
Methods
getTheSIMView public static SIMView getTheSIMView()
Return a reference to the GSM interface
Returns:
a reference to a class which implements the GSMView interface
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.access.SIMSystem 5
Interface sim.access.SIMViewpublic interface SIMView
extends Shareable
The SIMView interface is the interface between the GSM application and any applet (SIM Toolkit or other)and offers some methods to communicate with the GSM application without compromising the integrity ofthe existing file system. All the methods are based on the commands of the GSM11.11 specification. Thisinterface shall be implemented by the Toolkit framework. The main idea is to avoid an APDU basedcommunication between SIM Toolkit applets and the GSM application. This interface is not intended for theactivation or interaction with a SIM Toolkit applet.
See Also:
Shareable, SIMViewException
Variable Index
FID_DF_DCS
Constant: File identifier of the DF DCS1800
FID_DF_GSM
Constant: File identifier of the DF GSM
FID_DF_TELECOM
Constant: File identifier of the DF TELECOM
FID_MF
Constant: File identifier of the MF
MODE_ABSOLUTE
Constant: Record access mode 'absolute'
MODE_CURRENT
Constant: Record access mode 'current'
MODE_NEXT
Constant: Record access mode 'next'
MODE_PREVIOUS
Constant: Record access mode 'previous'
Interface sim.access.SIMView 6
SEEK_FROM_BEGINNING_FORWARD
Constant: Seek mode, from the beginning forward
SEEK_FROM_END_BACKWARD
Constant: Seek mode, from the end backward
SEEK_FROM_NEXT_FORWARD
Constant: Seek mode, from the next location forward
SEEK_FROM_PREVIOUS_BACKWARD
Constant: Seek mode, from the previous location backward
Method Index
increase(byte[], short, byte[], short)
INCREASE command as defined in GSM 11.11 standard.This method increases the current cyclic EF record of the calling applet.
invalidate()
INVALIDATE command as defined in GSM 11.11 standard.This method invalidates the currently selected EF of the calling applet.
readBinary(short, byte[], short, short)
READ BINARY command as defined in GSM 11.11 standard.This method reads the data bytes of the current transparent EF of the calling applet.
readRecord(short, byte, short, byte[], short, short)
READ RECORD command as defined in GSM 11.11 standard.This method reads the data bytes of the current linear fixed/cyclic EF of the calling applet.
rehabilitate()
REHABILITATE command as defined in GSM 11.11 standard.This method rehabilitates the currently selected EF of the calling applet.
seek(byte, byte[], short, short)
SEEK command as defined in GSM 11.11 standard.This method seeks a pattern in the current linear fixed EF of the calling applet.
select(byte[], short, short, short)
SELECT command as defined in GSM 11.11 standard.By default, the MF is selected at the beginning of each applet activation (current file = MF).
select(short)
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.access.SIMView 7
SELECT command as defined in GSM 11.11 standard.This SELECT method allows to update the current file without handling the Select ResponseBy default, the MF is selected at the beginning of each applet activation (current file = MF).
status(byte[], short, short)
STATUS command as defined in GSM 11.11 standard.This method returns the FCI (File Control Information) of the current DF (or MF) of thecalling applet.
updateBinary(short, byte[], short, short)
UPDATE BINARY command as defined in GSM 11.11 standard.This method updates the data bytes of the current transparent EF of the calling applet.
updateRecord(short, byte, short, byte[], short, short)
UPDATE RECORD command as defined in GSM 11.11 standard.This method updates the data bytes of the current linear fixed/cyclic EF of the calling applet.
Variables
FID_MF public static final short FID_MF
Constant: File identifier of the MF
FID_DF_TELECOM public static final short FID_DF_TELECOM
Constant: File identifier of the DF TELECOM
FID_DF_GSM public static final short FID_DF_GSM
Constant: File identifier of the DF GSM
FID_DF_DCS public static final short FID_DF_DCS
Constant: File identifier of the DF DCS1800
MODE_NEXT public static final byte MODE_NEXT
Constant: Record access mode 'next'
MODE_PREVIOUS public static final byte MODE_PREVIOUS
Constant: Record access mode 'previous'
MODE_CURRENT public static final byte MODE_CURRENT
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.access.SIMView 8
Constant: Record access mode 'current'
MODE_ABSOLUTE public static final byte MODE_ABSOLUTE
Constant: Record access mode 'absolute'
SEEK_FROM_BEGINNING_FORWARD public static final byte SEEK_FROM_BEGINNING_FORWARD
Constant: Seek mode, from the beginning forward
SEEK_FROM_END_BACKWARD public static final byte SEEK_FROM_END_BACKWARD
Constant: Seek mode, from the end backward
SEEK_FROM_NEXT_FORWARD public static final byte SEEK_FROM_NEXT_FORWARD
Constant: Seek mode, from the next location forward
SEEK_FROM_PREVIOUS_BACKWARD public static final byte SEEK_FROM_PREVIOUS_BACKWARD
Constant: Seek mode, from the previous location backward
Methods
select public abstract short select(byte fci[], short fciOffset, short fciLength, short fid) throws SIMViewException
SELECT command as defined in GSM 11.11 standard.By default, the MF is selected at the beginning of each applet activation (current file = MF).This method selects a file of the common GSM file system. The file search starts at thecurrent DF of the applet according to the file search method described in GSM 11.11specification. The current DF or current EF and the current record pointer of the callingapplet will be changed after successful execution.
Parameters:
fci - is the reference to the target byte array for FCI (File Control Information) of current file,coding according to GSM 11.11. If fci is null, no response is prepared and no exception isthrown. If fci buffer is too small to receive the whole response, no exception is thrown andthe response is truncated. fciOffset is the offset in the fci buffer for the response data fciLength is the length of the required data in the fci byte array fid is the File Identifier of the file to be selected.
Returns:
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.access.SIMView 9
length of the data which have been written in the fci buffer (cannot be greater than fci buffersize)
Throws:SIMViewException
in case of error FILE_NOT_FOUND INTERNAL_ERROR
select public abstract void select(short fid) throws SIMViewException
SELECT command as defined in GSM 11.11 standard.This SELECT method allows to update the current file without handling the Select Response Bydefault, the MF is selected at the beginning of each applet activation (current file = MF). This methodselects a file of the common GSM file system. The file search starts at the current DF of the appletaccording to the file search method described in GSM 11.11 specification. The current DF or currentEF and the current record pointer of the calling applet will be changed after successful execution.
Parameters:
fid - is the File Identifier of the file to be selected.
Throws:SIMViewException
in case of error FILE_NOT_FOUND INTERNAL_ERROR
status public abstract short status(byte fci[], short fciOffset, short fciLength) throws SIMViewException
STATUS command as defined in GSM 11.11 standard.This method returns the FCI (File Control Information) of the current DF (or MF) ofthe calling applet.
Parameters:
fci - is the reference to the target byte array for FCI (File Control Information) ofcurrent DF (or MF), coding according to GSM 11.11. If fci is null, no response isprepared and no exception is thrown. If fci buffer is too small to receive the wholeresponse, no exception is thrown and the response is truncated. fciOffset is the offset in the fci buffer for the response data fciLength is the length of the required data in the fci byte array
Returns:
length of the data which have been written in the fci buffer (cannot be greater thanfci buffer size)
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.access.SIMView 10
Throws:SIMViewException
in case of error INTERNAL_ERROR
readBinary public abstract void readBinary(short fileOffset, byte resp[], short respOffset, short respLength) throws SIMViewException
READ BINARY command as defined in GSM 11.11 standard.This method reads the data bytes of the current transparent EF of the calling applet.
Parameters:
fileOffset - is the offset in the source transparent file. resp is the reference to the response byte array for read data. respOffset is the offset in the response byte array. respLength is the number of bytes to read.
Throws:SIMViewException
in case of error NO_EF_SELECTED FILE_INCONSISTENT AC_NOT_FULFILLED CURRENT_EF_INVALIDATED OUT_OF_FILE_BOUNDARIES OUT_OF_BUFFER_BOUNDARIES INTERNAL_ERROR
updateBinary public abstract void updateBinary(short fileOffset, SIMViewException
UPDATE BINARY command as defined in GSM 11.11 standard.This method updates the data bytes of the current transparent EF of the calling applet.
Parameters:
fileOffset - is the offset in the destination transparent file. data is the reference to the source byte array for data to update. dataOffset is the offset in the source byte array. dataLength is the number of bytes to update.
Throws:SIMViewException
in case of error NO_EF_SELECTED
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.access.SIMView 11
FILE_INCONSISTENT AC_NOT_FULFILLED CURRENT_EF_INVALIDATED OUT_OF_FILE_BOUNDARIES OUT_OF_BUFFER_BOUNDARIES INTERNAL_ERROR
readRecord public abstract void readRecord(short recNumber, byte mode, short recOffset, byte resp[], short respOffset, short respLength) throws SIMViewException
READ RECORD command as defined in GSM 11.11 standard.This method reads the data bytes of the current linear fixed/cyclic EF of the callingapplet. The current record pointer can be changed due to the choosen mode.
Parameters:
recNumber - is the record number. mode is the mode for reading record, according to GSM 11.11. recOffset is the offset in the record for the data to read. resp is the reference to the response byte array for read data. respOffset is the offset in the response byte array. respLength is the number of bytes to read.
Throws:SIMViewException
in case of error NO_EF_SELECTED FILE_INCONSISTENT AC_NOT_FULFILLED CURRENT_EF_INVALIDATED OUT_OF_RECORD_BOUNDARIES OUT_OF_BUFFER_BOUNDARIES RECORD_NUMBER_NOT_AVAILABLE INVALID_MODE INTERNAL_ERROR
updateRecord public abstract void updateRecord(short recNumber, byte mode, short recOffset, byte data[], short dataOffset, short dataLength) throws SIMViewException
UPDATE RECORD command as defined in GSM 11.11 standard.This method updates the data bytes of the current linear fixed/cyclic EF of the calling applet.The current record pointer can be changed due to the choosen mode.
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.access.SIMView 12
Parameters:
recNumber - is the record number. mode is the mode for updating record, according to GSM 11.11. recOffset is the offset in the record for the data to update. data is the reference to the source byte array for data to update. dataOffset is the offset in the source byte array. dataLength is the number of bytes to update.
Throws:SIMViewException
in case of error NO_EF_SELECTED FILE_INCONSISTENT AC_NOT_FULFILLED CURRENT_EF_INVALIDATED OUT_OF_RECORD_BOUNDARIES OUT_OF_BUFFER_BOUNDARIES RECORD_NUMBER_NOT_AVAILABLE INVALID_MODE INTERNAL_ERROR
seek public abstract short seek(byte mode, byte patt[], SIMViewException
SEEK command as defined in GSM 11.11 standard.This method seeks a pattern in the current linear fixed EF of the calling applet.
Parameters:
mode - is the seek mode, according to GSM 11.11 (no type information). patt is the reference to the byte array containing the seek pattern. pattOffset is the offset of the seek pattern in the byte array. pattLength is the length of the seek pattern.
Returns:
record number if pattern found, 0 otherwise
Throws:SIMViewException
in case of error NO_EF_SELECTED PATTERN_NOT_FOUND FILE_INCONSISTENT AC_NOT_FULFILLED CURRENT_EF_INVALIDATED INVALID_MODE PATTERN_SIZE_INCONSISTENT INTERNAL_ERROR
increase
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.access.SIMView 13
public abstract short increase(byte incr[], short incrOffset, byte resp[], short respOffset) throws SIMViewException
INCREASE command as defined in GSM 11.11 standard.This method increases the current cyclic EF record of the calling applet. Theresponse buffer will only contain the value of the increased record.
Parameters:
incr - is the reference to the source byte array, containing the value to add, on 3bytes. incrOffset is the offset in the source byte array. resp is the reference to the response byte array for new record value. If resp is null,no response is prepared and no exception is thrown. If resp buffer is smaller than therecord size, an "OUT_OF_BUFFER_BOUNDARIES" exception is thrown. If respbuffer is bigger than the record size, the resp buffer is filled with the record valueand left justified respOffset is the offset in the response byte array.
Returns:
length of the valid data in the resp buffer (cannot be greater than the record size)
Throws:SIMViewException
in case of error NO_EF_SELECTED FILE_INCONSISTENT AC_NOT_FULFILLED CURRENT_EF_INVALIDATED MAX_VALUE_REACHED OUT_OF_BUFFER_BOUNDARIES INTERNAL_ERROR
invalidate public abstract void invalidate() throws SIMViewException
INVALIDATE command as defined in GSM 11.11 standard.This method invalidates the currently selected EF of the calling applet.
Throws:SIMViewException
in case of error NO_EF_SELECTED AC_NOT_FULFILLED INVALIDATION_STATUS_CONTRADICTION INTERNAL_ERROR
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.access.SIMView 14
rehabilitate public abstract void rehabilitate() throws SIMViewException
REHABILITATE command as defined in GSM 11.11 standard.This method rehabilitates the currently selected EF of the calling applet.
Throws:SIMViewException
in case of error NO_EF_SELECTED AC_NOT_FULFILLED INVALIDATION_STATUS_CONTRADICTION INTERNAL_ERROR
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.access.SIMView 15
Class sim.access.SIMViewExceptionjava.lang.Object | +----java.lang.Throwable | +----java.lang.Exception | +----java.lang.RuntimeException | +----javacard.framework.CardRuntimeException | +----sim.access.SIMViewException
public class SIMViewException
extends CardRuntimeException
The SIMViewException class encapsulates specific exceptions which can be generated by the methods ofthe SIMView interface in case of error.
Table SIMViewException
reason Description
NO_EF_SELECTED No EF selected before calling the method
FILE_INCONSISTENT File inconsistent with the method
AC_NOT_FULFILLED Access condition level not fulfilled
FILE_NOT_FOUND File not found
INTERNAL_ERROR Internal error
CURRENT_EF_INVALIDATED Current EF invalidated
INVALIDATION_STATUS_CONTRADICTION Method in contradiction with the invalidation status
OUT_OF_FILE_BOUNDARIES Out of the transparent file boundaries
OUT_OF_RECORD_BOUNDARIES Out of the record boundaries
OUT_OF_BUFFER_BOUNDARIES Out of the buffer boundaries (response or data)
RECORD_NUMBER_NOT_AVAILABLE Record number not available
INVALID_MODE Invalid mode for seek command or record access
PATTERN_NOT_FOUND Pattern not found for seek command
PATTERN_SIZE_INCONSISTENT Pattern size greater than record size
MAX_VALUE_REACHED Max value reached for increase command
See Also:
SIMView
Class sim.access.SIMViewException 16
Variable Index
AC_NOT_FULFILLED
Constant: Access condition level not fulfilled
CURRENT_EF_INVALIDATED
Constant: Current EF invalidated
FILE_INCONSISTENT
Constant: File inconsistent with the method
FILE_NOT_FOUND
Constant: File not found
INTERNAL_ERROR
Constant: Internal error
INVALID_MODE
Constant: Invalid mode for seek command or record access
INVALIDATION_STATUS_CONTRADICTION
Constant: Method in contradiction with the invalidation status
MAX_VALUE_REACHED
Constant: Max value reached for increase command
NO_EF_SELECTED
Constant: No EF selected before calling the method
OUT_OF_BUFFER_BOUNDARIES
Constant: Out of the buffer boundaries (response or data)
OUT_OF_FILE_BOUNDARIES
Constant: Out of the transparent file boundaries
OUT_OF_RECORD_BOUNDARIES
Constant: Out of the record boundaries
PATTERN_NOT_FOUND
Constant: Pattern not found for seek command
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.access.SIMViewException 17
PATTERN_SIZE_INCONSISTENT
Constant: Pattern size greater than record size
RECORD_NUMBER_NOT_AVAILABLE
Constant: Record number not available
Constructor Index
SIMViewException(short)
Constructs a SIMViewException object.
Method Index
throwIt(short)
Throws the JCRE instance of SIMViewException with the specified reason.
Variables
NO_EF_SELECTED public static final short NO_EF_SELECTED
Constant: No EF selected before calling the method
FILE_INCONSISTENT public static final short FILE_INCONSISTENT
Constant: File inconsistent with the method
AC_NOT_FULFILLED public static final short AC_NOT_FULFILLED
Constant: Access condition level not fulfilled
FILE_NOT_FOUND public static final short FILE_NOT_FOUND
Constant: File not found
INTERNAL_ERROR public static final short INTERNAL_ERROR
Constant: Internal error
CURRENT_EF_INVALIDATED public static final short CURRENT_EF_INVALIDATED
Constant: Current EF invalidated
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.access.SIMViewException 18
INVALIDATION_STATUS_CONTRADICTION public static final short INVALIDATION_STATUS_CONTRADICTION
Constant: Method in contradiction with the invalidation status
OUT_OF_FILE_BOUNDARIES public static final short OUT_OF_FILE_BOUNDARIES
Constant: Out of the transparent file boundaries
OUT_OF_RECORD_BOUNDARIES public static final short OUT_OF_RECORD_BOUNDARIES
Constant: Out of the record boundaries
OUT_OF_BUFFER_BOUNDARIES public static final short OUT_OF_BUFFER_BOUNDARIES
Constant: Out of the buffer boundaries (response or data)
RECORD_NUMBER_NOT_AVAILABLE public static final short RECORD_NUMBER_NOT_AVAILABLE
Constant: Record number not available
INVALID_MODE public static final short INVALID_MODE
Constant: Invalid mode for seek command or record access
PATTERN_NOT_FOUND public static final short PATTERN_NOT_FOUND
Constant: Pattern not found for seek command
PATTERN_SIZE_INCONSISTENT public static final short PATTERN_SIZE_INCONSISTENT
Constant: Pattern size greater than record size
MAX_VALUE_REACHED public static final short MAX_VALUE_REACHED
Constant: Max value reached for increase command
Constructors
SIMViewException public SIMViewException(short reason)
Constructs a SIMViewException object. To conserve on resources use throwIt() to re-usethe JCRE instance of this class.
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.access.SIMViewException 19
Parameters:
reason - is the reason for the exception
Methods throwIt public static void throwIt(short reason) throws SIMViewException
Throws the JCRE instance of SIMViewException with the specified reason.
Parameters:
reason - is the reason for the exception
Throws:SIMViewException
always
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.access.SIMViewException 20
package sim.toolkit
Interface Index
• ToolkitConstants
Class Index
• EditHandler• EnvelopeHandler• EnvelopeResponseHandler• MEProfile• ProactiveHandler• ProactiveResponseHandler• Registry• ToolkitApplet• ViewHandler
Exception Index
• ToolkitException
package sim.toolkit 21
Class sim.toolkit.ViewHandlerjava.lang.Object | +----sim.toolkit.ViewHandler
public class ViewHandler
extends Object
The ViewHandler class offers basic services and contains basic methods to handle TLV list, such as in aTerminal Response data field or in a BER-TLV element (Envelope data field or Proactive command).
See Also:
ToolkitException
Constructor Index
ViewHandler(byte[], short, short)
Build a new ViewHandler object.
Method Index
compareValue(short, byte[], short, short)
Compare the last found TLV element with a buffer.
copyValue(short, byte[], short, short)
Copy a part of the last TLV element which has been found, into a destination buffer.
findAndCompareValue(byte, byte, short, byte[], short, short)
Look for the first occurence of a TLV element and compare its value with a buffer.
findAndCompareValue(byte, byte[], short)
Look for the first occurence of a TLV element and compare its value with a buffer.
findAndCopyValue(byte, byte, short, byte[], short, short)
Look for the first occurence of a TLV element and copy its value into a destination buffer.
findAndCopyValue(byte, byte[], short)
Look for the first occurence of a TLV element and copy its value into a destination buffer.
Class sim.toolkit.ViewHandler 22
findTLV (byte, byte)
Look for a TLV element in the TLV structure (handler buffer).
getValueByte(short)
Get a byte from the last TLV element which has been found in the buffer.
getValueLength()
Get the length of the value field for the last TLV element which has been found in the buffer.
Constructors
ViewHandler public ViewHandler(byte buffer[], short offset, short length)
Build a new ViewHandler object.
Parameters:
buffer - a reference to the TLV buffer
offset - the position in the TLV buffer
length - the length of the TLV buffer
Methods findTLV public byte findTLV(byte tag, byte occurrence) throwsToolkitException
Look for a TLV element in the TLV structure (handler buffer). This search method is ComprehensionRequired flag independent.
Parameters:
tag - the tag of the TLV element to search
occurrence - the occurrence number of the TLV element (1 for the first, 2 for the second...)
Returns:
NOT_FOUND if the required occurrence of the TLV element does not exist FOUND_CR_SET if the required occurence exists and Comprehension Required flag is set FOUND_CR_NOT_SET if the required occurence exists and Comprehension Required flag is not set
Throws:ToolkitException
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ViewHandler 23
HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for the system-definedsingleton classes.
getValueLength public short getValueLength() throws ToolkitException
Get the length of the value field for the last TLV element which has been found inthe buffer.
Returns:
length of the value field
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for thesystem-defined singleton classes. UNAVAILABLE_ELEMENT in case of unavailable TLV element
getValueByte public byte getValueByte(short valueOffset) throws ToolkitException
Get a byte from the last TLV element which has been found in the buffer.
Parameters:
valueOffset - the offset of the byte to return in the TLV element
Returns:
element value (1 byte)
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for thesystem-defined singleton classes. UNAVAILABLE_ELEMENT in case of unavailable TLV element
copyValue public short copyValue(short valueOffset, byte dstBuffer[], ToolkitException
Copy a part of the last TLV element which has been found, into a destination buffer.
Parameters:
valueOffset - the offset of the first byte in the source TLV element
dstBuffer - a reference to the destination buffer
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ViewHandler 24
dstOffset - the position in the destination buffer
dstLength - the data length to be copied
Returns:
dstOffset+dstLength
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for the system-definedsingleton classes. UNAVAILABLE_ELEMENT in case of unavailable TLV element
compareValue public byte compareValue(short valueOffset, byte compareBuffer[], short compareOffset, short compareLength) throws ToolkitException
Compare the last found TLV element with a buffer.
Parameters:
valueOffset - the offset of the first byte to compare in the TLV element
compareBuffer - a reference to the comparison buffer
compareOffset - the position in the comparison buffer
compareLength - the length to be compared
Returns:
the result of the comparison as follows:0 if identical -1 if the first miscomparing byte in TLV element array is less than that in destinationarray, 1 if the first miscomparing byte in TLV element array is greater than that indestination array.
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for thesystem-defined singleton classes. UNAVAILABLE_ELEMENT in case of unavailable TLV element
findAndCopyValue public short findAndCopyValue(byte tag, byte dstBuffer[], short dstOffset) throws ToolkitException
Look for the first occurence of a TLV element and copy its value into a destination buffer. If
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ViewHandler 25
no TLV element is found, the return value equals dstOffset . This search method isComprehension Required flag independent. To find another occurence or to copy only a partof the TLV, the methods findTLV() and copyValue() shall be used.
Parameters:
tag - the tag of the TLV element to search
dstBuffer - a reference to the destination buffer
dstOffset - the position in the destination buffer
Returns:
dstOffset + length of the copied value
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for thesystem-defined singleton classes. UNAVAILABLE_ELEMENT in case of unavailable TLV element
findAndCopyValue public short findAndCopyValue(byte tag, byte occurenc eToolkitException
Look for the first occurence of a TLV element and copy its value into a destination buffer. If no TLVelement is found, the return value equals dstOffset . This search method is Comprehension Requiredflag independent. To find another occurence or to copy only a part of the TLV, the methodsfindTLV() and copyValue() shall be used.
Parameters:
tag - the tag of the TLV element to search
occurrence - the occurrence number of the TLV element (1 for the first, 2 for the second...)
valueOffset - the offset of the first byte in the source TLV element
dstBuffer - a reference to the destination buffer
dstOffset - the position in the destination buffer
dstLength - the data length to be copied
Returns:
dstOffset + dstLength
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for the system-defined
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ViewHandler 26
singleton classes. UNAVAILABLE_ELEMENT in case of unavailable TLV element
findAndCompareValue public byte findAndCompareValue(byte tag, byte dstBuffer[], short dstOffset) throws ToolkitException
Look for the first occurence of a TLV element and compare its value with a buffer. Ifno TLV element is found, the return value equals -1. This search method isComprehension Required flag independent. To find another occurence or to compareonly a part of the TLV, the methods findTLV() and compareValue() shall be used.
Parameters:
tag - the tag of the TLV element to search
dstBuffer - a reference to the comparison buffer
dstOffset - the position in the comparison buffer
Returns:
the result of the comparison as follows:0 if identical -1 if the first miscomparing byte in TLV element array is less than that in destinationarray, 1 if the first miscomparing byte in TLV element array is greater than that indestination array.
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for thesystem-defined singleton classes. UNAVAILABLE_ELEMENT in case of unavailable TLV element
findAndCompareValue public byte findAndCompareValue(byte tag, byte occurence, short valueOffset, byte compareBuffer[], short compareOffset, short compareLength) throws ToolkitException
Look for the first occurence of a TLV element and compare its value with a buffer. If noTLV element is found, the return value equals -1. This search method is ComprehensionRequired flag independent. To find another occurence or to compare only a part of the TLV,the methods findTLV() and compareValue() shall be used.
Parameters:
tag - the tag of the TLV element to search
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ViewHandler 27
occurrence - the occurrence number of the TLV element (1 for the first, 2 for the second...)
valueOffset - the offset of the first byte in the source TLV element
compareBuffer - a reference to the comparison buffer
compareOffset - the position in the comparison buffer
compareLength - the length to be compared
Returns:
the result of the comparison as follows:0 if identical -1 if the first miscomparing byte in TLV element array is less than that in destination array, 1 if the first miscomparing byte in TLV element array is greater than that in destination array.
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for thesystem-defined singleton classes. UNAVAILABLE_ELEMENT in case of unavailable TLV element
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ViewHandler 28
Class sim.toolkit.EnvelopeHandlerjava.lang.Object | +---- sim.toolkit.ViewHandler | +----sim.toolkit.EnvelopeHandler
public final class EnvelopeHandler
extends ViewHandler
The EnvelopeHandler class contains basic methods to handle the Envelope data field. This class will be usedby the Toolkit applet in order to have access to the current Envelope information. No constructor is availablefor the Toolkit applet. The EnvelopeHandler class is a singleton class and the only way to get aEnvelopeHandler reference is through the getTheHandler() static method.
Example of use in a standard Toolkit applet: private static final byte MY_TAG = (byte)0x54; // constant
private EnvelopeHandler theEnv;
private byte[] data; // reference declaration
data = new byte[32]; // build object
void processToolkit(byte event) throws ToolkitException {
// get the EnvelopeHandler system instance
theEnv = EnvelopeHandler.getTheHandler();
if (theEnv.findTLV(MY_TAG, (byte)1) != NOT_FOUND) { // look for MY_TAG element
if (theEnv.getValueByte((short)0) == (byte)1) { // check first element byte
// copy element part into data buffer
theEnv.copyValue((short)1,
data,
(short)0,
(short)(theEnv.getValueLength() - 1));
}
}
}
See Also:
ViewHandler, EnvelopeResponseHandler, ToolkitException
Method Index
getEnvelopeTag()
Return the Envelope BER-TLV tag.
getItemIdentifier()
Return the item identifier byte value from the first Item Identifier TLV element in the currentEnvelope data field.
getTheHandler()
Class sim.toolkit.EnvelopeHandler 29
Return the single system instance of the EnvelopeHandler class.
getTPOAOffset()
Look for the TP-OA field in the first TPDU TLV element in the Envelope data field.
getTPUDOffset()
Look for the TP-UD field in the first TPDU TLV element in the Envelope data field.
Methods
getTheHandler public static EnvelopeHandler getTheHandler()
Return the single system instance of the EnvelopeHandler class. Several calls to this methodwill always return the same object reference.
Returns:
reference of the system instance
getEnvelopeTag public byte getEnvelopeTag() throws ToolkitException
Return the Envelope BER-TLV tag.
Returns:
Envelope tag
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy.
getTPOAOffset public short getTPOAOffset() throws ToolkitException
Look for the TP-OA field in the first TPDU TLV element in the Envelope data field.Should be used with Envelope SMS-PP Data Download.
Returns:
TPOA offset in the first TPDU TLV element if TPOA exists. The TPOA length canbe recovered by using the getValueByte method in Handler class.
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy.
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.EnvelopeHandler 30
UNAVAILABLE_ELEMENT in case of unavailable TPDU TLV element or if theTPOA field does not exist
getTPUDOffset public short getTPUDOffset() throws ToolkitException
Look for the TP-UD field in the first TPDU TLV element in the Envelope data field. Shouldbe used with Envelope SMS-PP Data Download.
Returns:
TPUD offset in the first TPDU TLV element if TPUD exists. The TPUD length can berecovered by using the getValueByte method in Handler class.
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy. UNAVAILABLE_ELEMENT in case of unavailable TPDU TLV element or if the TPUDfield does not exist
getItemIdentifier public byte getItemIdentifier() throws ToolkitException
Return the item identifier byte value from the first Item Identifier TLV element in the currentEnvelope data field.
Returns:
item identifier
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy. UNAVAILABLE_ELEMENT in case of unavailable TLV element
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.EnvelopeHandler 31
Class sim.toolkit.ProactiveResponseHandlerjava.lang.Object | +---- sim.toolkit.ViewHandler | +----sim.toolkit.ProactiveResponseHandler
public final class ProactiveResponseHandler
extends ViewHandler
The ProactiveResponseHandler class contains basic methods to handle the Terminal Response data field.This class will be used by the Toolkit applet to get the response to the Proactive commands. No constructor isavailable for the Toolkit applet. The ProactiveResponseHandler class is a singleton class and the only way toget a ProactiveResponseHandler reference is through the getTheHandler() static method.
Example of use in a standard Toolkit applet: private byte[] data;
data = new byte[32]; // build a buffer
ProactiveResponseHandler ProRespHdlr; // get the system instance
ProRespHdlr = ProactiveResponseHandler.getTheHandler();
// get General Result
byte result = ProRespHdlr.getGeneralResult();
respHdlr.findTLV(TAG_DEVICE_IDENTITIES, 1); // look for Device Identities
byte sourceDev = ProRespHdlr.getValueByte((short)0); // read Device Identities
byte destinDev = ProRespHdlr.getValueByte((short)1);
// look for Text String element
if (ProRespHdlr.findTLV(TAG_TEXT_STRING, (byte)1) == FOUND_CR_SET) {
if ((short len = ProRespHdlr.getValueLength()) > 1) {
// not empty string: to be copied
ProRespHdlr.copyValue((short)1, data, (short)0, (short)(len - 1));
}
}
See Also:
ViewHandler, ProactiveHandler, ToolkitException
Method Index
copyAdditionalInformation(byte[], short, short)
Copy a part of the additional information field from the first Result TLV element of thecurrent response data field.
copyTextString(byte[], short)
Copy the text string value from the first Text String TLV element of the current responsedata field.
getAdditionalInformationLength()
Class sim.toolkit.ProactiveResponseHandler 32
Return the length of the additional information field from the first Result TLV element of thecurrent response data field.
getDurationInterval()
Return the duration interval value from the first Duration TLV element of the currentresponse data field.
getDurationUnit()
Return the duration unit byte from the first Duration TLV element of the current responsedata field.
getGeneralResult()
Return the general result byte of the Proactive command.
getItemIdentifier()
Return the item identifier byte value from the first Item Identifier TLV element of the currentresponse data field.
getTextStringCodingScheme()
Return the data coding scheme byte from the first Text String TLV element of the currentresponse data field.
getTextStringLength()
Return the text string length value from the first Text String TLV element of the currentresponse data field.
getTheHandler()
Return the single system instance of the ProactiveResponseHandler class.
Methods
getTheHandler public static ProactiveResponseHandler getTheHandler()
Return the single system instance of the ProactiveResponseHandler class. Several calls tothis method will always return the same object reference.
Returns:
reference of the system instance
getGeneralResult public byte getGeneralResult() throws ToolkitException
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ProactiveResponseHandler 33
Return the general result byte of the Proactive command.
Returns:
general result of the command (first byte of Result TLV in Terminal Response)
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the Proactive response buffer is not valid UNAVAILABLE_ELEMENT in case of unavailable TLV element
getAdditionalInformationLength public short getAdditionalInformationLength() throws ToolkitException
Return the length of the additional information field from the first Result TLVelement of the current response data field.
Returns:
additional information length
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the Proactive response buffer is not valid UNAVAILABLE_ELEMENT in case of unavailable TLV element
copyAdditionalInformation public short copyAdditionalInformation(byte dstBuffer[], short dstOffset, short dstLength) throws ToolkitException
Copy a part of the additional information field from the first Result TLV element of thecurrent response data field.
Parameters:
dstBuffer - a reference to the destination buffer
dstOffset - the position in the destination buffer
dstLength - the data length to be copied
Returns:
dstOffset+dstLength
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the Proactive response buffer is not valid UNAVAILABLE_ELEMENT in case of unavailable TLV element
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ProactiveResponseHandler 34
getItemIdentifier public byte getItemIdentifier() throws ToolkitException
Return the item identifier byte value from the first Item Identifier TLV element of the currentresponse data field.
Returns:
item identifier
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the Proactive response buffer is not valid UNAVAILABLE_ELEMENT in case of unavailable TLV element
getDurationInterval public short getDurationInterval() throws ToolkitException
Return the duration interval value from the first Duration TLV element of the currentresponse data field.
Returns:
duration interval (between 1 and 255)
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the Proactive response buffer is not valid UNAVAILABLE_ELEMENT in case of unavailable TLV element
getDurationUnit public byte getDurationUnit() throws ToolkitException
Return the duration unit byte from the first Duration TLV element of the current responsedata field.
Returns:
duration unit (0, 1 or 2)
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the Proactive response buffer is not valid UNAVAILABLE_ELEMENT in case of unavailable TLV element
getTextStringLength public short getTextStringLength() throws ToolkitException
Return the text string length value from the first Text String TLV element of the current response
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ProactiveResponseHandler 35
data field. The Data Coding Scheme byte is not taken into account.
Returns:
text string length
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the Proactive response buffer is not valid UNAVAILABLE_ELEMENT in case of unavailable TLV element
getTextStringCodingScheme public byte getTextStringCodingScheme() throws ToolkitException
Return the data coding scheme byte from the first Text String TLV element of thecurrent response data field.
Returns:
text string coding scheme
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the Proactive response buffer is not valid UNAVAILABLE_ELEMENT in case of unavailable TLV element
copyTextString public short copyTextString(byte dstBuffer[], short dstOffset) throws ToolkitException
Copy the text string value from the first Text String TLV element of the current responsedata field. The Data Coding Scheme byte is not copied.
Parameters:
dstBuffer - a reference to the destination buffer
dstOffset - the position in the destination buffer
Returns:
dstOffset + length of the copied value
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the Proactive response buffer is not valid UNAVAILABLE_ELEMENT in case of unavailable TLV element
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ProactiveResponseHandler 36
Class sim.toolkit.EditHandlerjava.lang.Object | +---- sim.toolkit.ViewHandler | +----sim.toolkit.EditHandler
public class EditHandler
extends ViewHandler
This class is the basic class for the construction of a list of simple TLV elements
See Also:
ViewHandler, ToolkitException
Constructor Index
EditHandler(byte[], short, short)
Build a new EditHandler object.
Method Index
appendArray(byte[], short, short)
Append a buffer into the EditHandler buffer.
appendTLV(byte, byte)
Append a TLV element to the current Proactive command (1-byte element)(useful to add single byte elements as Item Identifier or Tone).
appendTLV(byte, byte, byte)
Append a TLV element to the current Proactive command (2-byte element)(useful to add double byte elements as Device Identities, Duration or Response Length).
appendTLV(byte, byte, byte[], short, short)
Append a TLV element to the current Proactive command (byte array format)
appendTLV(byte, byte[], short, short)
Append a TLV element to the current Proactive command (byte array format)
clear()
Class sim.toolkit.EditHandler 37
Clear an EditHandler buffer.
getLength()
Return the length of the current SIMPLE TLV list.
Constructors
EditHandler public EditHandler(byte buffer[], short offset, short length)
Build a new EditHandler object.
Methods
clear public void clear() throws ToolkitException
Clear an EditHandler buffer.
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for thesystem-defined singleton classes.
appendArray public void appendArray(byte buffer[], short offset, ToolkitException
Append a buffer into the EditHandler buffer.
Parameters:
buffer - the buffer containing data for copy
offset - the offset in the buffer
length - the value length of the buffer
Throws:ToolkitException
BUFFER_OVERFLOW in case of too much data HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for the system-definedsingleton classes.
appendTLV public void appendTLV(byte tag,
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.EditHandler 38
byte value[], short offset, short length) throws ToolkitException
Append a TLV element to the current Proactive command (byte array format)
Parameters:
tag - the tag of the TLV to append, including the Comprehension Required flag
value - the buffer containing the TLV value
offset - the offset of the TLV value in the buffer
length - the value length of the TLV to append
Throws:ToolkitException
BUFFER_OVERFLOW in case of too much data HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for thesystem-defined singleton classes.
appendTLV public void appendTLV(byte tag, byte value) throws ToolkitException
Append a TLV element to the current Proactive command (1-byte element)(useful to add single byte elements as Item Identifier or Tone).
Parameters:
tag - the tag of the TLV to append, including the Comprehension Required flag
value - the TLV value on 1 byte
Throws:ToolkitException
BUFFER_OVERFLOW in case of too much data HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for thesystem-defined singleton classes.
appendTLV public void appendTLV(byte tag, byte value1, ToolkitException
Append a TLV element to the current Proactive command (2-byte element)(useful to add double byte elements as Device Identities, Duration or Response Length).
Parameters:
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.EditHandler 39
tag - the tag of the TLV to append, including the Comprehension Required flag
value1 - the 1st byte (msb) of the TLV value
value2 - the 2nd byte (lsb) of the TLV value
Throws:ToolkitException
BUFFER_OVERFLOW in case of too much data HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for the system-definedsingleton classes.
appendTLV public void appendTLV(byte tag, byte firstbyte, byte value[], short offset, short length) throws ToolkitException
Append a TLV element to the current Proactive command (byte array format)
Parameters:
tag - the tag of the TLV to append, including the Comprehension Required flag
firstbyte - the first byte in the value field
value - the buffer containing the rest of the TLV field
offset - the offset of the rest of the TLV field in the buffer
length - the value length of the TLV to append
Throws:ToolkitException
BUFFER_OVERFLOW in case of too much data HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for thesystem-defined singleton classes.
getLength public short getLength() throws ToolkitException
Return the length of the current SIMPLE TLV list.
Returns:
length in bytes
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for the
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.EditHandler 40
system-defined singleton classes.
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.EditHandler 41
Class sim.toolkit.EnvelopeResponseHandlerjava.lang.Object | +---- sim.toolkit.ViewHandler | +---- sim.toolkit.EditHandler | +----sim.toolkit.EnvelopeResponseHandler
public final class EnvelopeResponseHandler
extends EditHandler
The EnvelopeResponseHandler class contains basic methods to handle the Envelope response data field.This class will be used by the Toolkit applet in order to edit the response to current Envelope command. Noconstructor is available for the Toolkit applet. The EnvelopeResponseHandler class is a singleton class andthe only way to get a EnvelopeResponseHandler reference is through the getTheHandler() static method.
See Also:
ViewHandler, EditHandler, EnvelopeHandler, ToolkitException
Method Index
getTheHandler()
Return the single system instance of the EnvelopeResponseHandler class.
post(byte)
Post the Envelope response.
postAsBERTLV(byte, byte)
Post the Envelope response in a BER TLV structure.
Methods
getTheHandler public static EnvelopeResponseHandler getTheHandler()
Return the single system instance of the EnvelopeResponseHandler class. Several calls tothis method will always return the same object reference.
Returns:
Class sim.toolkit.EnvelopeResponseHandler 42
reference of the system instance
post public void post(byte statusType)
Post the Envelope response. Should be used with Envelope SMS-PP Data Download.
Parameters:
statusType - the status to be sent to the ME (9Fxx or 9Exx)
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy.
postAsBERTLV public void postAsBERTLV(byte statusType, byte tag)
Post the Envelope response in a BER TLV structure. Should be used with EnvelopeCall Control by SIM or MO Short Message Control by SIM. The tag value is to beused to set the Result for Call Control and MO Short Message Control by the SIM.
Parameters:
statusType - the status to be sent to the ME (9Fxx or 9Exx)
tag - the BER Tag to be used at the beginning of the SIMPLE_TLV list.
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the handler is busy.
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.EnvelopeResponseHandler 43
Class sim.toolkit.ProactiveHandlerjava.lang.Object | +---- sim.toolkit.ViewHandler | +---- sim.toolkit.EditHandler | +----sim.toolkit.ProactiveHandler
public final class ProactiveHandler
extends EditHandler
This class is the basic class for the definition of Proactive commands . Low level methods, as init() ,appendTLV() ... will be used to handle generic Proactive commands (standard or future definitions...). Othermethods are dedicated to the Release 97 of the GSM 11.14 (version 6.2.0). The ProactiveHandler class is asingleton class, therefore only one instance of this class may be created by the system: all the Toolkit applets,which need to send Proactive commands, shall call the getTheHandler() static method to get the referenceof this system instance.
Example of use in a standard Toolkit applet: // constants definition
private static final byte MY_COMMAND = (byte)0x33;
private static final byte DEVICE_ME = (byte)0x82;
private static final byte MY_TAG = (byte)0x45;
private static final byte DCS8 = (byte)0x04;
ProactiveHandler proHdlr; // get the system instance
proHdlr = ProactiveHandler.getTheHandler();
// build and send a new Proactive command
proHdlr.init(MY_COMMAND, (byte)0, DEVICE_ME);
proHdlr.appendTLV((byte)(MY_TAG | MASK_COMPREHENSION_REQUIRED),
(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, DCS8, text, (short)0, (short)3);
result = proHdlr.send();
See Also:
ViewHandler, EditHandler, ToolkitException
Method Index
getTheHandler()
Return the single system instance of the ProactiveHandler class.
Class sim.toolkit.ProactiveHandler 44
init (byte, byte, byte)
Initialize the next Proactive command with Command Details and Device Identities TLV.The source device is always the SIM card.
initDisplayText(byte, byte, byte[], short, short)
Build a Display Text Proactive command without sending the command.
initGetInkey(byte, byte, byte[], short, short)
Build a Get Inkey Proactive command without sending the command.
initGetInput(byte, byte, byte[], short, short, short, short)
Initialize the building of a Get Input Proactive command.
initPollInterval (byte, short)
Build a Poll Interval Proactive command without sending the command.
send()
Send the current Proactive command.
Methods
getTheHandler public static ProactiveHandler getTheHandler()
Return the single system instance of the ProactiveHandler class. Several calls to this methodwill always return the same object reference.
Returns:
reference of the system instance
init public void init(byte type, byte qualifier, byt eToolkitException
Initialize 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. TheComprehension Required flags are set.
Parameters:
type - the command type
qualifier - the command qualifier
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ProactiveHandler 45
dstDevice - the destination device
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the Proactive buffer is busy
send public byte send() throws ToolkitException
Send the current Proactive command.
Returns:
general result of the command (first byte of Result TLV in Terminal Response)
Throws:ToolkitException
HANDLER_NOT_AVAILABLE if the Proactive buffer is busy PROACTIVE_NOT_SUPPORTED if the ME does not support proactive SIMs
initDisplayText public byte initDisplayText(byte qualifier, byte dcs, byte buffer[], short offset, short length) throws ToolkitException
Build a Display Text Proactive command without sending the command. TheComprehension Required flags are all set to 1.
Parameters:
qualifier - Display Text command qualifier
dcs - data coding scheme
buffer - reference to the text string source buffer
offset - offset of the text string in the source buffer
length - length of the text string in the source buffer
Returns:
general result of the command (first byte of Result TLV in Terminal Response)
Throws:ToolkitException
PROACTIVE_OVERFLOW in case of too large Proactive command HANDLER_NOT_AVAILABLE if the Proactive buffer is busy
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ProactiveHandler 46
initGetInkey public byte initGetInkey(byte qualifier, byte dcs, ToolkitException
Build a Get Inkey Proactive command without sending the command. The Comprehension Requiredflags are all set to 1.
Parameters:
qualifier - Get Inkey command qualifier
dcs - data coding scheme
buffer - reference to the displayed text string source buffer
offset - offset of the displayed text string in the source buffer
length - length of the displayed text string in the source buffer
Returns:
general result of the command (first byte of Result TLV in Terminal Response)
Throws:ToolkitException
PROACTIVE_OVERFLOW in case of too large Proactive command HANDLER_NOT_AVAILABLE if the Proactive buffer is busy
initPollInterval public byte initPollInterval(byte unit, short interval) throws ToolkitException
Build a Poll Interval Proactive command without sending the command. TheComprehension Required flags are all set to 1.
Parameters:
unit - time unit
interval - time interval
Returns:
general result of the command (first byte of Result TLV in Terminal Response)
Throws:ToolkitException
PROACTIVE_OVERFLOW in case of too large Proactive command HANDLER_NOT_AVAILABLE if the Proactive buffer is busy
initGetInput
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ProactiveHandler 47
public void initGetInput(byte qualifier, byte dcs, byte buffer[], short offset, short length, short minRespLength, short maxRespLength) throws ToolkitException
Initialize the building of a Get Input Proactive command. The Comprehension Required flagsare all set to 1. The following command parameters (i.e. TLVs) may be appended to the command beforesending it: Default Text
Parameters:
qualifier - Get Input command qualifier
dcs - data coding scheme
buffer - reference to the displayed text string source buffer
offset - offset of the displayed text string in the source buffer
length - length of the displayed text string in the source buffer
minRespLength - minimal length of the response text string
maxRespLength - maximal length of the response text string
Throws:ToolkitException
PROACTIVE_OVERFLOW in case of too large Proactive command HANDLER_NOT_AVAILABLE if the Proactive buffer is busy
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ProactiveHandler 48
Class sim.toolkit.MEProfilejava.lang.Object | +----sim.toolkit.MEProfile
public final class MEProfile
extends Object
The MEProfile class contains methods to question the handset profile, regarding the SIM ApplicationToolkit and supposing that this profile has been set by the Terminal Profile APDU command. The followingtable gives the index value according to the facility to check. Only Release 97 facilities of the GSM 11.14 arelisted (version 6.2.0). This class contains only static methods, no instance of this class is necessary.
Facility Index
Profile download 0
SMS-PP data download 1
Cell Broadcast data download 2
Menu selection 3
New status word for SIM data download error 4
Command result 8
Call Control by SIM 9
Cell identity included in Call Control by SIM 10
MO short message control by SIM 11
Handling of the alpha identifier 12
UCS2 Entry supported 13
UCS2 Display supported 14
Proactive SIM: Display Text 16
Proactive SIM: Get Inkey 17
Proactive SIM: Get Input 18
Proactive SIM: More Time 19
Proactive SIM: Play Tone 20
Proactive SIM: Poll Interval 21
Proactive SIM: Polling Off 22
Proactive SIM: Refresh 23
Proactive SIM: Select Item 24
Class sim.toolkit.MEProfile 49
Proactive SIM: Send Short Message 25
Proactive SIM: Send SS 26
Proactive SIM: Send USSD 27
Proactive SIM: Set Up Call 28
Proactive SIM: Set Up Menu 29
Proactive SIM: Provide Local Information 30
Proactive SIM: Provide Local Information (NMR) 31
Proactive SIM: Set Up Event List 32
Event: MT call 33
Event: Call connected 34
Event: Call disconnected 35
Event: Location status 36
Event: User activity 37
Event: Idle screen available 38
Example of use in a standard Toolkit applet: private static final byte PROFILE_USSD = (byte)27;
if (MEProfile.check(PROFILE_USSD) == true) {
// USSD available on the handset
sendTheRequest();
} else {
// abort applet
return;
}
Method Index
check(byte)
Check a facility in the handset profile.
check(byte[], short, short)
Check a set of facilities in the handset profile.
Methods
check public static boolean check(byte index)
Check a facility in the handset profile. In case of phase 2 mobile, this method returns always
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.MEProfile 50
false, but no exception is thrown.
Parameters:
index - the number of the facility to check, according to the table above.
Returns:
true if the facility is supported, false otherwise
check public static boolean check(byte mask[], short offset,
Check a set of facilities in the handset profile. In case of phase 2 mobile, this method returns alwaysfalse, but no exception is thrown. The method checks all the facilities corresponding to bits set to 1 inthe mask buffer.
Parameters:
mask - a byte array containing the mask to compare with the profile
offset - the starting offset of the mask in the byte array
length - the length of the mask (at least 1)
Returns:
true if the set of facilities is supported, false otherwise
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.MEProfile 51
Class sim.toolkit.Registryjava.lang.Object | +----sim.toolkit.Registry
public final class Registry
extends Object
The Registry class offers basic services and methods to allow any Toolkit applet to register its configuration(supported events) during the install phase and possibly to change it during all the applet life time. Eachtoolkit applet should ask the system to build an instance of this class through theregisterToolkit() method of the ToolkitApplet class. The initial state of all the events is cleared.
Note: the constants related to the events are defined in the ToolkitConstants interface.
Example of use in a standard Toolkit applet: public class MyToolkitApplet extends ToolkitApplet implements ToolkitConstants {
// data fields
private Registry reg;
private byte[] menuEntry = { ... };
private byte[] myTAR = {(byte)0x11, (byte)0x22, (byte)0x33};
private byte menuId;
//
// Constructor of applet
//
public MyToolkitApplet() {
// get a Registry object for the applet...
reg = registerToolkit();
// ...and initialize it according to the applet characteristics
menuId = reg.createMenuEntry(menuEntry, (short)0, (short)menuEntry.length,
PRO_CMD_SET_UP_CALL, false);
reg.disableMenuEntry(menuId);
reg.setDataDownloadTAR(myTAR, (short)0);
reg.setEvent(EVENT_CALL_CONTROL_BY_SIM);
}
//
// 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
MyToolkitApplet applet = new MyToolkitApplet();
applet.register();
}
//
// Process toolkit events
// *param event the type of event to be processed
// *exception ToolkitException
//
public void processToolkit(byte event) throws ToolkitException {
if (event == EVENT_FORMATTED_SMS_PP) {
reg.enableMenuEntry(menuId);
} else if (event == EVENT_MENU_SELECTION) {
//...
}
}
Class sim.toolkit.Registry 52
}
See Also:
ToolkitApplet, ToolkitException, ToolkitConstants
Method Index
changeMenuEntry(byte, byte[], short, short, byte, boolean)
Change the value of a menu entry.
clearEvent(byte)
Clear an event in the Registry.
createMenuEntry(byte[], short, short, byte, boolean)
Create a new menu entry.
disableMenuEntry(byte)
Disable a menu entry.
enableMenuEntry(byte)
Enable a menu entry.
isEventSet(byte)
Allow to know if an event is set in the Registry.
setDataDownloadTAR(byte[], short)
Register the SMS-PP Data Download TAR.The TAR (Toolkit Application Reference) will be used to identify the target applet in case offormatted short message.
setEvent(byte)
Set an event in the Registry.
setEventList(byte[], short, short)
Set an event list in the Registry.
Methods
setEvent
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.Registry 53
public void setEvent(byte event) throws ToolkitException
Set an event in the Registry.
Parameters:
event - value of the new event to register (between 0 and 255)
Throws:ToolkitException
EVENT_NOT_SUPPORTED if the event is not supported EVENT_ALREADY_REGISTERED if the event has already been registered (for limitedevent like Call Control)
setEventList public void setEventList(byte eventlist[], short offset, ToolkitException
Set an event list in the Registry.
Parameters:
eventlist - buffer containing thelist of the new events to register
offset - offset in the eventlist buffer for event registration
length - length in the eventlist buffer for event registration
Throws:ToolkitException
EVENT_NOT_SUPPORTED if one event is not supported EVENT_ALREADY_REGISTERED if one event has already been registered (for limited event likeCall Control)
clearEvent public void clearEvent(byte event)
Clear an event in the Registry.
Parameters:
event - the value of the event to unregister (between 0 and 255)
isEventSet public boolean isEventSet(byte event)
Allow to know if an event is set in the Registry.
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.Registry 54
Parameters:
event - the value of the event (between 0 and 255)
Returns:
true if the event is set in the Registry, false otherwise
setDataDownloadTAR public void setDataDownloadTAR(byte tar[], short off sToolkitException
Register the SMS-PP Data Download TAR.The TAR (Toolkit Application Reference) will be used to identify the target applet in case offormatted short message. By calling this method the applet automatically registers to the eventEVENT_FORMATTED_SMS_PP.
Parameters:
tar - buffer containing the Toolkit Applet Reference value (on 3 bytes)
offset - the offset of the TAR within the buffer
Throws:ToolkitException
INVALID_TAR if this TAR is already used
disableMenuEntry public void disableMenuEntry(byte id) throws ToolkitException
Disable a menu entry.
Parameters:
id - the menu entry identifier supplied by the createMenuEntry() method
Throws:ToolkitException
ENTRY_NOT_FOUND if the menu entry does not exist for this applet
enableMenuEntry public void enableMenuEntry(byte id) throws ToolkitException
Enable a menu entry.
Parameters:
id - the menu entry identifier supplied by the createMenuEntry() method
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.Registry 55
Throws:ToolkitException
ENTRY_NOT_FOUND if the menu entry does not exist for this applet
createMenuEntry public byte createMenuEntry(byte menuEntry[], short off sToolkitException
Create a new menu entry. The default state of the new menu entry is 'enabled'. The value of the"helpSupported" boolean parameter defines the registration status of theEVENT_MENU_SELECTION_HELP_REQUEST event. The applet automatically registers to theEVENT_MENU_SELECTION.
Parameters:
menuEntry - a reference on a byte array, containing the new menu entry string
offset - the position of the new menu entry string in the buffer
length - the length of the new menu entry string
nextAction - a byte coding the next action indicator for the new menu entry (or 0)
helpSupported - equals true if help is available for the new menu entry
Returns:
the identifier attached to the new menu entry
Throws:ToolkitException
REGISTRY_ERROR if the new menu entry cannot be created
changeMenuEntry public void changeMenuEntry(byte id, byte menuEntry[], short offset, short length, byte nextAction, boolean helpSupported) throws ToolkitException
Change the value of a menu entry. The default state of the changed menu entry is'enabled'. The value of the "helpSupported" boolean parameter defines theregistration status of the EVENT_MENU_SELECTION_HELP_REQUEST event.
Parameters:
id - the menu entry identifier supplied by the createMenuEntry() method
menuEntry - a reference on a byte array, containing the new menu entry string
offset - the position of the new menu entry string in the buffer
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.Registry 56
length - the length of the new menu entry string
nextAction - a byte coding the next action indicator for the new menu entry (or 0)
helpSupported - equals true if help is available for the new menu entry
Throws:ToolkitException
ENTRY_NOT_FOUND if the menu entry does not exist for this applet
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.Registry 57
Class sim.toolkit.ToolkitAppletjava.lang.Object | +----javacard.framework.Applet | +----sim.toolkit.ToolkitApplet
public abstract class ToolkitApplet
extends Applet
This abstract class defines a Toolkit applet in a smart card. The ToolkitApplet class should be extended byany applet wishing to implement SIM Toolkit features, as described in the GSM 11.14 specification (e.g.Menu Selection event, Call Control by SIM event...), to be loaded onto, installed into and executed on a JavaCard compliant smart card. A toolkit applet can be triggered by the following events :
Event Description
EVENT_PROFILE_DOWNLOAD Terminal Profile command reception
EVENT_FORMATTED_SMS_PP 03.48 formatted envelope SMS-PPData Download reception
EVENT_UNFORMATTED_SMS_PP Unformatted SMS-PP Data Downloadreception
EVENT_UNFORMATTED_SMS_CB Unformatted Cell Broadcast DataDownload command reception
EVENT_MENU_SELECTION Envelope Menu Selection commandreception
EVENT_MENU_SELECTION_HELP_REQUEST Envelope Menu Selection HelpRequest command reception
EVENT_CALL_CONTROL_BY_SIM Envelope Call Control by SIMcommand reception
EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM Envelope MO Short Message Controlby SIM command reception
EVENT_EVENT_DOWNLOAD_MT_CALL Envelope Event Download - MT call
EVENT_EVENT_DOWNLOAD_CALL_CONNECTED Envelope Event Download - Callconnected
EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED Envelope Event Download - Calldisconnected
EVENT_EVENT_DOWNLOAD_LOCATION_STATUS Envelope Event Download - Locationstatus
EVENT_EVENT_DOWNLOAD_USER_ACTIVITY Envelope Event Download - Useractivity
EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE Envelope Event Download - Idlescreen available
Class sim.toolkit.ToolkitApplet 58
EVENT_CARD_RESET Card electrical reset event
EVENT_STATUS_COMMAND Status APDU command event
EVENT_UNRECOGNIZED_ENVELOPE Unrecognized Envelope commandreception
EVENT_PROPRIETARY_EVENT Reserved for proprietary events
Example of standard Toolkit applet: 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 launched.
//
public class HelloWorld extends ToolkitApplet implements 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 Registry reg;
//
// Constructor of applet
//
public HelloWorld() {
// get a Registry object...
// ...and initialize it according to the applet characteristics
reg.createMenuEntry(menuEntry, (short)0, (short)menuEntry.length, PRO_CMD_DISPLAY_TEXT, false);
}
//
// 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_STRING|MASK_COMPREHENSION_REQUIRED), textBuf,
(short)0, (short)textBuf.length);
proHdlr.send();
}
}
}
See Also:
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ToolkitApplet 59
Registry, ToolkitException, ToolkitConstants
Constructor Index
ToolkitApplet()
Only this class's install method should create the ToolkitApplet object.
Method Index
processToolkit(byte)
This method is the standard entry point of a Toolkit applet and shall manage the currentToolkit event, as indicated in the event table.
registerToolkit()
This method is used by the Toolkit applet to register this applet instance with the Toolkitframework and to get the reference of the associated Registry object.
Constructors
ToolkitApplet protected ToolkitApplet()
Only this class's install method should create the ToolkitApplet object.
Methods
registerToolkit protected final Registry registerToolkit() throws ToolkitException
This method is used by the Toolkit applet to register this applet instance with the Toolkitframework and to get the reference of the associated Registry object. At least on event shallbe registered. Other events will be registered with the setEvent() method.
Returns:
reference to a Registry object
Throws:ToolkitException
REGISTRY_ERROR in case of register error
processToolkit public abstract void processToolkit(byte event) throws ToolkitException
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ToolkitApplet 60
This method is the standard entry point of a Toolkit applet and shall manage the current Toolkitevent, as indicated in the event table.
Parameters:
event - the type of event to be processed
Throws:ToolkitException
in case of error
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ToolkitApplet 61
Interface sim.toolkit.ToolkitConstantspublic interface ToolkitConstants
ToolkitConstants encapsulates constants related to the Toolkit applets.
Variable Index
EVENT_CALL_CONTROL_BY_SIM
Event Constant: Call Control by SIM event
EVENT_CARD_RESET
Event Constant: Card electrical reset event
EVENT_EVENT_DOWNLOAD_CALL_CONNECTED
Event Constant: Event Download event - Call connected type
EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED
Event Constant: Event Download event - Call disconnected type
EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE
Event Constant: Event Download event - Idle screen available type
EVENT_EVENT_DOWNLOAD_LOCATION_STATUS
Event Constant: Event Download event - Location status type
EVENT_EVENT_DOWNLOAD_MT_CALL
Event Constant: Event Download event - MT call type
EVENT_EVENT_DOWNLOAD_USER_ACTIVITY
Event Constant: Event Download event - User activity type
EVENT_FORMATTED_SMS_PP
Event Constant: SMS-PP Data Download (03.48 formatted) event
EVENT_MENU_SELECTION
Event Constant: Menu Selection event
EVENT_MENU_SELECTION_HELP_REQUEST
Event Constant: Menu Selection Help Request event
Interface sim.toolkit.ToolkitConstants 62
EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM
Event Constant: MO Short Message Control by SIM event
EVENT_PROFILE_DOWNLOAD
Event Constant: Profile Download event
EVENT_PROPRIETARY_EVENT
Event Constant: Proprietary event
EVENT_STATUS_COMMAND
Event Constant: Status APDU command event
EVENT_UNFORMATTED_SMS_CB
Event Constant: Cell Broadcast Data Download event
EVENT_UNFORMATTED_SMS_PP
Event Constant: Unformatted SMS-PP event
EVENT_UNRECOGNIZED_ENVELOPE
Event Constant: Unrecognized Envelope event
FOUND_CR_NOT_SET
constant: result of the findTLV method
FOUND_CR_SET
constant: result of the findTLV method
MASK_COMPREHENSION_REQUIRED
Constant: mask to add to any tag to set the CR flag
NOT_FOUND
constant: result of the findTLV method
PRO_CMD_DISPLAY_TEXT
Type of proactive command Constant: DISPLAY TEXT
PRO_CMD_GET_INKEY
Type of proactive command Constant: GET INKEY
PRO_CMD_GET_INPUT
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.toolkit.ToolkitConstants 63
Type of proactive command Constant: GET INPUT
PRO_CMD_MORE_TIME
Type of proactive command Constant: MORE TIME
PRO_CMD_PLAY_TONE
Type of proactive command Constant: PLAY TONE
PRO_CMD_POLL_INTERVAL
Type of proactive command Constant: POLL INTERVAL
PRO_CMD_POLLING_OFF
Type of proactive command Constant: POLLING OFF
PRO_CMD_PROVIDE_LOCAL_INFORMATION
Type of proactive command Constant: PROVIDE LOCAL INFORMATION
PRO_CMD_REFRESH
Type of proactive command Constant: REFRESH
PRO_CMD_SELECT_ITEM
Type of proactive command Constant: SELECT ITEM
PRO_CMD_SEND_SHORT_MESSAGE
Type of proactive command Constant: SEND SHORT MESSAGE
PRO_CMD_SEND_SS
Type of proactive command Constant: SEND SS
PRO_CMD_SEND_USSD
Type of proactive command Constant: SEND USSD
PRO_CMD_SET_UP_CALL
Type of proactive command Constant: SET UP CALL
PRO_CMD_SET_UP_EVENT_LIST
Type of proactive command Constant: SET UP EVENT LIST
PRO_CMD_SET_UP_MENU
Type of proactive command Constant: SET UP MENU
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.toolkit.ToolkitConstants 64
TAG_ADDRESS
Simple TLV Constant: Address tag
TAG_ALPHA_IDENTIFIER
Simple TLV Constant: Alpha Identifier tag
TAG_BCCH_CHANNEL_LIST
Simple TLV Constant: BCCH Channel List tag
TAG_CALL_CONTROL_REQUESTED_ACTION
Simple TLV Constant: Call Control requested action tag
TAG_CALLED_PARTY_SUBADDRESS
Simple TLV Constant: Called Party Subaddress tag
TAG_CAPABILITY_CONFIGURATION_PARAMETERS
Simple TLV Constant: Capability Configuration Parameters tag
TAG_CAUSE
Simple TLV Constant: Cause tag
TAG_CELL_BROADCAST_PAGE
Simple TLV Constant: Cell Broadcast Page tag
TAG_COMMAND_DETAILS
Simple TLV Constant: Command Details tag
TAG_DEFAULT_TEXT
Simple TLV Constant: Default Text tag
TAG_DEVICE_IDENTITIES
Simple TLV Constant: Device Identities tag
TAG_DURATION
Simple TLV Constant: Duration tag
TAG_EVENT_LIST
Simple TLV Constant: Event List tag
TAG_FILE_LIST
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.toolkit.ToolkitConstants 65
Simple TLV Constant: File List tag
TAG_HELP_REQUEST
Simple TLV Constant: Help Request tag
TAG_IMEI
Simple TLV Constant: IMEI tag
TAG_ITEM
Simple TLV Constant: Item tag
TAG_ITEM_IDENTIFIER
Simple TLV Constant: Item Identifier tag
TAG_ITEMS_NEXT_ACTION_INDICATOR
Simple TLV Constant: Items Next Action Indicator tag
TAG_LOCATION_INFORMATION
Simple TLV Constant: Location Information tag
TAG_LOCATION_STATUS
Simple TLV Constant: Location Status tag
TAG_NETWORK_MEASUREMENT_RESULTS
Simple TLV Constant: Network Measurement Results tag
TAG_RESPONSE_LENGTH
Simple TLV Constant: Response Length tag
TAG_RESULT
Simple TLV Constant: Result tag
TAG_SMS_TPDU
Simple TLV Constant: SMS TPDU tag
TAG_SS_STRING
Simple TLV Constant: SS String tag
TAG_TEXT_STRING
Simple TLV Constant: Text String tag
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.toolkit.ToolkitConstants 66
TAG_TONE
Simple TLV Constant: Tone tag
TAG_TRANSACTION_IDENTIFIER
Simple TLV Constant: Transaction Identifier tag
TAG_USSD_STRING
Simple TLV Constant: USSD String tag
Variables
EVENT_PROFILE_DOWNLOAD public static final byte EVENT_PROFILE_DOWNLOAD
Event Constant: Profile Download event
EVENT_FORMATTED_SMS_PP public static final byte EVENT_FORMATTED_SMS_PP
Event Constant: SMS-PP Data Download (03.48 formatted) event
EVENT_UNFORMATTED_SMS_PP public static final byte EVENT_UNFORMATTED_SMS_PP
Event Constant: Unformatted SMS-PP event
EVENT_UNFORMATTED_SMS_CB public static final byte EVENT_UNFORMATTED_SMS_CB
Event Constant: Cell Broadcast Data Download event
EVENT_MENU_SELECTION public static final byte EVENT_MENU_SELECTION
Event Constant: Menu Selection event
EVENT_MENU_SELECTION_HELP_REQUEST public static final byte EVENT_MENU_SELECTION_HELP_REQUEST
Event Constant: Menu Selection Help Request event
EVENT_CALL_CONTROL_BY_SIM public static final byte EVENT_CALL_CONTROL_BY_SIM
Event Constant: Call Control by SIM event
EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM public static final byte EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM
Event Constant: MO Short Message Control by SIM event
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.toolkit.ToolkitConstants 67
EVENT_EVENT_DOWNLOAD_MT_CALL public static final byte EVENT_EVENT_DOWNLOAD_MT_CALL
Event Constant: Event Download event - MT call type
EVENT_EVENT_DOWNLOAD_CALL_CONNECTED public static final byte EVENT_EVENT_DOWNLOAD_CALL_CONNECTED
Event Constant: Event Download event - Call connected type
EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED public static final byte EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED
Event Constant: Event Download event - Call disconnected type
EVENT_EVENT_DOWNLOAD_LOCATION_STATUS public static final byte EVENT_EVENT_DOWNLOAD_LOCATION_STATUS
Event Constant: Event Download event - Location status type
EVENT_EVENT_DOWNLOAD_USER_ACTIVITY public static final byte EVENT_EVENT_DOWNLOAD_USER_ACTIVITY
Event Constant: Event Download event - User activity type
EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE public static final byte EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE
Event Constant: Event Download event - Idle screen available type
EVENT_UNRECOGNIZED_ENVELOPE public static final byte EVENT_UNRECOGNIZED_ENVELOPE
Event Constant: Unrecognized Envelope event
EVENT_PROPRIETARY_EVENT public static final byte EVENT_PROPRIETARY_EVENT
Event Constant: Proprietary event
EVENT_CARD_RESET public static final byte EVENT_CARD_RESET
Event Constant: Card electrical reset event
EVENT_STATUS_COMMAND public static final byte EVENT_STATUS_COMMAND
Event Constant: Status APDU command event
TAG_COMMAND_DETAILS public static final byte TAG_COMMAND_DETAILS
Simple TLV Constant: Command Details tag
TAG_DEVICE_IDENTITIES
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.toolkit.ToolkitConstants 68
public static final byte TAG_DEVICE_IDENTITIES
Simple TLV Constant: Device Identities tag
TAG_RESULT public static final byte TAG_RESULT
Simple TLV Constant: Result tag
TAG_DURATION public static final byte TAG_DURATION
Simple TLV Constant: Duration tag
TAG_ALPHA_IDENTIFIER public static final byte TAG_ALPHA_IDENTIFIER
Simple TLV Constant: Alpha Identifier tag
TAG_ADDRESS public static final byte TAG_ADDRESS
Simple TLV Constant: Address tag
TAG_CAPABILITY_CONFIGURATION_PARAMETERS public static final byte TAG_CAPABILITY_CONFIGURATION_PARAMETERS
Simple TLV Constant: Capability Configuration Parameters tag
TAG_CALLED_PARTY_SUBADDRESS public static final byte TAG_CALLED_PARTY_SUBADDRESS
Simple TLV Constant: Called Party Subaddress tag
TAG_SS_STRING public static final byte TAG_SS_STRING
Simple TLV Constant: SS String tag
TAG_USSD_STRING public static final byte TAG_USSD_STRING
Simple TLV Constant: USSD String tag
TAG_SMS_TPDU public static final byte TAG_SMS_TPDU
Simple TLV Constant: SMS TPDU tag
TAG_CELL_BROADCAST_PAGE public static final byte TAG_CELL_BROADCAST_PAGE
Simple TLV Constant: Cell Broadcast Page tag
TAG_TEXT_STRING public static final byte TAG_TEXT_STRING
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.toolkit.ToolkitConstants 69
Simple TLV Constant: Text String tag
TAG_TONE public static final byte TAG_TONE
Simple TLV Constant: Tone tag
TAG_ITEM public static final byte TAG_ITEM
Simple TLV Constant: Item tag
TAG_ITEM_IDENTIFIER public static final byte TAG_ITEM_IDENTIFIER
Simple TLV Constant: Item Identifier tag
TAG_RESPONSE_LENGTH public static final byte TAG_RESPONSE_LENGTH
Simple TLV Constant: Response Length tag
TAG_FILE_LIST public static final byte TAG_FILE_LIST
Simple TLV Constant: File List tag
TAG_LOCATION_INFORMATION public static final byte TAG_LOCATION_INFORMATION
Simple TLV Constant: Location Information tag
TAG_IMEI public static final byte TAG_IMEI
Simple TLV Constant: IMEI tag
TAG_HELP_REQUEST public static final byte TAG_HELP_REQUEST
Simple TLV Constant: Help Request tag
TAG_NETWORK_MEASUREMENT_RESULTS public static final byte TAG_NETWORK_MEASUREMENT_RESULTS
Simple TLV Constant: Network Measurement Results tag
TAG_DEFAULT_TEXT public static final byte TAG_DEFAULT_TEXT
Simple TLV Constant: Default Text tag
TAG_ITEMS_NEXT_ACTION_INDICATOR public static final byte TAG_ITEMS_NEXT_ACTION_INDICATOR
Simple TLV Constant: Items Next Action Indicator tag
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.toolkit.ToolkitConstants 70
TAG_EVENT_LIST public static final byte TAG_EVENT_LIST
Simple TLV Constant: Event List tag
TAG_CAUSE public static final byte TAG_CAUSE
Simple TLV Constant: Cause tag
TAG_LOCATION_STATUS public static final byte TAG_LOCATION_STATUS
Simple TLV Constant: Location Status tag
TAG_TRANSACTION_IDENTIFIER public static final byte TAG_TRANSACTION_IDENTIFIER
Simple TLV Constant: Transaction Identifier tag
TAG_BCCH_CHANNEL_LIST public static final byte TAG_BCCH_CHANNEL_LIST
Simple TLV Constant: BCCH Channel List tag
TAG_CALL_CONTROL_REQUESTED_ACTION public static final byte TAG_CALL_CONTROL_REQUESTED_ACTION
Simple TLV Constant: Call Control requested action tag
MASK_COMPREHENSION_REQUIRED public static final byte MASK_COMPREHENSION_REQUIRED
Constant: mask to add to any tag to set the CR flag
NOT_FOUND public static final byte NOT_FOUND
constant: result of the findTLV method
FOUND_CR_SET public static final byte FOUND_CR_SET
constant: result of the findTLV method
FOUND_CR_NOT_SET public static final byte FOUND_CR_NOT_SET
constant: result of the findTLV method
PRO_CMD_REFRESH public static final byte PRO_CMD_REFRESH
Type of proactive command Constant: REFRESH
PRO_CMD_MORE_TIME
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.toolkit.ToolkitConstants 71
public static final byte PRO_CMD_MORE_TIME
Type of proactive command Constant: MORE TIME
PRO_CMD_POLL_INTERVAL public static final byte PRO_CMD_POLL_INTERVAL
Type of proactive command Constant: POLL INTERVAL
PRO_CMD_POLLING_OFF public static final byte PRO_CMD_POLLING_OFF
Type of proactive command Constant: POLLING OFF
PRO_CMD_SET_UP_EVENT_LIST public static final byte PRO_CMD_SET_UP_EVENT_LIST
Type of proactive command Constant: SET UP EVENT LIST
PRO_CMD_SET_UP_CALL public static final byte PRO_CMD_SET_UP_CALL
Type of proactive command Constant: SET UP CALL
PRO_CMD_SEND_SS public static final byte PRO_CMD_SEND_SS
Type of proactive command Constant: SEND SS
PRO_CMD_SEND_USSD public static final byte PRO_CMD_SEND_USSD
Type of proactive command Constant: SEND USSD
PRO_CMD_SEND_SHORT_MESSAGE public static final byte PRO_CMD_SEND_SHORT_MESSAGE
Type of proactive command Constant: SEND SHORT MESSAGE
PRO_CMD_PLAY_TONE public static final byte PRO_CMD_PLAY_TONE
Type of proactive command Constant: PLAY TONE
PRO_CMD_DISPLAY_TEXT public static final byte PRO_CMD_DISPLAY_TEXT
Type of proactive command Constant: DISPLAY TEXT
PRO_CMD_GET_INKEY public static final byte PRO_CMD_GET_INKEY
Type of proactive command Constant: GET INKEY
PRO_CMD_GET_INPUT public static final byte PRO_CMD_GET_INPUT
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.toolkit.ToolkitConstants 72
Type of proactive command Constant: GET INPUT
PRO_CMD_SELECT_ITEM public static final byte PRO_CMD_SELECT_ITEM
Type of proactive command Constant: SELECT ITEM
PRO_CMD_SET_UP_MENU public static final byte PRO_CMD_SET_UP_MENU
Type of proactive command Constant: SET UP MENU
PRO_CMD_PROVIDE_LOCAL_INFORMATION public static final byte PRO_CMD_PROVIDE_LOCAL_INFORMATION
Type of proactive command Constant: PROVIDE LOCAL INFORMATION
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Interface sim.toolkit.ToolkitConstants 73
Class sim.toolkit.ToolkitExceptionjava.lang.Object | +----java.lang.Throwable | +----java.lang.Exception | +----java.lang.RuntimeException | +----javacard.framework.CardRuntimeException | +----sim.toolkit.ToolkitException
public class ToolkitException
extends CardRuntimeException
This class extends the Throwable class and allows the classes of this package to throw specific exceptions incase of problems.
Table ToolkitException
reason Description
BUFFER_OVERFLOW Data larger than storage buffer
HANDLER_NOT_AVAILABLE Handler cannot be accessed (e.g. busy)
PROACTIVE_NOT_SUPPORTED Proactive SIM not supported by ME
UNAVAILABLE_ELEMENT No available element in the handler buffer
INVALID_TAR TAR already used
ENTRY_NOT_FOUND Menu entry not found
REGISTRY_ERROR Error in the registry information
EVENT_NOT_SUPPORTED Event code not supported
EVENT_ALREADY_REGISTERED Event already registered for limited events(e.g Call Control)
Variable Index
BUFFER_OVERFLOW
Constant: reason code for buffer overflow
ENTRY_NOT_FOUND
Constant: reason code for a non-existent menu entry
EVENT_ALREADY_REGISTERED
Class sim.toolkit.ToolkitException 74
Constant: reason code for event already registered (e.g Call Control)
EVENT_NOT_SUPPORTED
Constant: reason code for event code not supported
HANDLER_NOT_AVAILABLE
Constant: reason code for Handler cannot be accessed (e.g.
INVALID_TAR
Constant: reason code for TAR already used
PROACTIVE_NOT_SUPPORTED
Constant: reason code for Proactive command not supported by ME
REGISTRY_ERROR
Constant: reason code for error in the registry information
UNAVAILABLE_ELEMENT
Constant: reason code for unavailable element in the handler buffer
Constructor Index
ToolkitException(short)
Construct a ToolkitException instance with the specified reason.
Method Index
throwIt(short)
Throws the JCRE instance of the ToolkitException class with the specified reason.
Variables
BUFFER_OVERFLOW public static final short BUFFER_OVERFLOW
Constant: reason code for buffer overflow
HANDLER_NOT_AVAILABLE public static final short HANDLER_NOT_AVAILABLE
Constant: reason code for Handler cannot be accessed (e.g. busy)
PROACTIVE_NOT_SUPPORTED
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ToolkitException 75
public static final short PROACTIVE_NOT_SUPPORTED
Constant: reason code for Proactive command not supported by ME
UNAVAILABLE_ELEMENT public static final short UNAVAILABLE_ELEMENT
Constant: reason code for unavailable element in the handler buffer
INVALID_TAR public static final short INVALID_TAR
Constant: reason code for TAR already used
ENTRY_NOT_FOUND public static final short ENTRY_NOT_FOUND
Constant: reason code for a non-existent menu entry
REGISTRY_ERROR public static final short REGISTRY_ERROR
Constant: reason code for error in the registry information
EVENT_NOT_SUPPORTED public static final short EVENT_NOT_SUPPORTED
Constant: reason code for event code not supported
EVENT_ALREADY_REGISTERED public static final short EVENT_ALREADY_REGISTERED
Constant: reason code for event already registered (e.g Call Control)
Constructors
ToolkitException public ToolkitException(short reason)
Construct a ToolkitException instance with the specified reason. To conserve on resourcesuse throwIt() method to re-use the JCRE instance of this class.
Parameters:
reason - the reason for the exception
Methods throwIt public static void throwIt(short reason) throws ToolkitException
Throws the JCRE instance of the ToolkitException class with the specified reason.
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ToolkitException 76
Parameters:
reason - the reason for the exception.
Throws:ToolkitException
always
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Class sim.toolkit.ToolkitException 77
Index of all Fields and Methods
A
AC_NOT_FULFILLED . Static variable in class sim.access.SIMViewException
Constant: Access condition level not fulfilled
appendArray(byte[], short, short). Method in class sim.toolkit.EditHandler
Append a buffer into the EditHandler buffer.
appendTLV(byte, byte). Method in class sim.toolkit.EditHandler
Append a TLV element to the current Proactive command (1-byte element)(useful to add single byte elements as Item Identifier or Tone).
appendTLV(byte, byte, byte). Method in class sim.toolkit.EditHandler
Append a TLV element to the current Proactive command (2-byte element)(useful to add double byte elements as Device Identities, Duration or Response Length).
appendTLV(byte, byte, byte[], short, short). Method in class sim.toolkit.EditHandler
Append a TLV element to the current Proactive command (byte array format)
appendTLV(byte, byte[], short, short). Method in class sim.toolkit.EditHandler
Append a TLV element to the current Proactive command (byte array format)
B
BUFFER_OVERFLOW. Static variable in class sim.toolkit.ToolkitException
Constant: reason code for buffer overflow
C
changeMenuEntry(byte, byte[], short, short, byte, boolean). Method in class sim.toolkit.Registry
Change the value of a menu entry.
check(byte). Static method in class sim.toolkit.MEProfile
Index of all Fields and Methods 78
Check a facility in the handset profile.
check(byte[], short, short). Static method in class sim.toolkit.MEProfile
Check a set of facilities in the handset profile.
clear(). Method in class sim.toolkit.EditHandler
Clear an EditHandler buffer.
clearEvent(byte). Method in class sim.toolkit.Registry
Clear an event in the Registry.
compareValue(short, byte[], short, short). Method in class sim.toolkit.ViewHandler
Compare the last found TLV element with a buffer.
copyAdditionalInformation(byte[], short, short). Method in classsim.toolkit.ProactiveResponseHandler
Copy a part of the additional information field from the first Result TLV element of thecurrent response data field.
copyTextString(byte[], short). Method in class sim.toolkit.ProactiveResponseHandler
Copy the text string value from the first Text String TLV element of the current responsedata field.
copyValue(short, byte[], short, short). Method in class sim.toolkit.ViewHandler
Copy a part of the last TLV element which has been found, into a destination buffer.
createMenuEntry(byte[], short, short, byte, boolean). Method in class sim.toolkit.Registry
Create a new menu entry.
CURRENT_EF_INVALIDATED. Static variable in class sim.access.SIMViewException
Constant: Current EF invalidated
D
disableMenuEntry(byte). Method in class sim.toolkit.Registry
Disable a menu entry.
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 79
E
EditHandler(byte[], short, short). Constructor for class sim.toolkit.EditHandler
Build a new EditHandler object.
enableMenuEntry(byte). Method in class sim.toolkit.Registry
Enable a menu entry.
ENTRY_NOT_FOUND. Static variable in class sim.toolkit.ToolkitException
Constant: reason code for a non-existent menu entry
EVENT_ALREADY_REGISTERED. Static variable in class sim.toolkit.ToolkitException
Constant: reason code for event already registered (e.g Call Control)
EVENT_CALL_CONTROL_BY_SIM. Static variable in interface sim.toolkit.ToolkitConstants
Event Constant: Call Control by SIM event
EVENT_CARD_RESET. Static variable in interface sim.toolkit.ToolkitConstants
Event Constant: Card electrical reset event
EVENT_EVENT_DOWNLOAD_CALL_CONNECTED. Static variable in interfacesim.toolkit.ToolkitConstants
Event Constant: Event Download event - Call connected type
EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED. Static variable in interfacesim.toolkit.ToolkitConstants
Event Constant: Event Download event - Call disconnected type
EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE. Static variable in interfacesim.toolkit.ToolkitConstants
Event Constant: Event Download event - Idle screen available type
EVENT_EVENT_DOWNLOAD_LOCATION_STATUS. Static variable in interfacesim.toolkit.ToolkitConstants
Event Constant: Event Download event - Location status type
EVENT_EVENT_DOWNLOAD_MT_CALL. Static variable in interfacesim.toolkit.ToolkitConstants
Event Constant: Event Download event - MT call type
EVENT_EVENT_DOWNLOAD_USER_ACTIVITY. Static variable in interfacesim.toolkit.ToolkitConstants
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 80
Event Constant: Event Download event - User activity type
EVENT_FORMATTED_SMS_PP. Static variable in interface sim.toolkit.ToolkitConstants
Event Constant: SMS-PP Data Download (03.48 formatted) event
EVENT_MENU_SELECTION. Static variable in interface sim.toolkit.ToolkitConstants
Event Constant: Menu Selection event
EVENT_MENU_SELECTION_HELP_REQUEST. Static variable in interfacesim.toolkit.ToolkitConstants
Event Constant: Menu Selection Help Request event
EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM. Static variable in interfacesim.toolkit.ToolkitConstants
Event Constant: MO Short Message Control by SIM event
EVENT_NOT_SUPPORTED. Static variable in class sim.toolkit.ToolkitException
Constant: reason code for event code not supported
EVENT_PROFILE_DOWNLOAD. Static variable in interface sim.toolkit.ToolkitConstants
Event Constant: Profile Download event
EVENT_PROPRIETARY_EVENT. Static variable in interface sim.toolkit.ToolkitConstants
Event Constant: Proprietary event
EVENT_STATUS_COMMAND. Static variable in interface sim.toolkit.ToolkitConstants
Event Constant: Status APDU command event
EVENT_UNFORMATTED_SMS_CB. Static variable in interface sim.toolkit.ToolkitConstants
Event Constant: Cell Broadcast Data Download event
EVENT_UNFORMATTED_SMS_PP. Static variable in interface sim.toolkit.ToolkitConstants
Event Constant: Unformatted SMS-PP event
EVENT_UNRECOGNIZED_ENVELOPE. Static variable in interface sim.toolkit.ToolkitConstants
Event Constant: Unrecognized Envelope event
F
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 81
FID_DF_DCS. Static variable in interface sim.access.SIMView
Constant: File identifier of the DF DCS1800
FID_DF_GSM. Static variable in interface sim.access.SIMView
Constant: File identifier of the DF GSM
FID_DF_TELECOM . Static variable in interface sim.access.SIMView
Constant: File identifier of the DF TELECOM
FID_MF . Static variable in interface sim.access.SIMView
Constant: File identifier of the MF
FILE_INCONSISTENT. Static variable in class sim.access.SIMViewException
Constant: File inconsistent with the method
FILE_NOT_FOUND. Static variable in class sim.access.SIMViewException
Constant: File not found
findAndCompareValue(byte, byte, short, byte[], short, short). Method in classsim.toolkit.ViewHandler
Look for the first occurence of a TLV element and compare its value with a buffer.
findAndCompareValue(byte, byte[], short). Method in class sim.toolkit.ViewHandler
Look for the first occurence of a TLV element and compare its value with a buffer.
findAndCopyValue(byte, byte, short, byte[], short, short). Method in class sim.toolkit.ViewHandler
Look for the first occurence of a TLV element and copy its value into a destination buffer.
findAndCopyValue(byte, byte[], short). Method in class sim.toolkit.ViewHandler
Look for the first occurence of a TLV element and copy its value into a destination buffer.
findTLV (byte, byte). Method in class sim.toolkit.ViewHandler
Look for a TLV element in the TLV structure (handler buffer).
FOUND_CR_NOT_SET. Static variable in interface sim.toolkit.ToolkitConstants
constant: result of the findTLV method
FOUND_CR_SET. Static variable in interface sim.toolkit.ToolkitConstants
constant: result of the findTLV method
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 82
G
getAdditionalInformationLength(). Method in class sim.toolkit.ProactiveResponseHandler
Return the length of the additional information field from the first Result TLV element of thecurrent response data field.
getDurationInterval(). Method in class sim.toolkit.ProactiveResponseHandler
Return the duration interval value from the first Duration TLV element of the currentresponse data field.
getDurationUnit(). Method in class sim.toolkit.ProactiveResponseHandler
Return the duration unit byte from the first Duration TLV element of the current responsedata field.
getEnvelopeTag(). Method in class sim.toolkit.EnvelopeHandler
Return the Envelope BER-TLV tag.
getGeneralResult(). Method in class sim.toolkit.ProactiveResponseHandler
Return the general result byte of the Proactive command.
getItemIdentifier(). Method in class sim.toolkit.EnvelopeHandler
Return the item identifier byte value from the first Item Identifier TLV element in the currentEnvelope data field.
getItemIdentifier(). Method in class sim.toolkit.ProactiveResponseHandler
Return the item identifier byte value from the first Item Identifier TLV element of the currentresponse data field.
getLength(). Method in class sim.toolkit.EditHandler
Return the length of the current SIMPLE TLV list.
getTextStringCodingScheme(). Method in class sim.toolkit.ProactiveResponseHandler
Return the data coding scheme byte from the first Text String TLV element of the currentresponse data field.
getTextStringLength(). Method in class sim.toolkit.ProactiveResponseHandler
Return the text string length value from the first Text String TLV element of the currentresponse data field.
getTheHandler(). Static method in class sim.toolkit.EnvelopeHandler
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 83
Return the single system instance of the EnvelopeHandler class.
getTheHandler(). Static method in class sim.toolkit.EnvelopeResponseHandler
Return the single system instance of the EnvelopeResponseHandler class.
getTheHandler(). Static method in class sim.toolkit.ProactiveHandler
Return the single system instance of the ProactiveHandler class.
getTheHandler(). Static method in class sim.toolkit.ProactiveResponseHandler
Return the single system instance of the ProactiveResponseHandler class.
getTheSIMView(). Static method in class sim.access.SIMSystem
Return a reference to the GSM interface
getTPOAOffset(). Method in class sim.toolkit.EnvelopeHandler
Look for the TP-OA field in the first TPDU TLV element in the Envelope data field.
getTPUDOffset(). Method in class sim.toolkit.EnvelopeHandler
Look for the TP-UD field in the first TPDU TLV element in the Envelope data field.
getValueByte(short). Method in class sim.toolkit.ViewHandler
Get a byte from the last TLV element which has been found in the buffer.
getValueLength(). Method in class sim.toolkit.ViewHandler
Get the length of the value field for the last TLV element which has been found in the buffer.
H
HANDLER_NOT_AVAILABLE . Static variable in class sim.toolkit.ToolkitException
Constant: reason code for Handler cannot be accessed (e.g.
I
increase(byte[], short, byte[], short). Method in interface sim.access.SIMView
INCREASE command as defined in GSM 11.11 standard.This method increases the current cyclic EF record of the calling applet.
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 84
init (byte, byte, byte). Method in class sim.toolkit.ProactiveHandler
Initialize the next Proactive command with Command Details and Device Identities TLV.The source device is always the SIM card.
initDisplayText(byte, byte, byte[], short, short). Method in class sim.toolkit.ProactiveHandler
Build a Display Text Proactive command without sending the command.
initGetInkey(byte, byte, byte[], short, short). Method in class sim.toolkit.ProactiveHandler
Build a Get Inkey Proactive command without sending the command.
initGetInput(byte, byte, byte[], short, short, short, short). Method in classsim.toolkit.ProactiveHandler
Initialize the building of a Get Input Proactive command.
initPollInterval (byte, short). Method in class sim.toolkit.ProactiveHandler
Build a Poll Interval Proactive command without sending the command.
INTERNAL_ERROR. Static variable in class sim.access.SIMViewException
Constant: Internal error
INVALID_MODE . Static variable in class sim.access.SIMViewException
Constant: Invalid mode for seek command or record access
INVALID_TAR . Static variable in class sim.toolkit.ToolkitException
Constant: reason code for TAR already used
invalidate(). Method in interface sim.access.SIMView
INVALIDATE command as defined in GSM 11.11 standard.This method invalidates the currently selected EF of the calling applet.
INVALIDATION_STATUS_CONTRADICTION. Static variable in classsim.access.SIMViewException
Constant: Method in contradiction with the invalidation status
isEventSet(byte). Method in class sim.toolkit.Registry
Allow to know if an event is set in the Registry.
M
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 85
MASK_COMPREHENSION_REQUIRED. Static variable in interface sim.toolkit.ToolkitConstants
Constant: mask to add to any tag to set the CR flag
MAX_VALUE_REACHED. Static variable in class sim.access.SIMViewException
Constant: Max value reached for increase command
MODE_ABSOLUTE. Static variable in interface sim.access.SIMView
Constant: Record access mode 'absolute'
MODE_CURRENT. Static variable in interface sim.access.SIMView
Constant: Record access mode 'current'
MODE_NEXT. Static variable in interface sim.access.SIMView
Constant: Record access mode 'next'
MODE_PREVIOUS. Static variable in interface sim.access.SIMView
Constant: Record access mode 'previous'
N
NO_EF_SELECTED. Static variable in class sim.access.SIMViewException
Constant: No EF selected before calling the method
NOT_FOUND. Static variable in interface sim.toolkit.ToolkitConstants
constant: result of the findTLV method
O
OUT_OF_BUFFER_BOUNDARIES. Static variable in class sim.access.SIMViewException
Constant: Out of the buffer boundaries (response or data)
OUT_OF_FILE_BOUNDARIES. Static variable in class sim.access.SIMViewException
Constant: Out of the transparent file boundaries
OUT_OF_RECORD_BOUNDARIES. Static variable in class sim.access.SIMViewException
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 86
Constant: Out of the record boundaries
P
PATTERN_NOT_FOUND. Static variable in class sim.access.SIMViewException
Constant: Pattern not found for seek command
PATTERN_SIZE_INCONSISTENT. Static variable in class sim.access.SIMViewException
Constant: Pattern size greater than record size
post(byte). Method in class sim.toolkit.EnvelopeResponseHandler
Post the Envelope response.
postAsBERTLV(byte, byte). Method in class sim.toolkit.EnvelopeResponseHandler
Post the Envelope response in a BER TLV structure.
PRO_CMD_DISPLAY_TEXT. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: DISPLAY TEXT
PRO_CMD_GET_INKEY. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: GET INKEY
PRO_CMD_GET_INPUT. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: GET INPUT
PRO_CMD_MORE_TIME. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: MORE TIME
PRO_CMD_PLAY_TONE. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: PLAY TONE
PRO_CMD_POLL_INTERVAL. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: POLL INTERVAL
PRO_CMD_POLLING_OFF. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: POLLING OFF
PRO_CMD_PROVIDE_LOCAL_INFORMATION. Static variable in interfacesim.toolkit.ToolkitConstants
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 87
Type of proactive command Constant: PROVIDE LOCAL INFORMATION
PRO_CMD_REFRESH. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: REFRESH
PRO_CMD_SELECT_ITEM. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: SELECT ITEM
PRO_CMD_SEND_SHORT_MESSAGE. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: SEND SHORT MESSAGE
PRO_CMD_SEND_SS. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: SEND SS
PRO_CMD_SEND_USSD. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: SEND USSD
PRO_CMD_SET_UP_CALL. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: SET UP CALL
PRO_CMD_SET_UP_EVENT_LIST. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: SET UP EVENT LIST
PRO_CMD_SET_UP_MENU. Static variable in interface sim.toolkit.ToolkitConstants
Type of proactive command Constant: SET UP MENU
PROACTIVE_NOT_SUPPORTED. Static variable in class sim.toolkit.ToolkitException
Constant: reason code for Proactive command not supported by ME
processToolkit(byte). Method in class sim.toolkit.ToolkitApplet
This method is the standard entry point of a Toolkit applet and shall manage the currentToolkit event, as indicated in the event table.
R
readBinary(short, byte[], short, short). Method in interface sim.access.SIMView
READ BINARY command as defined in GSM 11.11 standard.This method reads the data bytes of the current transparent EF of the calling applet.
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 88
readRecord(short, byte, short, byte[], short, short). Method in interface sim.access.SIMView
READ RECORD command as defined in GSM 11.11 standard.This method reads the data bytes of the current linear fixed/cyclic EF of the calling applet.
RECORD_NUMBER_NOT_AVAILABLE. Static variable in class sim.access.SIMViewException
Constant: Record number not available
registerToolkit(). Method in class sim.toolkit.ToolkitApplet
This method is used by the Toolkit applet to register this applet instance with the Toolkitframework and to get the reference of the associated Registry object.
REGISTRY_ERROR. Static variable in class sim.toolkit.ToolkitException
Constant: reason code for error in the registry information
rehabilitate(). Method in interface sim.access.SIMView
REHABILITATE command as defined in GSM 11.11 standard.This method rehabilitates the currently selected EF of the calling applet.
S
seek(byte, byte[], short, short). Method in interface sim.access.SIMView
SEEK command as defined in GSM 11.11 standard.This method seeks a pattern in the current linear fixed EF of the calling applet.
SEEK_FROM_BEGINNING_FORWARD. Static variable in interface sim.access.SIMView
Constant: Seek mode, from the beginning forward
SEEK_FROM_END_BACKWARD. Static variable in interface sim.access.SIMView
Constant: Seek mode, from the end backward
SEEK_FROM_NEXT_FORWARD. Static variable in interface sim.access.SIMView
Constant: Seek mode, from the next location forward
SEEK_FROM_PREVIOUS_BACKWARD. Static variable in interface sim.access.SIMView
Constant: Seek mode, from the previous location backward
select(byte[], short, short, short). Method in interface sim.access.SIMView
SELECT command as defined in GSM 11.11 standard.By default, the MF is selected at the beginning of each applet activation (current file = MF).
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 89
select(short). Method in interface sim.access.SIMView
SELECT command as defined in GSM 11.11 standard.This SELECT method allows to update the current file without handling the Select ResponseBy default, the MF is selected at the beginning of each applet activation (current file = MF).
send(). Method in class sim.toolkit.ProactiveHandler
Send the current Proactive command.
setDataDownloadTAR(byte[], short). Method in class sim.toolkit.Registry
Register the SMS-PP Data Download TAR.The TAR (Toolkit Application Reference) will be used to identify the target applet in case offormatted short message.
setEvent(byte). Method in class sim.toolkit.Registry
Set an event in the Registry.
setEventList(byte[], short, short). Method in class sim.toolkit.Registry
Set an event list in the Registry.
SIMSystem(). Constructor for class sim.access.SIMSystem
SIMViewException(short). Constructor for class sim.access.SIMViewException
Constructs a SIMViewException object.
status(byte[], short, short). Method in interface sim.access.SIMView
STATUS command as defined in GSM 11.11 standard.This method returns the FCI (File Control Information) of the current DF (or MF) of thecalling applet.
T
TAG_ADDRESS. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Address tag
TAG_ALPHA_IDENTIFIER . Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Alpha Identifier tag
TAG_BCCH_CHANNEL_LIST. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: BCCH Channel List tag
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 90
TAG_CALL_CONTROL_REQUESTED_ACTION. Static variable in interfacesim.toolkit.ToolkitConstants
Simple TLV Constant: Call Control requested action tag
TAG_CALLED_PARTY_SUBADDRESS. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Called Party Subaddress tag
TAG_CAPABILITY_CONFIGURATION_PARAMETERS. Static variable in interfacesim.toolkit.ToolkitConstants
Simple TLV Constant: Capability Configuration Parameters tag
TAG_CAUSE. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Cause tag
TAG_CELL_BROADCAST_PAGE. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Cell Broadcast Page tag
TAG_COMMAND_DETAILS. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Command Details tag
TAG_DEFAULT_TEXT. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Default Text tag
TAG_DEVICE_IDENTITIES . Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Device Identities tag
TAG_DURATION. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Duration tag
TAG_EVENT_LIST. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Event List tag
TAG_FILE_LIST . Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: File List tag
TAG_HELP_REQUEST. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Help Request tag
TAG_IMEI . Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: IMEI tag
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 91
TAG_ITEM. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Item tag
TAG_ITEM_IDENTIFIER . Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Item Identifier tag
TAG_ITEMS_NEXT_ACTION_INDICATOR. Static variable in interfacesim.toolkit.ToolkitConstants
Simple TLV Constant: Items Next Action Indicator tag
TAG_LOCATION_INFORMATION. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Location Information tag
TAG_LOCATION_STATUS. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Location Status tag
TAG_NETWORK_MEASUREMENT_RESULTS. Static variable in interfacesim.toolkit.ToolkitConstants
Simple TLV Constant: Network Measurement Results tag
TAG_RESPONSE_LENGTH. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Response Length tag
TAG_RESULT. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Result tag
TAG_SMS_TPDU. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: SMS TPDU tag
TAG_SS_STRING. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: SS String tag
TAG_TEXT_STRING. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Text String tag
TAG_TONE. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Tone tag
TAG_TRANSACTION_IDENTIFIER. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: Transaction Identifier tag
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 92
TAG_USSD_STRING. Static variable in interface sim.toolkit.ToolkitConstants
Simple TLV Constant: USSD String tag
throwIt(short). Static method in class sim.access.SIMViewException
Throws the JCRE instance of SIMViewException with the specified reason.
throwIt(short). Static method in class sim.toolkit.ToolkitException
Throws the JCRE instance of the ToolkitException class with the specified reason.
ToolkitApplet(). Constructor for class sim.toolkit.ToolkitApplet
Only this class's install method should create the ToolkitApplet object.
ToolkitException(short). Constructor for class sim.toolkit.ToolkitException
Construct a ToolkitException instance with the specified reason.
U
UNAVAILABLE_ELEMENT . Static variable in class sim.toolkit.ToolkitException
Constant: reason code for unavailable element in the handler buffer
updateBinary(short, byte[], short, short). Method in interface sim.access.SIMView
UPDATE BINARY command as defined in GSM 11.11 standard.This method updates the data bytes of the current transparent EF of the calling applet.
updateRecord(short, byte, short, byte[], short, short). Method in interface sim.access.SIMView
UPDATE RECORD command as defined in GSM 11.11 standard.This method updates the data bytes of the current linear fixed/cyclic EF of the calling applet.
V
ViewHandler(byte[], short, short). Constructor for class sim.toolkit.ViewHandler
Build a new ViewHandler object.
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)
Index of all Fields and Methods 93