GSM 03.19

ETSI SMG #28 8- 12February, 1999 Milano, Italy
Tdoc P-99-182
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
European Telecommunications Standards Institute
GSM 03.19 V1.0.0 (1999-01)
Reference
DTS/SMG-090219N (2100001f.PDF)
Keywords
Digital cellular telecommunications system, Global System for Mobile communications (GSM)
ETSI Secretariat
Postal address
F-06921 Sophia Antipolis Cedex - FRANCE
Office address
650 Route des Lucioles - Sophia Antipolis Valbonne - FRANCE Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16
Siret N 348 623 562 00017 - NAF 742 C Association but non lucratif enregistre la Sous-Prfecture de Grasse (06) N 7803/88
Internet
secretariat@etsi.fr http://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)
Contents
Intellectual Property Rights ............................................................................................................................... 4 Foreword............................................................................................................................................................ 4 1 2
2.1
Scope ....................................................................................................................................................... 5 References ............................................................................................................................................... 5

Normative references .........................................................................................................................................5
3
3.1 3.2
Definitions and abbreviations.................................................................................................................. 6

Definitions..........................................................................................................................................................6 Abbreviations .....................................................................................................................................................6
4
4.1 4.2
Description .............................................................................................................................................. 7
GSM Java Card Architecture .............................................................................................................................7 Java Card Selection Mechanism.........................................................................................................................8
5
5.1 5.2 5.3 5.4
GSM framework...................................................................................................................................... 8
Overview............................................................................................................................................................8 GSM file data access ..........................................................................................................................................8 Access control ....................................................................................................................................................8 GSM low Level API...........................................................................................................................................8
6
6.1 6.2 6.3 6.4 6.5
SIM Toolkit framework........................................................................................................................... 9

Overview............................................................................................................................................................9 Applet Triggering...............................................................................................................................................9 Registration ......................................................................................................................................................11 Proactive command handling ...........................................................................................................................11 Envelope response handling.............................................................................................................................12
7
7.1 7.2
SIM Toolkit applet ................................................................................................................................ 12

Applet Loading.................................................................................................................................................12 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)
Intellectual Property Rights

IPRs essential or potentially essential to the present document may have been declared to ETSI. The information pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found in ETR 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in respect of ETSI standards", which is available free of charge from the ETSI Secretariat. Latest updates are available on the ETSI Web server (http://www.etsi.fr/ipr). Pursuant to the ETSI Interim IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee can be given as to the existence of other IPRs not referenced in ETR 314 (or the updates on http://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.
Foreword
This draft ETSI Technical Specification has been produced by Special Mobile Group (SMG) of the European Telecommunications Standards Institute (ETSI). In analogy with CCITT Recommendations I.130, the first stage of the following three level structure is used to describe the telecommunications services as provided by European public telecommunications operators: Stage 1 Stage 2 Stage 3 is an overall service description, from the service subscriber's and user's standpoint; identifies the functional capabilities and information flows needed to support the service described in stage 1; and defines the signalling system protocols and switching functions needed to implement the service described in stage 1.
This TS details the stage 2 aspects (functional capabilities) for the support of a Subscriber Identity Module Application Programming 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 release date 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)
Scope
This ETSI Technical Specification defines the stage two description of the Subscriber Identity Module Application Programming 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 Java Card 2.1 API specification [6]. This TS includes information applicable to network operators, service providers and SIM, server and database manufacturers.
References
a) specific versions of publications (identified by date of publication, edition number, version number, etc.), in which 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 version identity); or c) all versions subsequent to and including the identified version (identified by "onwards" following the version identity); or d) publications without mention of a specific version, in which case the latest version applies.
References may be made to:
A non-specific reference to an ETS shall also be taken to refer to later versions published as an EN with the same number.
2.1
[1] [2] [3]
Normative references
GSM 01.04 (ETR 350): Digital cellular telecommunications system (Phase 2+); Abbreviations and acronyms. GSM 11.11 (ETS 300 977): Digital cellular telecommunications system (Phase 2+); Specification of the Subscriber Identity Module - Mobile Equipment (SIM - ME) interface. GSM 11.14 Digital cellular telecommunication system (Phase 2+, Release 97); Specification of the SIM Application Toolkit for the Subscriber Identity Module - Mobile Equipment (SIM - ME) interface. GSM 03.48 "Digital cellular telecommunications system (Phase 2+); Security Mechanisms for the SIM application toolkit; Stage 2" ISO/IEC 7816-3 (1997) " Identification cards - Integrated circuit(s) cards with contacts, Part 3: Electronic signals and transmission protocols" GSM 02.19 " Digital cellular telecommunications system (Phase 2+); Subscriber Identity Module Application Programming Interface (SIM API); Service description; Stage 1" SUN Java Card Specification "Java Card 2.1 API Specification " SUN Java Card Specification "Java Card 2.1 Runtime Environment Specification" SUN Java Card Specification "Java Card 2.1 VM Architecture Specification"
[4] [5] [6] [7] [8] [9]
SUN Java Card Specifications can be downloaded at http://java.sun.com/products/javacard
GSM 03.19 V1.0.0 (1999-01)
3
3.1
Definitions and abbreviations

Definitions
For 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 Card virtual 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 defines instance and class variables and methods. Framework: A framework defines a set of Application Programming Interface (API) classes for developing applications 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 and containing 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 and loading). 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
Abbreviations
For the purposes of this TS the following abbreviations apply: AC Application Code APDU Application Protocol Data Unit API Application Programming Interface CAD Card Acceptance Device FFS For Further Study IFD Interface Device JCRE Java Card Run Time Environment JVM Java Virtual Machine ME Mobile Equipment MS Mobile Station SIM Subscriber Identity Module SE Sending Entity SMS-CB Short Message Service Cell Broadcast SMS-PP Short Message Service Point to Point USSD Unstructured Supplementary Services Data VM Virtual Machine Further GSM related abbreviations are given in GSM 01.04 [1].
GSM 03.19 V1.0.0 (1999-01)
Description
This document describes an API for the GSM SIM. This API allows application programmers access to the functions and data described in GSM 11.11 [2] and GSM 11.14 [3], such that SIM based services can be developed and loaded onto 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 Architecture

Applet n Applet 1
Applet Triggering
The over all architecture of the SIM Toolkit API based on Java Card 2.1 is:
Toolkit GSM
JCRE
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 proactive commands. The Applet Triggering based on the information provided by that layer will trigger the corresponding Applet. 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 to select 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 lower layer (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 )
Toolkit Applet 1
processToolkit
Applet ..
processToolkit
Applet n
processToolkit
GSM
select process
select process
select process
JCRE
Figure 2: Toolkit applet entry points
GSM 03.19 V1.0.0 (1999-01)
4.2
Java Card Selection Mechanism
The Java Card selection mechanism is defined in the Java Card Runtime Environment Specification [8].
5
5.1
GSM framework
Overview
The GSM Application is the default application, it owns the GSM files/data, handles all the GSM APDUs and passes all Toolkit 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
select
GSM file data access

Select a file without changing the current file of any other applet or of the subscriber session. At the beginning of an entry point of an applet, the current file is the MF. This method returns the selected file information; Read the file status information of the current DF; Read data bytes of the transparent EF currently selected by the applet; 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 a record; Modify data bytes of the transparent EF currently selected by the applet. The applet shall send the corresponding refresh ; Modify data bytes of the linear fixed or cyclic EF currently selected by the applet. The current record pointer of other applets / subscriber shall not be changed in case of linear fixed EF but the record pointer of a cyclic EF shall be changed for all other applets / subscriber to the record number 1. This method allows updating part of a record. The applet shall send the corresponding refresh ; 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 the value of the last updated record of the cyclic EF currently selected. It becomes than record number 1 for every other applet and subscriber session. This method returns the increased value. The applet shall send the corresponding refresh; Rehabilitate the EF currently selected by the applet with effect for all other applets / subscriber. The applet shall send the corresponding refresh; Invalidate the EF currently selected by the applet with effect for all other applets / subscriber. The applet shall send the corresponding refresh
The following methods shall be offered by the API to card applets, to allow access to the GSM data:
status readBinary readRecord
updateBinary updateRecord
seek increase
rehabilitate invalidate
These methods are described in the sim.access.SIMView interface in Annex A.
5.3
[FFS]
Access control
The Access Control privileges of the applet are granted during installation according to the level of trust.
5.4
GSM low Level API
[FFS. This API allows the implementation of the GSM application]
GSM 03.19 V1.0.0 (1999-01)
6
6.1
SIM Toolkit framework

Overview
The SIM API shall consist of APIs for GSM 11.14 [3] (pro-active functions) and GSM 11.11 [2] (transport functions).
Toolkit Applet 1
Applet 2
Proactive commands
Toolkit Applet 3
Applet n
sim.access package sim.toolkit package
Install Uninstall
(see NOTE 1)
Activation
P/C responses
File access
Toolkit Framework Applet triggering Proactive Command handler Applet install/uninstall

Security
Applet security manager
APDU e.g. Envelopes
Proactive polling, 91XX, Fetch, Proactive commands, Terminal Response
File access
GSM Framework
NOTE 1: The install / uninstall process is defined in GSM xx.yy [ ]
Files
APDU JCRE
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 of course, they may still be stored in elementary fields, but classes will access these data as part of the objects within those classes.
6.2
Applet Triggering
The 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. Menu Selected
APDU
Applet Triggering
SMS Received Terminal Profile ...
10
GSM 03.19 V1.0.0 (1999-01)
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 correct Envelope shall not result in an error status word in case of a failure of an applet. The only application as seen by the ME is 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 will handle 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 the applet 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 if registered. EVENT_MENU_SELECTION, EVENT_MENU_SELECTION_HELP_REQUEST A toolkit applet might be activated upon selection in the MEs menu by the user, or request help on this specific menu. In order to allow the user to choose in a menu, the Toolkit Framework shall have previously issued a SET UP MENU proactive command. When an application which could be activated by menu is loaded into the SIM, the Toolkit 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 Update Record 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 message is send ; - unformatted or using an applet specific protocol the SIM toolkit framework will pass this data to a specific applet 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 using the envelope command. E.g. the application may then read the message and extract a meaningful piece of information 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 corresponding Envelope command. [The order in which the applets are triggered is for further study.]
11
GSM 03.19 V1.0.0 (1999-01)
In order to allow the applet to be triggered by these events, the Toolkit Framework shall have previously issued a SET UP EVENT LIST proactive command. When an application which could be activated by these events is loaded 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 register to 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 proactive commands 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 associated to the event using the methods provided by the sim.toolkit.ViewHandler.EnvelopeHandler class.
6.3
Registration
During it's installation the applet shall register to the JCRE and the Toolkit framework so that it can be triggered by both selection mechanisms. The applet will have to call a registerToolkit() method to get a reference to it's registry and then to explicitly register to each event it requires. The applet can change the events to which it is registered during its life cycle. The applet will automatically register to some event e.g. EVENT_MENU_SELECTION by calling the corresponding method e.g. createMenuEntry. The API is described in the sim.toolkit.Registry class in Annex A.
6.4
Proactive command handling
The SIM application toolkit protocol (i.e. 91xx, Fetch, Terminal Response) is handled by the Toolkit framework, the applet shall not handle those events. The Toolkit Framework shall provide a reference of the sim.toolkit.ViewHandler.EditHandler.ProactiveHandler to the applet 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 the response. The Toolkit Framework will then return in the applet just after the send() method. It shall then provide to the Applet the sim.toolkit.ViewHandler.ProactiveResponseHandler, so that the applet can analyse the response.
12
GSM 03.19 V1.0.0 (1999-01)
6.5
Envelope response handling
To allow an applet to answer to some specific events (e.g. EVENT_CALL_CONTROL_BY_SIM) the Toolkit Framework 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 can continue it's processing (e.g. prepare a proactive command) the Toolkit Framework will return the response APDU defined by the applet (i.e. 9F xx or 9E xx).
7
7.1
SIM Toolkit applet

Applet Loading
The SIM API card shall be compliant to the Java Card 2.1 VM Architecture Specification [9] and to the Annex B to guarantee interoperability at byte code Level. The applet loading mechanism, protocol and applet life cycle are defined in GSM xx.yy[]
7.2
Object Sharing
The sharing mechanism defined in Java Card 2.1 API Specification [7] and Java Card 2.1 Runtime Environment Specification [8] shall be used by the applet to share data.
13
GSM 03.19 V1.0.0 (1999-01)
Annex A (normative): Java Card SIM API
Document Acrobat
14
GSM 03.19 V1.0.0 (1999-01)
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]
15
GSM 03.19 V1.0.0 (1999-01)
Annex C (informative): toolkit applet example

/** * Example Applet */ import import import import import import sim.toolkit.*; sim.access.*; javacard.framework.APDU; javacard.framework.Util; javacard.framework.ISOException; javacard.framework.ISO;
public class MyToolkitApplet extends ToolkitApplet implements ToolkitConstants{ public public public public public public static static static static static static final final final final final final byte byte byte byte byte byte MY_INSTRUCTION = (byte)0x46; DEVICEID_ME = (byte) 0x82; DEVICEID_DISPLAY = (byte) 0x02; DCS8 = (byte)0xF4; SMS_TPDU = (byte)0x8D; 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) {
16
GSM 03.19 V1.0.0 (1999-01)
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); } } }
17
GSM 03.19 V1.0.0 (1999-01)
History
Document history
Date Version Comment
December 1998 January 1999 January 1999 January 1999 January 1999 January 1999
0.1.0 0.1.1 0.2.0 0.2.1 0.2.2 1.0.0
Initial draft based on the outcome of JCF SIM API Task Force (December 98). Discussion document during the seventh SMG9 SIM API meeting (January 99) Outcome of the seventh SMG9 SIM API meeting (January 99) Outcome of the SIM API splinter group during SMG9#17 (January 99) Outcome of SMG9#17 (January 99) Submission to SMG #28 for info. (no technical changes compared to V0.2.2)
Rapporteur: Christian Dietrich, (christian.dietrich@slb.com) The ETSI committee SMG9 is responsible for developing this specification. An email list has been set up for discussion about this document. To subscribe to the list, send a message to listserv@list.etsi.fr with a single line in the body of the message: 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/ or http://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
Package Index
Other Packages
package sim.access package sim.toolkit
Package Index
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
package sim.access
Interface Index
SIMView
Class Index
SIMSystem
Exception Index
SIMViewException
package sim.access
Class sim.access.SIMSystem
java.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 is needed. 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
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
Interface sim.access.SIMView
public 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 of the existing file system. All the methods are based on the commands of the GSM11.11 specification. This interface shall be implemented by the Toolkit framework. The main idea is to avoid an APDU based communication between SIM Toolkit applets and the GSM application. This interface is not intended for the activation 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
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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) Interface sim.access.SIMView 7
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) SELECT command as defined in GSM 11.11 standard. This SELECT method allows to update the current file without handling the Select Response By 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 the calling 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) 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 the current DF of the applet according to the file search method described in GSM 11.11 specification. The current DF or current EF and the current record pointer of the calling applet 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 is thrown. If fci buffer is too small to receive the whole response, 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 fid is the File Identifier of the file to be selected. Returns: Interface sim.access.SIMView 9
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) length of the data which have been written in the fci buffer (cannot be greater than fci buffer size) 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 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 the current DF of the applet according to the file search method described in GSM 11.11 specification. The current DF or current EF 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) of the calling applet.
Parameters: fci - is the reference to the target byte array for FCI (File Control Information) of current DF (or MF), coding according to GSM 11.11. If fci is null, no response is prepared and no exception is thrown. If fci buffer is too small to receive the whole response, 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 than fci buffer size)
10
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 Interface sim.access.SIMView 11
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 calling applet. 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.
12
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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, SIMViewException byte patt[],
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 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. The response 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 3 bytes. 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 the record size, an "OUT_OF_BUFFER_BOUNDARIES" exception is thrown. If resp buffer is bigger than the record size, the resp buffer is filled with the record value and 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
14
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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
15
Class sim.access.SIMViewException
java.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 of the SIMView interface in case of error. Table SIMViewException reason NO_EF_SELECTED FILE_INCONSISTENT AC_NOT_FULFILLED FILE_NOT_FOUND INTERNAL_ERROR CURRENT_EF_INVALIDATED Description No EF selected before calling the method File inconsistent with the method Access condition level not fulfilled File not found Internal error Current EF invalidated
INVALIDATION_STATUS_CONTRADICTION Method in contradiction with the invalidation status OUT_OF_FILE_BOUNDARIES OUT_OF_RECORD_BOUNDARIES OUT_OF_BUFFER_BOUNDARIES RECORD_NUMBER_NOT_AVAILABLE INVALID_MODE PATTERN_NOT_FOUND PATTERN_SIZE_INCONSISTENT MAX_VALUE_REACHED Out of the transparent file boundaries Out of the record boundaries Out of the buffer boundaries (response or data) Record number not available Invalid mode for seek command or record access Pattern not found for seek command Pattern size greater than record size Max value reached for increase command
See Also: SIMView
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
17
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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
18
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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-use the JCRE instance of this class.
19
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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
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.ViewHandler
java.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 a Terminal 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.
22
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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
byte occurrence) throws
public byte findTLV(byte tag, ToolkitException
Look for a TLV element in the TLV structure (handler buffer). This search method is Comprehension Required 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
23
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for the system-defined singleton classes. getValueLength
public short getValueLength() throws ToolkitException
Get the length of the value field for the last TLV element which has been found in the buffer.
Returns: length of the value field Throws:ToolkitException HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for the system-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 the system-defined singleton classes. UNAVAILABLE_ELEMENT in case of unavailable TLV element
copyValue
public short copyValue(short valueOffset, ToolkitException byte dstBuffer[],
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 Class sim.toolkit.ViewHandler 24
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 singleton 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 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 the system-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 Class sim.toolkit.ViewHandler 25
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) no TLV element is found, the return value equals dstOffset. This search method is Comprehension Required flag independent. To find another occurence or to copy only a part of 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 the system-defined singleton classes. UNAVAILABLE_ELEMENT in case of unavailable TLV element
findAndCopyValue
public short findAndCopyValue(byte tag, ToolkitException byte occurenc
Look for the first occurence of a TLV element and copy its value into a destination buffer. If no TLV element is found, the return value equals dstOffset. This search method is Comprehension Required flag independent. To find another occurence or to copy only a part of the TLV, the methods findTLV() 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 Class sim.toolkit.ViewHandler 26
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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. If no TLV element is found, the return value equals -1. This search method is Comprehension Required 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 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 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 the system-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 no TLV element is found, the return value equals -1. This search method is Comprehension Required 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 Class sim.toolkit.ViewHandler 27
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 the system-defined singleton classes. UNAVAILABLE_ELEMENT in case of unavailable TLV element
28
Class sim.toolkit.EnvelopeHandler
java.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 used by the Toolkit applet in order to have access to the current Envelope information. No constructor is available for the Toolkit applet. The EnvelopeHandler class is a singleton class and the only way to get a EnvelopeHandler reference is through the getTheHandler() static method. Example of use in a standard Toolkit applet:
private static final byte MY_TAG = (byte)0x54; private EnvelopeHandler theEnv; private byte[] data; data = new byte[32]; void processToolkit(byte event) throws ToolkitException { // get the EnvelopeHandler system instance theEnv = EnvelopeHandler.getTheHandler(); if (theEnv.findTLV(MY_TAG, (byte)1) != NOT_FOUND) { if (theEnv.getValueByte((short)0) == (byte)1) { // copy element part into data buffer theEnv.copyValue((short)1, data, (short)0, (short)(theEnv.getValueLength() } } } // constant // reference declaration // build object
// look for MY_TAG element // check first element byte
- 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 current Envelope data field. getTheHandler() Class sim.toolkit.EnvelopeHandler 29
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 method will 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 can be recovered by using the getValueByte method in Handler class. Throws:ToolkitException HANDLER_NOT_AVAILABLE if the handler is busy. Class sim.toolkit.EnvelopeHandler 30
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) UNAVAILABLE_ELEMENT in case of unavailable TPDU TLV element or if the TPOA 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. Should be used with Envelope SMS-PP Data Download.
Returns: TPUD offset in the first TPDU TLV element if TPUD exists. The TPUD length can be recovered 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 TPUD field does not exist
getItemIdentifier
public byte getItemIdentifier() throws ToolkitException
Return the item identifier byte value from the first Item Identifier TLV element in the current Envelope data field.
Returns: item identifier Throws:ToolkitException HANDLER_NOT_AVAILABLE if the handler is busy. UNAVAILABLE_ELEMENT in case of unavailable TLV element
Class sim.toolkit.EnvelopeHandler
31
Class sim.toolkit.ProactiveResponseHandler
java.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 is available for the Toolkit applet. The ProactiveResponseHandler class is a singleton class and the only way to get 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 the current response data field. copyTextString(byte[], short) Copy the text string value from the first Text String TLV element of the current response data field. getAdditionalInformationLength() Class sim.toolkit.ProactiveResponseHandler 32
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) Return the length of the additional information field from the first Result TLV element of the current response data field. getDurationInterval() Return the duration interval value from the first Duration TLV element of the current response data field. getDurationUnit() Return the duration unit byte from the first Duration TLV element of the current response data 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 current response data field. getTextStringCodingScheme() Return the data coding scheme byte from the first Text String TLV element of the current response data field. getTextStringLength() Return the text string length value from the first Text String TLV element of the current response 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 to this method will always return the same object reference.
getGeneralResult
public byte getGeneralResult() throws ToolkitException
33
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 TLV element 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 the current 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 Class sim.toolkit.ProactiveResponseHandler 34
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) getItemIdentifier
public byte getItemIdentifier() throws ToolkitException
Return the item identifier byte value from the first Item Identifier TLV element of the current response 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 current response 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 response data 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 Class sim.toolkit.ProactiveResponseHandler 35
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 the current 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 response data 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
36
Class sim.toolkit.EditHandler
java.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
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 the system-defined singleton classes.
appendArray
public void appendArray(byte buffer[], ToolkitException short offset,
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-defined singleton classes. appendTLV
public void appendTLV(byte tag,
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 the system-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 the system-defined singleton classes.
appendTLV
public void appendTLV(byte tag, ToolkitException byte value1,
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: Class sim.toolkit.EditHandler 39
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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-defined singleton 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 the system-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 Class sim.toolkit.EditHandler 40
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) system-defined singleton classes.
41
Class sim.toolkit.EnvelopeResponseHandler
java.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. No constructor is available for the Toolkit applet. The EnvelopeResponseHandler class is a singleton class and the 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 to this method will always return the same object reference.
Returns:
42
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 Envelope Call Control by SIM or MO Short Message Control by SIM. The tag value is to be used 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.
43
Class sim.toolkit.ProactiveHandler
java.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...). Other methods are dedicated to the Release 97 of the GSM 11.14 (version 6.2.0). The ProactiveHandler class is a singleton 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 reference of 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.
44
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 method will always return the same object reference.
init
public void init(byte type, ToolkitException byte qualifier, byt
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. The Comprehension Required flags are set.
Parameters: type - the command type qualifier - the command qualifier Class sim.toolkit.ProactiveHandler 45
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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. The Comprehension 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
46
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) initGetInkey
public byte initGetInkey(byte qualifier, ToolkitException byte dcs,
Build a Get Inkey Proactive command without sending the command. The Comprehension Required flags 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. The Comprehension 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 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 flags are all set to 1. The following command parameters (i.e. TLVs) may be appended to the command before sending 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
48
Class sim.toolkit.MEProfile
java.lang.Object | +----sim.toolkit.MEProfile
public final class MEProfile extends Object The MEProfile class contains methods to question the handset profile, regarding the SIM Application Toolkit and supposing that this profile has been set by the Terminal Profile APDU command. The following table gives the index value according to the facility to check. Only Release 97 facilities of the GSM 11.14 are listed (version 6.2.0). This class contains only static methods, no instance of this class is necessary. Facility Profile download SMS-PP data download Cell Broadcast data download Menu selection New status word for SIM data download error Command result Call Control by SIM Cell identity included in Call Control by SIM MO short message control by SIM Handling of the alpha identifier UCS2 Entry supported UCS2 Display supported Proactive SIM: Display Text Proactive SIM: Get Inkey Proactive SIM: Get Input Proactive SIM: More Time Proactive SIM: Play Tone Proactive SIM: Poll Interval Proactive SIM: Polling Off Proactive SIM: Refresh Proactive SIM: Select Item Index 0 1 2 3 4 8 9 10 11 12 13 14 16 17 18 19 20 21 22 23 24
49
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) Proactive SIM: Send Short Message Proactive SIM: Send SS Proactive SIM: Send USSD Proactive SIM: Set Up Call Proactive SIM: Set Up Menu Proactive SIM: Provide Local Information 25 26 27 28 29 30
Proactive SIM: Provide Local Information (NMR) 31 Proactive SIM: Set Up Event List Event: MT call Event: Call connected Event: Call disconnected Event: Location status Event: User activity Event: Idle screen available 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; }
32 33 34 35 36 37 38
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 Class sim.toolkit.MEProfile 50
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 always false, but no exception is thrown. The method checks all the facilities corresponding to bits set to 1 in the 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
51
Class sim.toolkit.Registry
java.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. Each toolkit applet should ask the system to build an instance of this class through the registerToolkit() 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) { //... } }
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 of formatted short message. setEvent(byte) Set an event in the Registry. setEventList(byte[], short, short) Set an event list in the Registry.
Methods
setEvent 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 limited event like Call Control)
setEventList
public void setEventList(byte eventlist[], ToolkitException short offset,
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 like Call 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.
54
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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[], ToolkitException short off
Register the SMS-PP Data Download TAR. The TAR (Toolkit Application Reference) will be used to identify the target applet in case of formatted short message. By calling this method the applet automatically registers to the event EVENT_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
55
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) Throws:ToolkitException ENTRY_NOT_FOUND if the menu entry does not exist for this applet
createMenuEntry
public byte createMenuEntry(byte menuEntry[], ToolkitException short off
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 the EVENT_MENU_SELECTION_HELP_REQUEST event. The applet automatically registers to the EVENT_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 the registration 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
56
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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
57
Class sim.toolkit.ToolkitApplet
java.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 by any 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 Java Card compliant smart card. A toolkit applet can be triggered by the following events : Event EVENT_PROFILE_DOWNLOAD EVENT_FORMATTED_SMS_PP EVENT_UNFORMATTED_SMS_PP EVENT_UNFORMATTED_SMS_CB EVENT_MENU_SELECTION EVENT_MENU_SELECTION_HELP_REQUEST EVENT_CALL_CONTROL_BY_SIM EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM EVENT_EVENT_DOWNLOAD_MT_CALL EVENT_EVENT_DOWNLOAD_CALL_CONNECTED EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED EVENT_EVENT_DOWNLOAD_LOCATION_STATUS EVENT_EVENT_DOWNLOAD_USER_ACTIVITY Description Terminal Profile command reception 03.48 formatted envelope SMS-PP Data Download reception Unformatted SMS-PP Data Download reception Unformatted Cell Broadcast Data Download command reception Envelope Menu Selection command reception Envelope Menu Selection Help Request command reception Envelope Call Control by SIM command reception Envelope MO Short Message Control by SIM command reception Envelope Event Download - MT call Envelope Event Download - Call connected Envelope Event Download - Call disconnected Envelope Event Download - Location status Envelope Event Download - User activity
EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE Envelope Event Download - Idle screen available Class sim.toolkit.ToolkitApplet 58
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) EVENT_CARD_RESET EVENT_STATUS_COMMAND EVENT_UNRECOGNIZED_ENVELOPE EVENT_PROPRIETARY_EVENT 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(); } } }
Card electrical reset event Status APDU command event Unrecognized Envelope command reception Reserved for proprietary events
See Also: Class sim.toolkit.ToolkitApplet 59
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 current Toolkit event, as indicated in the event table. registerToolkit() This method is used by the Toolkit applet to register this applet instance with the Toolkit framework 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 Toolkit framework and to get the reference of the associated Registry object. At least on event shall be 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
60
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) This method is the standard entry point of a Toolkit applet and shall manage the current Toolkit event, as indicated in the event table.
Parameters: event - the type of event to be processed Throws:ToolkitException in case of error
61
Interface sim.toolkit.ToolkitConstants
public 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
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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
63
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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
64
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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
65
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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
66
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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
67
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 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
69
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 Interface sim.toolkit.ToolkitConstants 70
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 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
72
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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
73
Class sim.toolkit.ToolkitException
java.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 in case of problems. Table ToolkitException reason BUFFER_OVERFLOW HANDLER_NOT_AVAILABLE PROACTIVE_NOT_SUPPORTED UNAVAILABLE_ELEMENT INVALID_TAR ENTRY_NOT_FOUND REGISTRY_ERROR EVENT_NOT_SUPPORTED Description Data larger than storage buffer Handler cannot be accessed (e.g. busy) Proactive SIM not supported by ME No available element in the handler buffer TAR already used Menu entry not found Error in the registry information 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
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 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 resources use 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.
76
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) Parameters: reason - the reason for the exception. Throws:ToolkitException always
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
78
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 class sim.toolkit.ProactiveResponseHandler Copy a part of the additional information field from the first Result TLV element of the current 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 response data 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.
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 interface sim.toolkit.ToolkitConstants Event Constant: Event Download event - Call connected type EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED. Static variable in interface sim.toolkit.ToolkitConstants Event Constant: Event Download event - Call disconnected type EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE. Static variable in interface sim.toolkit.ToolkitConstants Event Constant: Event Download event - Idle screen available type EVENT_EVENT_DOWNLOAD_LOCATION_STATUS. Static variable in interface sim.toolkit.ToolkitConstants Event Constant: Event Download event - Location status type EVENT_EVENT_DOWNLOAD_MT_CALL. Static variable in interface sim.toolkit.ToolkitConstants Event Constant: Event Download event - MT call type EVENT_EVENT_DOWNLOAD_USER_ACTIVITY. Static variable in interface sim.toolkit.ToolkitConstants
80
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 interface sim.toolkit.ToolkitConstants Event Constant: Menu Selection Help Request event EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM. Static variable in interface sim.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
Index of all Fields and Methods 81
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 class sim.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
82
G
getAdditionalInformationLength(). Method in class sim.toolkit. ProactiveResponseHandler Return the length of the additional information field from the first Result TLV element of the current response data field. getDurationInterval(). Method in class sim.toolkit. ProactiveResponseHandler Return the duration interval value from the first Duration TLV element of the current response data field. getDurationUnit(). Method in class sim.toolkit. ProactiveResponseHandler Return the duration unit byte from the first Duration TLV element of the current response data 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 current Envelope data field. getItemIdentifier(). Method in class sim.toolkit. ProactiveResponseHandler Return the item identifier byte value from the first Item Identifier TLV element of the current response 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 current response data field. getTextStringLength(). Method in class sim.toolkit. ProactiveResponseHandler Return the text string length value from the first Text String TLV element of the current response data field. getTheHandler(). Static method in class sim.toolkit. EnvelopeHandler
83
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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. Index of all Fields and Methods 84
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 class sim.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 class sim.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
Index of all Fields and Methods 85
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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
86
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 interface sim.toolkit.ToolkitConstants Index of all Fields and Methods 87
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 current Toolkit 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.
88
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 Toolkit framework 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). Index of all Fields and Methods 89
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 Response By 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 of formatted 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 the calling 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 Index of all Fields and Methods 90
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) TAG_CALL_CONTROL_REQUESTED_ACTION. Static variable in interface sim.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 interface sim.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
91
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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 interface sim.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 interface sim.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
92
GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm) 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.
93

GSM 03.19

Uploaded by

Copyright:

Available Formats

GSM 03.19

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

GSM 03.19

Uploaded by

Copyright:

Available Formats

ETSI SMG #28 8- 12February, 1999 Milano, Italy

GSM 03.19 V1.0.0 (1999-01)

GLOBAL SYSTEM FOR MOBILE COMMUNICATIONS

European Telecommunications Standards Institute

GSM 03.19 V1.0.0 (1999-01)

GSM 03.19 V1.0.0 (1999-01)

Definitions and abbreviations.................................................................................................................. 6

SIM Toolkit framework........................................................................................................................... 9

SIM Toolkit applet ................................................................................................................................ 12

GSM 03.19 V1.0.0 (1999-01)

Intellectual Property Rights

GSM 03.19 V1.0.0 (1999-01)

References may be made to:

[4] [5] [6] [7] [8] [9]

SUN Java Card Specifications can be downloaded at http://java.sun.com/products/javacard

GSM 03.19 V1.0.0 (1999-01)

Definitions and abbreviations

GSM 03.19 V1.0.0 (1999-01)

GSM Java Card Architecture

Figure 2: Toolkit applet entry points

GSM 03.19 V1.0.0 (1999-01)

Java Card Selection Mechanism

GSM file data access

status readBinary readRecord

These methods are described in the sim.access.SIMView interface in Annex A.

GSM low Level API

[FFS. This API allows the implementation of the GSM application]

GSM 03.19 V1.0.0 (1999-01)

SIM Toolkit framework

Toolkit Framework Applet triggering Proactive Command handler Applet install/uninstall

Applet security manager

APDU e.g. Envelopes

Proactive polling, 91XX, Fetch, Proactive commands, Terminal Response

SMS Received Terminal Profile ...

GSM 03.19 V1.0.0 (1999-01)

GSM 03.19 V1.0.0 (1999-01)

Proactive command handling

GSM 03.19 V1.0.0 (1999-01)

Envelope response handling

SIM Toolkit applet

GSM 03.19 V1.0.0 (1999-01)

Annex A (normative): Java Card SIM API

GSM 03.19 V1.0.0 (1999-01)

Annex B (normative): Java Card SIM API identifiers

GSM 03.19 V1.0.0 (1999-01)

Annex C (informative): toolkit applet example

GSM 03.19 V1.0.0 (1999-01)

GSM 03.19 V1.0.0 (1999-01)

0.1.0 0.1.1 0.2.0 0.2.1 0.2.2 1.0.0

GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)

GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)

GSM 03.19 v1.0.0 Annex A: SIM API for Java Card(tm)

Return a reference to the GSM interface

Returns: a reference to a class which implements the GSMView interface

See Also: Shareable, SIMViewException

Constant: File identifier of the MF FID_DF_TELECOM

Constant: File identifier of the DF TELECOM FID_DF_GSM

Constant: File identifier of the DF GSM FID_DF_DCS

Constant: File identifier of the DF DCS1800 MODE_NEXT

Constant: Record access mode 'next' MODE_PREVIOUS