GSM 03.19

ETSI SMG #28 Tdoc P-99-1828- 12February, 1999Milano, Italy

European Telecommunications Standards Institute

GSM 03.19 V1.0.0 (1999-01)Technical Specification

Digital cellular telecommunications system (Phase 2+);Subscriber Identity Module Application Programming Interface

(SIM API);SIM API for Java Card™ ;

Stage 2

GLOBAL SYSTEM FOR MOBILE COMMUNICATIONS

R

GSM 03.19 V1.0.0 (1999-01)2

ReferenceDTS/SMG-090219N (2100001f.PDF)

KeywordsDigital cellular telecommunications system,

Global System for Mobile communications (GSM)

ETSI Secretariat

Postal addressF-06921 Sophia Antipolis Cedex - FRANCE

Office address650 Route des Lucioles - Sophia Antipolis

Valbonne - FRANCETel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16

Siret N° 348 623 562 00017 - NAF 742 CAssociation à but non lucratif enregistrée à laSous-Préfecture de Grasse (06) N° 7803/88

[email protected]://www.etsi.fr

http://www.etsi.org

Copyright Notification

No part may be reproduced except as authorized by written permission.The copyright and the foregoing restriction extend to reproduction in all media.

© European Telecommunications Standards Institute 1998.All rights reserved.

GSM 03.19 V1.0.0 (1999-01)3

Contents

Intellectual Property Rights ............................................................................................................................... 4

Foreword............................................................................................................................................................ 4

1 Scope ....................................................................................................................................................... 5

2 References ............................................................................................................................................... 52.1 Normative references .........................................................................................................................................5

3 Definitions and abbreviations.................................................................................................................. 63.1 Definitions..........................................................................................................................................................63.2 Abbreviations .....................................................................................................................................................6

4 Description .............................................................................................................................................. 74.1 GSM Java Card Architecture .............................................................................................................................74.2 Java Card Selection Mechanism.........................................................................................................................8

5 GSM framework...................................................................................................................................... 85.1 Overview............................................................................................................................................................85.2 GSM file data access..........................................................................................................................................85.3 Access control ....................................................................................................................................................85.4 GSM low Level API...........................................................................................................................................8

6 SIM Toolkit framework........................................................................................................................... 96.1 Overview............................................................................................................................................................96.2 Applet Triggering...............................................................................................................................................96.3 Registration ......................................................................................................................................................116.4 Proactive command handling ...........................................................................................................................116.5 Envelope response handling.............................................................................................................................12

7 SIM Toolkit applet ................................................................................................................................ 127.1 Applet Loading.................................................................................................................................................127.2 Object Sharing..................................................................................................................................................12

Annex A (normative): Java Card SIM API ................................................................................................ 13

Annex B (normative): Java Card SIM API identifiers .............................................................................. 14

Annex C (informative): toolkit applet example .......................................................................................... 15

History ............................................................................................................................................................. 17

GSM 03.19 V1.0.0 (1999-01)4

Intellectual Property RightsIPRs essential or potentially essential to the present document may have been declared to ETSI. The informationpertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be foundin ETR 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in respect ofETSI standards", which is available free of charge from the ETSI Secretariat. Latest updates are available on the ETSIWeb server (http://www.etsi.fr/ipr).

Pursuant to the ETSI Interim IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. Noguarantee can be given as to the existence of other IPRs not referenced in ETR 314 (or the updates onhttp://www.etsi.fr/ipr) which are, or may be, or may become, essential to the present document.

Java and Java Card are trademarks of SUN Microsystems.

ForewordThis draft ETSI Technical Specification has been produced by Special Mobile Group (SMG) of the EuropeanTelecommunications Standards Institute (ETSI).

In analogy with CCITT Recommendations I.130, the first stage of the following three level structure is used to describethe telecommunications services as provided by European public telecommunications operators:

Stage 1 is an overall service description, from the service subscriber's and user's standpoint;

Stage 2 identifies the functional capabilities and information flows needed to support the service describedin stage 1; and

Stage 3 defines the signalling system protocols and switching functions needed to implement the servicedescribed in stage 1.

This TS details the stage 2 aspects (functional capabilities) for the support of a Subscriber Identity Module ApplicationProgramming Interface (SIM API)

The contents of this TS are subject to continuing work within SMG and may change following formal SMG approval.Should SMG modify the contents of this TS it will then be republished by ETSI with an identifying change of releasedate and an increase in version number as follows:

Version 5.x.y

where:

y the third digit is incremented when editorial only changes have been incorporated in the specification;

x the second digit is incremented for all other types of changes, i.e. technical enhancements, corrections,updates, etc.

GSM 03.19 V1.0.0 (1999-01)5

1 ScopeThis ETSI Technical Specification defines the stage two description of the Subscriber Identity Module ApplicationProgramming Interface (SIM API) internal to the SIM.

This stage two describes the functional capabilities and the information flow for the SIM API implemented on the JavaCard 2.1 API specification [6].

This TS includes information applicable to network operators, service providers and SIM, server and databasemanufacturers.

2 ReferencesReferences may be made to:

a) specific versions of publications (identified by date of publication, edition number, version number, etc.), inwhich case, subsequent revisions to the referenced document do not apply; or

b) all versions up to and including the identified version (identified by "up to and including" before the versionidentity); or

c) all versions subsequent to and including the identified version (identified by "onwards" following the versionidentity); or

d) publications without mention of a specific version, in which case the latest version applies.

A non-specific reference to an ETS shall also be taken to refer to later versions published as an EN with the samenumber.

2.1 Normative references[1] GSM 01.04 (ETR 350): “Digital cellular telecommunications system (Phase 2+); Abbreviations

and acronyms”.

[2] GSM 11.11 (ETS 300 977): “Digital cellular telecommunications system (Phase 2+); Specificationof the Subscriber Identity Module - Mobile Equipment (SIM - ME) interface”.

[3] GSM 11.14 “Digital cellular telecommunication system (Phase 2+, Release 97); Specification ofthe SIM Application Toolkit for the Subscriber Identity Module - Mobile Equipment (SIM - ME)interface”.

[4] GSM 03.48 "Digital cellular telecommunications system (Phase 2+); Security Mechanisms for theSIM application toolkit; Stage 2"

[5] ISO/IEC 7816-3 (1997) " Identification cards - Integrated circuit(s) cards with contacts, Part 3:Electronic signals and transmission protocols"

[6] GSM 02.19 " Digital cellular telecommunications system (Phase 2+); Subscriber Identity ModuleApplication Programming Interface (SIM API); Service description; Stage 1"

[7] SUN Java Card Specification "Java Card 2.1 API Specification "

[8] SUN Java Card Specification "Java Card 2.1 Runtime Environment Specification"

[9] SUN Java Card Specification "Java Card 2.1 VM Architecture Specification"

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

GSM 03.19 V1.0.0 (1999-01)6

3 Definitions and abbreviations

3.1 DefinitionsFor the purposes of this TS the following definitions apply:

Applet: An Applet is an application built up using a number of classes which will run under the control of the Java Cardvirtual machine. Applets designed for smart cards are sometimes referred to as Cardlets.

Bytecode: Machine independent code generated by a Java compiler and executed by the Java interpreter.

Class: The Class is a type that defines the implementation of a particular kind of object. A Class definition definesinstance and class variables and methods.

Framework: A framework defines a set of Application Programming Interface (API) classes for developingapplications and for providing system services to those applications.

GSM applet: The GSM application conforming to GSM 11.11. It might be a Java Card applet or native application.

Java: An object oriented programming language developed by Sun Microsystems designed to be platform independent.

Method: A Method is a piece of executable code that can be invoked, possibly passing it certain values as arguments.Every Method definition belongs to some class.

Object:The principal building block of object oriented programs. Each object is a programming unit consisting of data(variables) and functionality (methods)

Package: A group of classes. Packages are declared when writing a Java Card program

Proactive applet: Applet loaded onto the SIM card seen by the Mobile as being part of the SIM Toolkit application andcontaining only the code necessary to run the application. These applets might be downloaded over the radio interface.

Toolkit Framework: Part of the SIM card responsible for the handling of applications (including triggering andloading). It also contains the library for the proactive API.

Virtual Machine: The part of the Run-time environment responsible for interpreting the bytecode.

3.2 AbbreviationsFor the purposes of this TS the following abbreviations apply:

AC Application CodeAPDU Application Protocol Data UnitAPI Application Programming InterfaceCAD Card Acceptance DeviceFFS For Further StudyIFD Interface DeviceJCRE Java Card™ Run Time EnvironmentJVM Java Virtual MachineME Mobile EquipmentMS Mobile StationSIM Subscriber Identity ModuleSE Sending EntitySMS-CB Short Message Service – Cell BroadcastSMS-PP Short Message Service – Point to PointUSSD Unstructured Supplementary Services DataVM Virtual Machine

Further GSM related abbreviations are given in GSM 01.04 [1].

GSM 03.19 V1.0.0 (1999-01)7

4 DescriptionThis document describes an API for the GSM SIM. This API allows application programmers access to the functionsand data described in GSM 11.11 [2] and GSM 11.14 [3], such that SIM based services can be developed and loadedonto SIMs, quickly and, if necessarily, remotely, after the card has been issued.

This API is an extension to the Java Card 2.1 API [7] based on the Java Card 2.1 Runtime Environment [8].

4.1 GSM Java Card ArchitectureThe over all architecture of the SIM Toolkit API based on Java Card 2.1 is:

Applet n

…

Applet 1

JCRE

GSM

Applet Triggering

Toolkit

Figure 1: GSM Java Card architecture

GSM : this corresponds to the GSM application.

Toolkit : this handles the SIM Application Toolkit protocol, provides services to the applet to construct proactivecommands. The Applet Triggering based on the information provided by that layer will trigger the correspondingApplet.

Applet : Can be any kind of applet either using the GSM/toolkit facilities or just handling APDU.

Two selection mechanisms are available:

- JCRE : this handles all the applet as defined in Java Card 2.1 Runtime Environment Specification [8] it will be able toselect a any specific applet and send to it the corresponding APDU, the GSM application is the default applet.

- Applet Triggering : this is the GSM/toolkit method of selecting an applet according to the event appeared in the lowerlayer (GSM, Toolkit).

Applets loaded into a SIM Toolkit Java Card derives from either of the following classes:- javacard.framework.Applet- sim.toolkit.ToolkitApplet (which derives from javacard.framework.Applet)

Such an applet can handle two kinds entry points:- Java Card (i.e. process, select, deselect, install )- GSM/Toolkit activation events (i.e. processToolkit )

Applet n

processToolkit

select

process

Applet ..

processToolkit

select

process

Applet 1

processToolkit

select

process

JCRE

GSM

Toolkit

Figure 2: Toolkit applet entry points

GSM 03.19 V1.0.0 (1999-01)8

4.2 Java Card Selection MechanismThe Java Card selection mechanism is defined in the Java Card Runtime Environment Specification [8].

5 GSM framework

5.1 OverviewThe GSM Application is the default application, it owns the GSM files/data, handles all the GSM APDUs and passes allToolkit APDUs to the Toolkit framework.

The GSM framework is based on two packages:

- The GSM low level package [FFS];

- The sim.access package, which allows the GSM application to share data with the applets.

5.2 GSM file data accessThe following methods shall be offered by the API to card applets, to allow access to the GSM data:

select Select a file without changing the current file of any other applet or of the subscriber session. Atthe beginning of an entry point of an applet, the current file is the MF. This method returns theselected file information;

status Read the file status information of the current DF;readBinary Read data bytes of the transparent EF currently selected by the applet;readRecord Read data bytes of the linear fixed or cyclic EF currently selected by the applet without changing

the current record pointer of any other applet / subscriber. This method allows reading part of arecord;

updateBinary Modify data bytes of the transparent EF currently selected by the applet. The applet shall send thecorresponding refresh ;

updateRecord Modify data bytes of the linear fixed or cyclic EF currently selected by the applet. The currentrecord pointer of other applets / subscriber shall not be changed in case of linear fixed EF but therecord pointer of a cyclic EF shall be changed for all other applets / subscriber to the recordnumber 1. This method allows updating part of a record. The applet shall send the correspondingrefresh ;

seek Search a record of the linear fixed file currently selected by the applet starting with a given pattern.The current record pointer of any other applet or of the subscriber session shall not be changed;

increase Increase the value of the last updated record of the cyclic EF currently selected. It becomes thanrecord number 1 for every other applet and subscriber session. This method returns the increasedvalue. The applet shall send the corresponding refresh;

rehabilitate Rehabilitate the EF currently selected by the applet with effect for all other applets / subscriber.The applet shall send the corresponding refresh;

invalidate Invalidate the EF currently selected by the applet with effect for all other applets / subscriber. Theapplet shall send the corresponding refresh

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

5.3 Access controlThe Access Control privileges of the applet are granted during installation according to the level of trust.

[FFS]

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

GSM 03.19 V1.0.0 (1999-01)9

6 SIM Toolkit framework

6.1 OverviewThe SIM API shall consist of APIs for GSM 11.14 [3] (pro-active functions) and GSM 11.11 [2] (transport functions).

ToolkitApplet 1 Applet 2

ToolkitApplet 3 Applet n

ProactiveCommand handler

GSM Framework Files

Toolkit Framework

Appletinstall/uninstall

Security

Applettriggering

Applet securitymanager

Activation

Proactivecommands

P/Cresponses

InstallUninstall

APDU

JCRE

APDUe.g.Envelopes

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

Fileaccess

File access

…

(see NOTE 1)

NOTE 1: The install / uninstallprocess is defined inGSM xx.yy [ ]

sim.access packagesim.toolkit package

Figure 3: Toolkit framework architecture

In this model, the GSM data field structure is viewed as a series of data objects to the API. In the physical model ofcourse, they may still be stored in elementary fields, but classes will access these data as part of the objects within thoseclasses.

6.2 Applet TriggeringThe application triggering portion of the SIM Toolkit framework is responsible for the activation of toolkit applets,based on the APDU received by the GSM application.

APDU Applet Triggering

Menu Selected

SMS Received

Terminal Profile

...

GSM 03.19 V1.0.0 (1999-01)10

Figure 4: applet triggering diagram

The ME shall not be adversely affected by the presence of applets on the SIM card. For instance a syntactically correctEnvelope shall not result in an error status word in case of a failure of an applet. The only application as seen by the MEis the SIM application. As a result, a SIM Toolkit applet may throw an error, but this error will not be sent to the ME.

The difference between a Java Card applet and a Toolkit applet is that the latter does not handle APDUs directly. It willhandle higher level messages. Furthermore the execution of a method could span over multiple APDUs, in particular,the proactive protocol commands (Fetch, Terminal Response).

As seen above, when the SIM is the selected application and when a Toolkit applet is trigged the select() method of theapplet shall not be launched since the applet itself is not really selected.

Here after are the events that can trigger a SIM toolkit applet :

EVENT_PROFILE_DOWNLOAD

Upon reception of the Terminal Profile command by the SIM, one or more applications could be run ifregistered.

EVENT_MENU_SELECTION, EVENT_MENU_SELECTION_HELP_REQUEST

A toolkit applet might be activated upon selection in the ME’s menu by the user, or request help on thisspecific menu.

In order to allow the user to choose in a menu, the Toolkit Framework shall have previously issued a SET UPMENU proactive command. When an application which could be activated by menu is loaded into the SIM, theToolkit framework shall automatically update the menu stored in the ME.

[The order of the items in the SET UP MENU proactive command is for further study]

EVENT_FORMATTED_SMS_PP, EVENT_UNFORMATTED_SMS_PP

An application may be activated upon the reception of a short message.

There are two ways for a card to receive an SMS : via the Envelope SMS-PP Data Download or the UpdateRecord EFsms instruction.

The reception of the SMS by the applet cannot be guaranteed for the Update Record EFsms instruction.

The received SMS may be :- formatted according to GSM 03.48 or an other protocol to identify explicitly the applet for which the messageis send ;- unformatted or using an applet specific protocol the SIM toolkit framework will pass this data to a specificapplet which may than dispatch the message.

EVENT_UNFORMATTED_SMS_CB

When the ME receives a new cell broadcast message, the cell broadcast page may be passed to the SIM usingthe envelope command. E.g. the application may then read the message and extract a meaningful piece ofinformation which could be displayed to the user, for instance.

EVENT_CALL_CONTROL_BY_SIM

When the SIM is in call control mode and when the user dials a number, this number is passed to the SIM.Only one toolkit applet can handle the answer to this command: call barred, modified or accepted.

EVENT_EVENT_DOWNLOAD_MT_CALL, EVENT_EVENT_DOWNLOAD_CALL_CONNECTED,EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED, EVENT_EVENT_DOWNLOAD_LOCATION_STATUS,EVENT_EVENT_DOWNLOAD_USER_ACTIVITY, EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE

The applet will be triggered by the registered event download trigger, upon reception of the correspondingEnvelope command.

[The order in which the applets are triggered is for further study.]

GSM 03.19 V1.0.0 (1999-01)11

In order to allow the applet to be triggered by these events, the Toolkit Framework shall have previously issueda SET UP EVENT LIST proactive command. When an application which could be activated by these events isloaded into the SIM, the Toolkit framework shall automatically update the event list stored in the ME.

EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM

Before sending an SMS MO entered by the user, the SMS is submitted to the SIM. Only one applet can registerto this event

EVENT_UNRECOGNIZED_ENVELOPE

The unrecognised Envelope event will allow an applet to handle the evolution of the GSM 11.14 specification.

EVENT_PROPRIETARY_EVENT

This event can be used to trigger an application on proprietary events

EVENT_CARD_RESET

The applet can request to be triggered at the card reset.

Note: This is a critical phase in the card operation. Applets Triggered by this events shall not send proactivecommands and shall be trusted by the card issuer.

EVENT_STATUS_COMMAND

At reception of a STATUS APDU command, the Toolkit framework shall trigger the registered applet.

The applet shall be triggered for the registered events upon reception, and shall be able to access to the data associatedto the event using the methods provided by the sim.toolkit.ViewHandler.EnvelopeHandler class.

6.3 RegistrationDuring it's installation the applet shall register to the JCRE and the Toolkit framework so that it can be triggered by bothselection mechanisms.

The applet will have to call a registerToolkit() method to get a reference to it's registry and then to explicitly register toeach event it requires.

The applet can change the events to which it is registered during it’s life cycle.

The applet will automatically register to some event e.g. EVENT_MENU_SELECTION by calling the correspondingmethod e.g. createMenuEntry.

The API is described in the sim.toolkit.Registry class in Annex A.

6.4 Proactive command handlingThe SIM application toolkit protocol (i.e. 91xx, Fetch, Terminal Response) is handled by the Toolkit framework, theapplet shall not handle those events.

The Toolkit Framework shall provide a reference of the sim.toolkit.ViewHandler.EditHandler.ProactiveHandler to theapplet so that when the applet is triggered it can :

- initialise the current proactive command with the init() method ;

- append several Simple TLV as defined in GSM 11.14 [3] to the current proactive command with the appendTLV()methods ;

- ask the Toolkit Framework to send this proactive command to the ME and wait for the reply, with the send()method.

The Toolkit Framework shall handle the transmission of the proactive command to the ME, and the reception of theresponse. The Toolkit Framework will then return in the applet just after the send() method. It shall then provide to theApplet the sim.toolkit.ViewHandler.ProactiveResponseHandler, so that the applet can analyse the response.

GSM 03.19 V1.0.0 (1999-01)12

6.5 Envelope response handlingTo allow an applet to answer to some specific events (e.g. EVENT_CALL_CONTROL_BY_SIM) the ToolkitFramework shall provide the sim.toolkit.ViewHandler.EditHandler.EnvelopeResponseHandler.

The applet can then post a response to some events with the post() or the postAsBERTLV() methods, the applet cancontinue it's processing (e.g. prepare a proactive command) the Toolkit Framework will return the response APDUdefined by the applet (i.e. 9F xx or 9E xx).

7 SIM Toolkit applet

7.1 Applet LoadingThe SIM API card shall be compliant to the Java Card 2.1 VM Architecture Specification [9] and to the Annex B toguarantee interoperability at byte code Level.

The applet loading mechanism, protocol and applet life cycle are defined in GSM xx.yy[]

7.2 Object SharingThe sharing mechanism defined in Java Card 2.1 API Specification [7] and Java Card 2.1 Runtime EnvironmentSpecification [8] shall be used by the applet to share data.

GSM 03.19 V1.0.0 (1999-01)13

Annex A (normative):Java Card SIM API

Document Acrobat

GSM 03.19 V1.0.0 (1999-01)14

Annex B (normative):Java Card SIM API identifiers[To be defined as soon as the byte code is defined for the Java Card API 2.1]

GSM 03.19 V1.0.0 (1999-01)15

Annex C (informative):toolkit applet example

/** * Example Applet */

import sim.toolkit.*;import sim.access.*;import javacard.framework.APDU;import javacard.framework.Util;import javacard.framework.ISOException;import javacard.framework.ISO;

public class MyToolkitApplet extends ToolkitApplet implements ToolkitConstants{

public static final byte MY_INSTRUCTION = (byte)0x46; public static final byte DEVICEID_ME = (byte) 0x82; public static final byte DEVICEID_DISPLAY = (byte) 0x02; public static final byte DCS8 = (byte)0xF4; public static final byte SMS_TPDU = (byte)0x8D; public static final byte SERVER_OPERATION = (byte)15;

private byte[] menuEntry ={(byte)'S',(byte)'e',(byte)'r',(byte)'v',(byte)'i',(byte)'c',(byte)'e',(byte)'1'}; private byte[] menuTitle= {(byte)'M',(byte)'y',(byte)'M',(byte)'e',(byte)'n' ,(byte)'u'}; private byte[] item1 = {(byte)'I',(byte)'T',(byte)'E',(byte)'M',(byte)'1' }; private byte[] item2 = {(byte)'I',(byte)'T',(byte)'E',(byte)'M',(byte)'2' }; private byte[] item3 = {(byte)'I',(byte)'T',(byte)'E',(byte)'M',(byte)'3' }; private byte[] item4 = {(byte)'I',(byte)'T',(byte)'E',(byte)'M',(byte)'4' }; private Object[] ItemList = { item1, item2, item3, item4 }; private byte[] textDText = {(byte)'H',(byte)'e',(byte)'l',(byte)'l',(byte)'o',(byte)' ', (byte)'w',(byte)'o',(byte)'r',(byte)'l',(byte)'d',(byte)'2'}; private byte[] textGInput = {(byte)'Y',(byte)'o',(byte)'u',(byte)'r',(byte)' ',(byte)'n', (byte)'a',(byte)'m',(byte)'e',(byte)'?'};

private Registry reg; private SIMView gsmFile; private byte buffer[] = new byte[10];

/** * Constructor of the applet */ public MyToolkitApplet() {

// get the GSM application reference gsmFile = SIMSystem.getTheSIMView();

// register to the the SIM toolkit framework reg = registerToolkit();

// Define the applet Menu Entry and register to the EVENT_MENU_SELECTION reg.createMenuEntry(menuEntry, (short)0, (short)menuEntry.length, PRO_CMD_DISPLAY_TEXT, false); // register to the EVENT_UNFORMATTED_SMS_PP reg.setEvent(EVENT_UNFORMATTED_SMS_PP); }

/** * Method called by the JCRE at the installation of the applet */ public static void install(byte bArray[], short bOffset, byte bLength) { MyToolkitApplet MyApplet = new MyToolkitApplet (); MyApplet.register(); }

/** * Method called by the SIM Toolkit Framework */ public void processToolkit(byte event) {

// get the handler reference EnvelopeHandler envHdlr = EnvelopeHandler.getTheHandler(); ProactiveHandler proHdlr = ProactiveHandler.getTheHandler(); ProactiveResponseHandler rspHdlr = ProactiveResponseHandler.getTheHandler();

switch(event) {

GSM 03.19 V1.0.0 (1999-01)16

case EVENT_MENU_SELECTION: // Prepare the Select Item proactive command proHdlr.init((byte) PRO_CMD_SELECT_ITEM,(byte)0,DEVICEID_ME); // Append the Menu Title proHdlr.appendTLV((byte) (TAG_ALPHA_IDENTIFIER | MASK_COMPREHENSION_REQUIRED), menuTitle,(short)0,(short)menuTitle.length); // add all the Item for (short i=(short)1;i<(short)5;i++) { proHdlr.appendTLV((byte) (TAG_ITEM | MASK_COMPREHENSION_REQUIRED), (byte)i,(byte[])ItemList[i],(short)0,(short)((byte[])ItemList[i]).length); } // ask the SIM Tooolkit Framework to send the proactive command proHdlr.send();

// SelectItem response handling switch (rspHdlr.getItemIdentifier()) { case 1: case 2: case 3: // DiplayText proHdlr.init((byte) PRO_CMD_DISPLAY_TEXT, (byte)CMD_QUALIFIER, (byte)DEVICEID_DISPLAY); proHdlr.appendTLV((byte)(TAG_TEXT_STRING|MASK_COMPREHENSION_REQUIRED), DCS8 textDText,(short)0, (short)textDText.length); proHdlr.send(); break; case 4: // GetInput followed by a DisplayText of the entered text proHdlr.initGetInput((byte)1,DCS8,textGInput,(byte)0, (short)textGInput.length,(short)1,(short)2); proHdlr.send(); rspHdlr.copyTextString(textDText,(short)0); proHdlr.initDisplayText((byte)0,DCS8,textHigh, (short)1,(short)textHigh.length); proHdlr.send(); break; } break;

case EVENT_UNFORMATTED_SMS_PP: // get the TP-UD field offset short TPUDOffset = envHdlr.getTPUDOffset()+ SERVER_OPERATION;

// start the action requested by the server switch (envHdlr.getValueByte((short)TPUDOffset) ) { case 0x41 : // Update of a gsm file // get the data from the received SMS envHdlr.copyValue((short)TPUDOffset,buffer,(short)0,(short)3); // write these data in the EFpuct gsmFile.select((short)0x7F20); gsmFile.select((short)0x6F41); gsmFile.updateBinary((short)0,buffer,(short)0,(short)3);

break;

case 0x36 : // change the MenuTitle for the SelectItem envHdlr.copyValue((short)TPUDOffset,menuTitle,(short)0,(short)6); break; } break; }

}

/** * Method called by the JCRE, once selected */ public void process(APDU apdu) { switch(apdu.getBuffer()[1]) { // specific APDU for this applet to configure the MenuTitle from SelectItem case (byte)MY_INSTRUCTION: Util.arrayCopy (apdu.getBuffer(),(short) 5, menuTitle,(short) 0 ,(short)6); break; default: ISOException.throwIt(ISO.SW_INS_NOT_SUPPORTED); } }}

GSM 03.19 V1.0.0 (1999-01)17

History

Document history

Date Version Comment

December 1998 0.1.0 Initial draft based on the outcome of JCF SIM API Task Force (December 98).

January 1999 0.1.1 Discussion document during the seventh SMG9 SIM API meeting (January 99)

January 1999 0.2.0 Outcome of the seventh SMG9 SIM API meeting (January 99)

January 1999 0.2.1 Outcome of the SIM API splinter group during SMG9#17 (January 99)

January 1999 0.2.2 Outcome of SMG9#17 (January 99)

January 1999 1.0.0 Submission to SMG #28 for info. (no technical changes compared to V0.2.2)

Rapporteur: Christian Dietrich, ([email protected])

The ETSI committee SMG9 is responsible for developing this specification. An email list has been set up for discussionabout this document. To subscribe to the list, send a message to [email protected] with a single line in the body of themessage: subscribe SMG9_API YourFirstName YourLastName

The latest draft version of this specification may be found at the location:http://docbox.etsi.fr/tech-org/smg/document/smg9/specs/drafts/

orhttp://docbox.etsi.org/tech-org/smg/document/smg9/specs/drafts/

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

Table of Contents

Package Index ....................................................................................................................................................1

Class Hierarchy .................................................................................................................................................2

package sim.access ............................................................................................................................................3

Class sim.access.SIMSystem ............................................................................................................................4

Interface sim.access.SIMView .........................................................................................................................6

Class sim.access.SIMViewException .............................................................................................................16

package sim.toolkit .........................................................................................................................................21

Class sim.toolkit.ViewHandler ......................................................................................................................22

Class sim.toolkit.EnvelopeHandler ...............................................................................................................29

Class sim.toolkit.ProactiveResponseHandler ...............................................................................................32

Class sim.toolkit.EditHandler ........................................................................................................................37

Class sim.toolkit.EnvelopeResponseHandler ...............................................................................................42

Class sim.toolkit.ProactiveHandler ...............................................................................................................44

Class sim.toolkit.MEProfile ...........................................................................................................................49

Class sim.toolkit.Registry ...............................................................................................................................52

Class sim.toolkit.ToolkitApplet .....................................................................................................................58

Interface sim.toolkit.ToolkitConstants .........................................................................................................62

Class sim.toolkit.ToolkitException ................................................................................................................74

Index of all Fields and Methods .....................................................................................................................78


i

Package Index

Other Packages

• package sim.access• package sim.toolkit

Package Index 1

Class Hierarchy• class java.lang.Object

♦ class javacard.framework.Applet

◊ class sim.toolkit.ToolkitApplet♦ class sim.toolkit.MEProfile♦ class sim.toolkit.Registry♦ class sim.access.SIMSystem♦ interface sim.access.SIMView (extends javacard.framework.Shareable)♦ class java.lang.Throwable (implements java.io.Serializable)

◊ class java.lang.Exception

⋅ class java.lang.RuntimeException

• class javacard.framework.CardRuntimeException

♦ class sim.access.SIMViewException♦ class sim.toolkit.ToolkitException

♦ interface sim.toolkit.ToolkitConstants♦ class sim.toolkit.ViewHandler

◊ class sim.toolkit.EditHandler

⋅ class sim.toolkit.EnvelopeResponseHandler⋅ class sim.toolkit.ProactiveHandler

◊ class sim.toolkit.EnvelopeHandler◊ class sim.toolkit.ProactiveResponseHandler

Class Hierarchy 2

package sim.access

Interface Index

• SIMView

Class Index

• SIMSystem

Exception Index

• SIMViewException

package sim.access 3

Class sim.access.SIMSystemjava.lang.Object | +----sim.access.SIMSystem

public class SIMSystem

extends Object

The SIMSystem class provides a way to get a view of the GSM File system. In any case, the client applet(SIM Tookit or other) will only access to methods of the SIMView interface. No instance of this class isneeded.

Example of use in a standard applet: public class MyApplet extends Applet {

private SIMView theGsmApplet;

private byte[] buffer;

public MyApplet () {

theGsmApplet = SIMSystem.getTheSIMView(); // get a reference to the GSM interface

buffer = new byte[32]; // create the exchange buffer

}

public static void install(APDU apdu) throws ISOException {

MyApplet myAppletRef = new MyApplet(); // create and register the applet

myAppletRef.register();

}

public void getADN(short adnNumber) {

theGsmApplet.select(buffer, (short)0x7F10);

theGsmApplet.select(buffer, (short)0x6F3A);

theGsmApplet.readRecord((short)adnNumber, // record number

(byte)SIMView.MODE_ABSOLUTE, // mode

(short)0, // record offset

(byte[])buffer, // destination buffer

(short)0, // buffer offset

(short)32); // length to read

}

}

Constructor Index

SIMSystem()

Method Index

getTheSIMView()

Return a reference to the GSM interface

Class sim.access.SIMSystem 4

Constructors

SIMSystem public SIMSystem()

Methods

getTheSIMView public static SIMView getTheSIMView()


Returns:

a reference to a class which implements the GSMView interface


Class sim.access.SIMSystem 5

Interface sim.access.SIMViewpublic interface SIMView

extends Shareable

The SIMView interface is the interface between the GSM application and any applet (SIM Toolkit or other)and offers some methods to communicate with the GSM application without compromising the integrity ofthe existing file system. All the methods are based on the commands of the GSM11.11 specification. Thisinterface shall be implemented by the Toolkit framework. The main idea is to avoid an APDU basedcommunication between SIM Toolkit applets and the GSM application. This interface is not intended for theactivation or interaction with a SIM Toolkit applet.

See Also:

Shareable, SIMViewException

Variable Index

FID_DF_DCS

Constant: File identifier of the DF DCS1800

FID_DF_GSM

Constant: File identifier of the DF GSM

FID_DF_TELECOM

Constant: File identifier of the DF TELECOM

FID_MF

Constant: File identifier of the MF

MODE_ABSOLUTE

Constant: Record access mode 'absolute'

MODE_CURRENT

Constant: Record access mode 'current'

MODE_NEXT

Constant: Record access mode 'next'

MODE_PREVIOUS

Constant: Record access mode 'previous'

Interface sim.access.SIMView 6

SEEK_FROM_BEGINNING_FORWARD

Constant: Seek mode, from the beginning forward

SEEK_FROM_END_BACKWARD

Constant: Seek mode, from the end backward

SEEK_FROM_NEXT_FORWARD

Constant: Seek mode, from the next location forward

SEEK_FROM_PREVIOUS_BACKWARD

Constant: Seek mode, from the previous location backward

Method Index

increase(byte[], short, byte[], short)

INCREASE command as defined in GSM 11.11 standard.This method increases the current cyclic EF record of the calling applet.

invalidate()

INVALIDATE command as defined in GSM 11.11 standard.This method invalidates the currently selected EF of the calling applet.

readBinary(short, byte[], short, short)

READ BINARY command as defined in GSM 11.11 standard.This method reads the data bytes of the current transparent EF of the calling applet.

readRecord(short, byte, short, byte[], short, short)

READ RECORD command as defined in GSM 11.11 standard.This method reads the data bytes of the current linear fixed/cyclic EF of the calling applet.

rehabilitate()

REHABILITATE command as defined in GSM 11.11 standard.This method rehabilitates the currently selected EF of the calling applet.

seek(byte, byte[], short, short)

SEEK command as defined in GSM 11.11 standard.This method seeks a pattern in the current linear fixed EF of the calling applet.

select(byte[], short, short, short)

SELECT command as defined in GSM 11.11 standard.By default, the MF is selected at the beginning of each applet activation (current file = MF).

select(short)



SELECT command as defined in GSM 11.11 standard.This SELECT method allows to update the current file without handling the Select ResponseBy default, the MF is selected at the beginning of each applet activation (current file = MF).

status(byte[], short, short)

STATUS command as defined in GSM 11.11 standard.This method returns the FCI (File Control Information) of the current DF (or MF) of thecalling applet.

updateBinary(short, byte[], short, short)

UPDATE BINARY command as defined in GSM 11.11 standard.This method updates the data bytes of the current transparent EF of the calling applet.

updateRecord(short, byte, short, byte[], short, short)

UPDATE RECORD command as defined in GSM 11.11 standard.This method updates the data bytes of the current linear fixed/cyclic EF of the calling applet.

Variables

FID_MF public static final short FID_MF


FID_DF_TELECOM public static final short FID_DF_TELECOM


FID_DF_GSM public static final short FID_DF_GSM


FID_DF_DCS public static final short FID_DF_DCS


MODE_NEXT public static final byte MODE_NEXT


MODE_PREVIOUS public static final byte MODE_PREVIOUS


MODE_CURRENT public static final byte MODE_CURRENT




MODE_ABSOLUTE public static final byte MODE_ABSOLUTE


SEEK_FROM_BEGINNING_FORWARD public static final byte SEEK_FROM_BEGINNING_FORWARD


SEEK_FROM_END_BACKWARD public static final byte SEEK_FROM_END_BACKWARD


SEEK_FROM_NEXT_FORWARD public static final byte SEEK_FROM_NEXT_FORWARD


SEEK_FROM_PREVIOUS_BACKWARD public static final byte SEEK_FROM_PREVIOUS_BACKWARD


Methods

select public abstract short select(byte fci[], short fciOffset, short fciLength, short fid) throws SIMViewException

SELECT command as defined in GSM 11.11 standard.By default, the MF is selected at the beginning of each applet activation (current file = MF).This method selects a file of the common GSM file system. The file search starts at thecurrent DF of the applet according to the file search method described in GSM 11.11specification. The current DF or current EF and the current record pointer of the callingapplet will be changed after successful execution.

Parameters:

fci - is the reference to the target byte array for FCI (File Control Information) of current file,coding according to GSM 11.11. If fci is null, no response is prepared and no exception isthrown. If fci buffer is too small to receive the whole response, no exception is thrown andthe response is truncated. fciOffset is the offset in the fci buffer for the response data fciLength is the length of the required data in the fci byte array fid is the File Identifier of the file to be selected.

Returns:



length of the data which have been written in the fci buffer (cannot be greater than fci buffersize)

Throws:SIMViewException

in case of error FILE_NOT_FOUND INTERNAL_ERROR

select public abstract void select(short fid) throws SIMViewException

SELECT command as defined in GSM 11.11 standard.This SELECT method allows to update the current file without handling the Select Response Bydefault, the MF is selected at the beginning of each applet activation (current file = MF). This methodselects a file of the common GSM file system. The file search starts at the current DF of the appletaccording to the file search method described in GSM 11.11 specification. The current DF or currentEF and the current record pointer of the calling applet will be changed after successful execution.

Parameters:

fid - is the File Identifier of the file to be selected.


in case of error FILE_NOT_FOUND INTERNAL_ERROR

status public abstract short status(byte fci[], short fciOffset, short fciLength) throws SIMViewException

STATUS command as defined in GSM 11.11 standard.This method returns the FCI (File Control Information) of the current DF (or MF) ofthe calling applet.

Parameters:

fci - is the reference to the target byte array for FCI (File Control Information) ofcurrent DF (or MF), coding according to GSM 11.11. If fci is null, no response isprepared and no exception is thrown. If fci buffer is too small to receive the wholeresponse, no exception is thrown and the response is truncated. fciOffset is the offset in the fci buffer for the response data fciLength is the length of the required data in the fci byte array

Returns:

length of the data which have been written in the fci buffer (cannot be greater thanfci buffer size)




in case of error INTERNAL_ERROR

readBinary public abstract void readBinary(short fileOffset, byte resp[], short respOffset, short respLength) throws SIMViewException


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.


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


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.


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

readRecord public abstract void readRecord(short recNumber, byte mode, short recOffset, byte resp[], short respOffset, short respLength) throws SIMViewException

READ RECORD command as defined in GSM 11.11 standard.This method reads the data bytes of the current linear fixed/cyclic EF of the callingapplet. The current record pointer can be changed due to the choosen mode.

Parameters:

recNumber - is the record number. mode is the mode for reading record, according to GSM 11.11. recOffset is the offset in the record for the data to read. resp is the reference to the response byte array for read data. respOffset is the offset in the response byte array. respLength is the number of bytes to read.


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.



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.


in case of error NO_EF_SELECTED FILE_INCONSISTENT AC_NOT_FULFILLED CURRENT_EF_INVALIDATED OUT_OF_RECORD_BOUNDARIES OUT_OF_BUFFER_BOUNDARIES RECORD_NUMBER_NOT_AVAILABLE INVALID_MODE INTERNAL_ERROR

seek public abstract short seek(byte mode, byte patt[], SIMViewException


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


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



public abstract short increase(byte incr[], short incrOffset, byte resp[], short respOffset) throws SIMViewException

INCREASE command as defined in GSM 11.11 standard.This method increases the current cyclic EF record of the calling applet. Theresponse buffer will only contain the value of the increased record.

Parameters:

incr - is the reference to the source byte array, containing the value to add, on 3bytes. incrOffset is the offset in the source byte array. resp is the reference to the response byte array for new record value. If resp is null,no response is prepared and no exception is thrown. If resp buffer is smaller than therecord size, an "OUT_OF_BUFFER_BOUNDARIES" exception is thrown. If respbuffer is bigger than the record size, the resp buffer is filled with the record valueand left justified respOffset is the offset in the response byte array.

Returns:

length of the valid data in the resp buffer (cannot be greater than the record size)


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



in case of error NO_EF_SELECTED AC_NOT_FULFILLED INVALIDATION_STATUS_CONTRADICTION INTERNAL_ERROR



rehabilitate public abstract void rehabilitate() throws SIMViewException



in case of error NO_EF_SELECTED AC_NOT_FULFILLED INVALIDATION_STATUS_CONTRADICTION INTERNAL_ERROR



Class sim.access.SIMViewExceptionjava.lang.Object | +----java.lang.Throwable | +----java.lang.Exception | +----java.lang.RuntimeException | +----javacard.framework.CardRuntimeException | +----sim.access.SIMViewException

public class SIMViewException

extends CardRuntimeException

The SIMViewException class encapsulates specific exceptions which can be generated by the methods ofthe SIMView interface in case of error.

Table SIMViewException

reason Description

NO_EF_SELECTED No EF selected before calling the method

FILE_INCONSISTENT File inconsistent with the method

AC_NOT_FULFILLED Access condition level not fulfilled

FILE_NOT_FOUND File not found

INTERNAL_ERROR Internal error

CURRENT_EF_INVALIDATED Current EF invalidated

INVALIDATION_STATUS_CONTRADICTION Method in contradiction with the invalidation status

OUT_OF_FILE_BOUNDARIES Out of the transparent file boundaries

OUT_OF_RECORD_BOUNDARIES Out of the record boundaries

OUT_OF_BUFFER_BOUNDARIES Out of the buffer boundaries (response or data)

RECORD_NUMBER_NOT_AVAILABLE Record number not available

INVALID_MODE Invalid mode for seek command or record access

PATTERN_NOT_FOUND Pattern not found for seek command

PATTERN_SIZE_INCONSISTENT Pattern size greater than record size

MAX_VALUE_REACHED Max value reached for increase command

See Also:

SIMView

Class sim.access.SIMViewException 16

Variable Index

AC_NOT_FULFILLED

Constant: Access condition level not fulfilled

CURRENT_EF_INVALIDATED

Constant: Current EF invalidated

FILE_INCONSISTENT

Constant: File inconsistent with the method

FILE_NOT_FOUND

Constant: File not found

INTERNAL_ERROR

Constant: Internal error

INVALID_MODE

Constant: Invalid mode for seek command or record access

INVALIDATION_STATUS_CONTRADICTION

Constant: Method in contradiction with the invalidation status

MAX_VALUE_REACHED

Constant: Max value reached for increase command

NO_EF_SELECTED

Constant: No EF selected before calling the method

OUT_OF_BUFFER_BOUNDARIES

Constant: Out of the buffer boundaries (response or data)

OUT_OF_FILE_BOUNDARIES

Constant: Out of the transparent file boundaries

OUT_OF_RECORD_BOUNDARIES

Constant: Out of the record boundaries

PATTERN_NOT_FOUND

Constant: Pattern not found for seek command



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


FILE_INCONSISTENT public static final short FILE_INCONSISTENT


AC_NOT_FULFILLED public static final short AC_NOT_FULFILLED


FILE_NOT_FOUND public static final short FILE_NOT_FOUND


INTERNAL_ERROR public static final short INTERNAL_ERROR


CURRENT_EF_INVALIDATED public static final short CURRENT_EF_INVALIDATED




INVALIDATION_STATUS_CONTRADICTION public static final short INVALIDATION_STATUS_CONTRADICTION


OUT_OF_FILE_BOUNDARIES public static final short OUT_OF_FILE_BOUNDARIES


OUT_OF_RECORD_BOUNDARIES public static final short OUT_OF_RECORD_BOUNDARIES


OUT_OF_BUFFER_BOUNDARIES public static final short OUT_OF_BUFFER_BOUNDARIES


RECORD_NUMBER_NOT_AVAILABLE public static final short RECORD_NUMBER_NOT_AVAILABLE


INVALID_MODE public static final short INVALID_MODE


PATTERN_NOT_FOUND public static final short PATTERN_NOT_FOUND


PATTERN_SIZE_INCONSISTENT public static final short PATTERN_SIZE_INCONSISTENT


MAX_VALUE_REACHED public static final short MAX_VALUE_REACHED


Constructors

SIMViewException public SIMViewException(short reason)

Constructs a SIMViewException object. To conserve on resources use throwIt() to re-usethe JCRE instance of this class.



Parameters:

reason - is the reason for the exception

Methods throwIt public static void throwIt(short reason) throws SIMViewException


Parameters:

reason - is the reason for the exception


always



package sim.toolkit

Interface Index

• ToolkitConstants

Class Index

• EditHandler• EnvelopeHandler• EnvelopeResponseHandler• MEProfile• ProactiveHandler• ProactiveResponseHandler• Registry• ToolkitApplet• ViewHandler

Exception Index

• ToolkitException

package sim.toolkit 21

Class sim.toolkit.ViewHandlerjava.lang.Object | +----sim.toolkit.ViewHandler

public class ViewHandler

extends Object

The ViewHandler class offers basic services and contains basic methods to handle TLV list, such as in aTerminal Response data field or in a BER-TLV element (Envelope data field or Proactive command).

See Also:

ToolkitException

Constructor Index

ViewHandler(byte[], short, short)

Build a new ViewHandler object.

Method Index

compareValue(short, byte[], short, short)

Compare the last found TLV element with a buffer.

copyValue(short, byte[], short, short)

Copy a part of the last TLV element which has been found, into a destination buffer.

findAndCompareValue(byte, byte, short, byte[], short, short)

Look for the first occurence of a TLV element and compare its value with a buffer.

findAndCompareValue(byte, byte[], short)


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)


Class sim.toolkit.ViewHandler 22

findTLV (byte, byte)

Look for a TLV element in the TLV structure (handler buffer).

getValueByte(short)

Get a byte from the last TLV element which has been found in the buffer.

getValueLength()

Get the length of the value field for the last TLV element which has been found in the buffer.

Constructors

ViewHandler public ViewHandler(byte buffer[], short offset, short length)


Parameters:

buffer - a reference to the TLV buffer

offset - the position in the TLV buffer

length - the length of the TLV buffer

Methods findTLV public byte findTLV(byte tag, byte occurrence) throwsToolkitException

Look for a TLV element in the TLV structure (handler buffer). This search method is ComprehensionRequired flag independent.

Parameters:

tag - the tag of the TLV element to search

occurrence - the occurrence number of the TLV element (1 for the first, 2 for the second...)

Returns:

NOT_FOUND if the required occurrence of the TLV element does not exist FOUND_CR_SET if the required occurence exists and Comprehension Required flag is set FOUND_CR_NOT_SET if the required occurence exists and Comprehension Required flag is not set

Throws:ToolkitException



HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for the system-definedsingleton classes.

getValueLength public short getValueLength() throws ToolkitException

Get the length of the value field for the last TLV element which has been found inthe buffer.

Returns:

length of the value field


HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for thesystem-defined singleton classes. UNAVAILABLE_ELEMENT in case of unavailable TLV element

getValueByte public byte getValueByte(short valueOffset) throws ToolkitException


Parameters:

valueOffset - the offset of the byte to return in the TLV element

Returns:

element value (1 byte)



copyValue public short copyValue(short valueOffset, byte dstBuffer[], ToolkitException


Parameters:

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


HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for the system-definedsingleton classes. UNAVAILABLE_ELEMENT in case of unavailable TLV element

compareValue public byte compareValue(short valueOffset, byte compareBuffer[], short compareOffset, short compareLength) throws ToolkitException


Parameters:

valueOffset - the offset of the first byte to compare in the TLV element

compareBuffer - a reference to the comparison buffer

compareOffset - the position in the comparison buffer

compareLength - the length to be compared

Returns:

the result of the comparison as follows:0 if identical -1 if the first miscomparing byte in TLV element array is less than that in destinationarray, 1 if the first miscomparing byte in TLV element array is greater than that indestination array.



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



no TLV element is found, the return value equals dstOffset . This search method isComprehension Required flag independent. To find another occurence or to copy only a partof the TLV, the methods findTLV() and copyValue() shall be used.

Parameters:




Returns:

dstOffset + length of the copied value



findAndCopyValue public short findAndCopyValue(byte tag, byte occurenc eToolkitException

Look for the first occurence of a TLV element and copy its value into a destination buffer. If no TLVelement is found, the return value equals dstOffset . This search method is Comprehension Requiredflag independent. To find another occurence or to copy only a part of the TLV, the methodsfindTLV() and copyValue() shall be used.

Parameters:







Returns:

dstOffset + dstLength


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 dstBuffer[], short dstOffset) throws ToolkitException

Look for the first occurence of a TLV element and compare its value with a buffer. Ifno TLV element is found, the return value equals -1. This search method isComprehension Required flag independent. To find another occurence or to compareonly a part of the TLV, the methods findTLV() and compareValue() shall be used.

Parameters:


dstBuffer - a reference to the comparison buffer

dstOffset - the position in the comparison buffer

Returns:

the result of the comparison as follows:0 if identical -1 if the first miscomparing byte in TLV element array is less than that in destinationarray, 1 if the first miscomparing byte in TLV element array is greater than that indestination array.



findAndCompareValue public byte findAndCompareValue(byte tag, byte occurence, short valueOffset, byte compareBuffer[], short compareOffset, short compareLength) throws ToolkitException

Look for the first occurence of a TLV element and compare its value with a buffer. If noTLV element is found, the return value equals -1. This search method is ComprehensionRequired flag independent. To find another occurence or to compare only a part of the TLV,the methods findTLV() and compareValue() shall be used.

Parameters:






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.





Class sim.toolkit.EnvelopeHandlerjava.lang.Object | +---- sim.toolkit.ViewHandler | +----sim.toolkit.EnvelopeHandler

public final class EnvelopeHandler

extends ViewHandler

The EnvelopeHandler class contains basic methods to handle the Envelope data field. This class will be usedby the Toolkit applet in order to have access to the current Envelope information. No constructor is availablefor the Toolkit applet. The EnvelopeHandler class is a singleton class and the only way to get aEnvelopeHandler reference is through the getTheHandler() static method.

Example of use in a standard Toolkit applet: private static final byte MY_TAG = (byte)0x54; // constant

private EnvelopeHandler theEnv;

private byte[] data; // reference declaration

data = new byte[32]; // build object

void processToolkit(byte event) throws ToolkitException {

// get the EnvelopeHandler system instance

theEnv = EnvelopeHandler.getTheHandler();

if (theEnv.findTLV(MY_TAG, (byte)1) != NOT_FOUND) { // look for MY_TAG element

if (theEnv.getValueByte((short)0) == (byte)1) { // check first element byte

// copy element part into data buffer

theEnv.copyValue((short)1,

data,

(short)0,

(short)(theEnv.getValueLength() - 1));

}

}

}

See Also:

ViewHandler, EnvelopeResponseHandler, ToolkitException

Method Index

getEnvelopeTag()

Return the Envelope BER-TLV tag.

getItemIdentifier()

Return the item identifier byte value from the first Item Identifier TLV element in the currentEnvelope data field.

getTheHandler()

Class sim.toolkit.EnvelopeHandler 29

Return the single system instance of the EnvelopeHandler class.

getTPOAOffset()

Look for the TP-OA field in the first TPDU TLV element in the Envelope data field.

getTPUDOffset()

Look for the TP-UD field in the first TPDU TLV element in the Envelope data field.

Methods

getTheHandler public static EnvelopeHandler getTheHandler()

Return the single system instance of the EnvelopeHandler class. Several calls to this methodwill always return the same object reference.

Returns:

reference of the system instance

getEnvelopeTag public byte getEnvelopeTag() throws ToolkitException


Returns:

Envelope tag


HANDLER_NOT_AVAILABLE if the handler is busy.

getTPOAOffset public short getTPOAOffset() throws ToolkitException

Look for the TP-OA field in the first TPDU TLV element in the Envelope data field.Should be used with Envelope SMS-PP Data Download.

Returns:

TPOA offset in the first TPDU TLV element if TPOA exists. The TPOA length canbe recovered by using the getValueByte method in Handler class.





UNAVAILABLE_ELEMENT in case of unavailable TPDU TLV element or if theTPOA field does not exist

getTPUDOffset public short getTPUDOffset() throws ToolkitException

Look for the TP-UD field in the first TPDU TLV element in the Envelope data field. Shouldbe used with Envelope SMS-PP Data Download.

Returns:

TPUD offset in the first TPDU TLV element if TPUD exists. The TPUD length can berecovered by using the getValueByte method in Handler class.


HANDLER_NOT_AVAILABLE if the handler is busy. UNAVAILABLE_ELEMENT in case of unavailable TPDU TLV element or if the TPUDfield does not exist

getItemIdentifier public byte getItemIdentifier() throws ToolkitException


Returns:

item identifier


HANDLER_NOT_AVAILABLE if the handler is busy. UNAVAILABLE_ELEMENT in case of unavailable TLV element



Class sim.toolkit.ProactiveResponseHandlerjava.lang.Object | +---- sim.toolkit.ViewHandler | +----sim.toolkit.ProactiveResponseHandler

public final class ProactiveResponseHandler

extends ViewHandler

The ProactiveResponseHandler class contains basic methods to handle the Terminal Response data field.This class will be used by the Toolkit applet to get the response to the Proactive commands. No constructor isavailable for the Toolkit applet. The ProactiveResponseHandler class is a singleton class and the only way toget a ProactiveResponseHandler reference is through the getTheHandler() static method.

Example of use in a standard Toolkit applet: private byte[] data;

data = new byte[32]; // build a buffer

ProactiveResponseHandler ProRespHdlr; // get the system instance

ProRespHdlr = ProactiveResponseHandler.getTheHandler();

// get General Result

byte result = ProRespHdlr.getGeneralResult();

respHdlr.findTLV(TAG_DEVICE_IDENTITIES, 1); // look for Device Identities

byte sourceDev = ProRespHdlr.getValueByte((short)0); // read Device Identities

byte destinDev = ProRespHdlr.getValueByte((short)1);

// look for Text String element

if (ProRespHdlr.findTLV(TAG_TEXT_STRING, (byte)1) == FOUND_CR_SET) {

if ((short len = ProRespHdlr.getValueLength()) > 1) {

// not empty string: to be copied

ProRespHdlr.copyValue((short)1, data, (short)0, (short)(len - 1));

}

}

See Also:

ViewHandler, ProactiveHandler, ToolkitException

Method Index

copyAdditionalInformation(byte[], short, short)

Copy a part of the additional information field from the first Result TLV element of thecurrent response data field.

copyTextString(byte[], short)

Copy the text string value from the first Text String TLV element of the current responsedata field.

getAdditionalInformationLength()

Class sim.toolkit.ProactiveResponseHandler 32

Return the length of the additional information field from the first Result TLV element of thecurrent response data field.

getDurationInterval()

Return the duration interval value from the first Duration TLV element of the currentresponse data field.

getDurationUnit()

Return the duration unit byte from the first Duration TLV element of the current responsedata field.

getGeneralResult()

Return the general result byte of the Proactive command.

getItemIdentifier()

Return the item identifier byte value from the first Item Identifier TLV element of the currentresponse data field.

getTextStringCodingScheme()

Return the data coding scheme byte from the first Text String TLV element of the currentresponse data field.

getTextStringLength()

Return the text string length value from the first Text String TLV element of the currentresponse data field.

getTheHandler()

Return the single system instance of the ProactiveResponseHandler class.

Methods

getTheHandler public static ProactiveResponseHandler getTheHandler()

Return the single system instance of the ProactiveResponseHandler class. Several calls tothis method will always return the same object reference.

Returns:


getGeneralResult public byte getGeneralResult() throws ToolkitException




Returns:

general result of the command (first byte of Result TLV in Terminal Response)


HANDLER_NOT_AVAILABLE if the Proactive response buffer is not valid UNAVAILABLE_ELEMENT in case of unavailable TLV element

getAdditionalInformationLength public short getAdditionalInformationLength() throws ToolkitException

Return the length of the additional information field from the first Result TLVelement of the current response data field.

Returns:

additional information length



copyAdditionalInformation public short copyAdditionalInformation(byte dstBuffer[], short dstOffset, short dstLength) throws ToolkitException


Parameters:




Returns:

dstOffset+dstLength





getItemIdentifier public byte getItemIdentifier() throws ToolkitException


Returns:

item identifier



getDurationInterval public short getDurationInterval() throws ToolkitException


Returns:

duration interval (between 1 and 255)



getDurationUnit public byte getDurationUnit() throws ToolkitException


Returns:

duration unit (0, 1 or 2)



getTextStringLength public short getTextStringLength() throws ToolkitException

Return the text string length value from the first Text String TLV element of the current response



data field. The Data Coding Scheme byte is not taken into account.

Returns:

text string length



getTextStringCodingScheme public byte getTextStringCodingScheme() throws ToolkitException

Return the data coding scheme byte from the first Text String TLV element of thecurrent response data field.

Returns:

text string coding scheme



copyTextString public short copyTextString(byte dstBuffer[], short dstOffset) throws ToolkitException

Copy the text string value from the first Text String TLV element of the current responsedata field. The Data Coding Scheme byte is not copied.

Parameters:



Returns:

dstOffset + length of the copied value





Class sim.toolkit.EditHandlerjava.lang.Object | +---- sim.toolkit.ViewHandler | +----sim.toolkit.EditHandler

public class EditHandler

extends ViewHandler

This class is the basic class for the construction of a list of simple TLV elements

See Also:

ViewHandler, ToolkitException

Constructor Index

EditHandler(byte[], short, short)

Build a new EditHandler object.

Method Index

appendArray(byte[], short, short)

Append a buffer into the EditHandler buffer.

appendTLV(byte, byte)

Append a TLV element to the current Proactive command (1-byte element)(useful to add single byte elements as Item Identifier or Tone).

appendTLV(byte, byte, byte)

Append a TLV element to the current Proactive command (2-byte element)(useful to add double byte elements as Device Identities, Duration or Response Length).

appendTLV(byte, byte, byte[], short, short)

Append a TLV element to the current Proactive command (byte array format)

appendTLV(byte, byte[], short, short)


clear()

Class sim.toolkit.EditHandler 37

Clear an EditHandler buffer.

getLength()

Return the length of the current SIMPLE TLV list.

Constructors

EditHandler public EditHandler(byte buffer[], short offset, short length)


Methods

clear public void clear() throws ToolkitException



HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for thesystem-defined singleton classes.

appendArray public void appendArray(byte buffer[], short offset, ToolkitException


Parameters:

buffer - the buffer containing data for copy

offset - the offset in the buffer

length - the value length of the buffer


BUFFER_OVERFLOW in case of too much data HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for the system-definedsingleton classes.

appendTLV public void appendTLV(byte tag,



byte value[], short offset, short length) throws ToolkitException


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


BUFFER_OVERFLOW in case of too much data HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for thesystem-defined singleton classes.

appendTLV public void appendTLV(byte tag, byte value) throws ToolkitException


Parameters:


value - the TLV value on 1 byte



appendTLV public void appendTLV(byte tag, byte value1, ToolkitException


Parameters:




value1 - the 1st byte (msb) of the TLV value

value2 - the 2nd byte (lsb) of the TLV value


BUFFER_OVERFLOW in case of too much data HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for the system-definedsingleton classes.

appendTLV public void appendTLV(byte tag, byte firstbyte, byte value[], short offset, short length) throws ToolkitException


Parameters:


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



getLength public short getLength() throws ToolkitException


Returns:

length in bytes


HANDLER_NOT_AVAILABLE if the handler is busy. This can only happen for the



system-defined singleton classes.



Class sim.toolkit.EnvelopeResponseHandlerjava.lang.Object | +---- sim.toolkit.ViewHandler | +---- sim.toolkit.EditHandler | +----sim.toolkit.EnvelopeResponseHandler

public final class EnvelopeResponseHandler

extends EditHandler

The EnvelopeResponseHandler class contains basic methods to handle the Envelope response data field.This class will be used by the Toolkit applet in order to edit the response to current Envelope command. Noconstructor is available for the Toolkit applet. The EnvelopeResponseHandler class is a singleton class andthe only way to get a EnvelopeResponseHandler reference is through the getTheHandler() static method.

See Also:

ViewHandler, EditHandler, EnvelopeHandler, ToolkitException

Method Index

getTheHandler()

Return the single system instance of the EnvelopeResponseHandler class.

post(byte)

Post the Envelope response.

postAsBERTLV(byte, byte)

Post the Envelope response in a BER TLV structure.

Methods

getTheHandler public static EnvelopeResponseHandler getTheHandler()

Return the single system instance of the EnvelopeResponseHandler class. Several calls tothis method will always return the same object reference.

Returns:

Class sim.toolkit.EnvelopeResponseHandler 42


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)



postAsBERTLV public void postAsBERTLV(byte statusType, byte tag)

Post the Envelope response in a BER TLV structure. Should be used with EnvelopeCall Control by SIM or MO Short Message Control by SIM. The tag value is to beused to set the Result for Call Control and MO Short Message Control by the SIM.

Parameters:

statusType - the status to be sent to the ME (9Fxx or 9Exx)

tag - the BER Tag to be used at the beginning of the SIMPLE_TLV list.




Class sim.toolkit.EnvelopeResponseHandler 43

Class sim.toolkit.ProactiveHandlerjava.lang.Object | +---- sim.toolkit.ViewHandler | +---- sim.toolkit.EditHandler | +----sim.toolkit.ProactiveHandler

public final class ProactiveHandler

extends EditHandler

This class is the basic class for the definition of Proactive commands . Low level methods, as init() ,appendTLV() ... will be used to handle generic Proactive commands (standard or future definitions...). Othermethods are dedicated to the Release 97 of the GSM 11.14 (version 6.2.0). The ProactiveHandler class is asingleton class, therefore only one instance of this class may be created by the system: all the Toolkit applets,which need to send Proactive commands, shall call the getTheHandler() static method to get the referenceof this system instance.

Example of use in a standard Toolkit applet: // constants definition

private static final byte MY_COMMAND = (byte)0x33;

private static final byte DEVICE_ME = (byte)0x82;

private static final byte MY_TAG = (byte)0x45;

private static final byte DCS8 = (byte)0x04;

ProactiveHandler proHdlr; // get the system instance

proHdlr = ProactiveHandler.getTheHandler();

// build and send a new Proactive command

proHdlr.init(MY_COMMAND, (byte)0, DEVICE_ME);

proHdlr.appendTLV((byte)(MY_TAG | MASK_COMPREHENSION_REQUIRED),

(byte)0);

short len = proHdlr.getLength(); // length should be 14 !

byte result = proHdlr.send();

private byte[] text = new byte[12]; // byte array definition

text[0] = (byte)'S'; // text, in 8-bit format, is "SAT"

text[1] = (byte)'A';

text[2] = (byte)'T';

// build and send a DisplayText command

result = proHdlr.initDisplayText((byte)0x80, DCS8, text, (short)0, (short)3);

result = proHdlr.send();

See Also:

ViewHandler, EditHandler, ToolkitException

Method Index

getTheHandler()

Return the single system instance of the ProactiveHandler class.

Class sim.toolkit.ProactiveHandler 44

init (byte, byte, byte)

Initialize the next Proactive command with Command Details and Device Identities TLV.The source device is always the SIM card.

initDisplayText(byte, byte, byte[], short, short)

Build a Display Text Proactive command without sending the command.

initGetInkey(byte, byte, byte[], short, short)

Build a Get Inkey Proactive command without sending the command.

initGetInput(byte, byte, byte[], short, short, short, short)

Initialize the building of a Get Input Proactive command.

initPollInterval (byte, short)

Build a Poll Interval Proactive command without sending the command.

send()

Send the current Proactive command.

Methods

getTheHandler public static ProactiveHandler getTheHandler()

Return the single system instance of the ProactiveHandler class. Several calls to this methodwill always return the same object reference.

Returns:


init public void init(byte type, byte qualifier, byt eToolkitException

Initialize the next Proactive command with Command Details and Device Identities TLV.The source device is always the SIM card. The command number is generated by the method. TheComprehension Required flags are set.

Parameters:

type - the command type

qualifier - the command qualifier



dstDevice - the destination device


HANDLER_NOT_AVAILABLE if the Proactive buffer is busy

send public byte send() throws ToolkitException


Returns:



HANDLER_NOT_AVAILABLE if the Proactive buffer is busy PROACTIVE_NOT_SUPPORTED if the ME does not support proactive SIMs

initDisplayText public byte initDisplayText(byte qualifier, byte dcs, byte buffer[], short offset, short length) throws ToolkitException

Build a Display Text Proactive command without sending the command. TheComprehension Required flags are all set to 1.

Parameters:

qualifier - Display Text command qualifier

dcs - data coding scheme

buffer - reference to the text string source buffer

offset - offset of the text string in the source buffer

length - length of the text string in the source buffer

Returns:



PROACTIVE_OVERFLOW in case of too large Proactive command HANDLER_NOT_AVAILABLE if the Proactive buffer is busy



initGetInkey public byte initGetInkey(byte qualifier, byte dcs, ToolkitException

Build a Get Inkey Proactive command without sending the command. The Comprehension Requiredflags are all set to 1.

Parameters:

qualifier - Get Inkey command qualifier


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:




initPollInterval public byte initPollInterval(byte unit, short interval) throws ToolkitException

Build a Poll Interval Proactive command without sending the command. TheComprehension Required flags are all set to 1.

Parameters:

unit - time unit

interval - time interval

Returns:




initGetInput



public void initGetInput(byte qualifier, byte dcs, byte buffer[], short offset, short length, short minRespLength, short maxRespLength) throws ToolkitException

Initialize the building of a Get Input Proactive command. The Comprehension Required flagsare all set to 1. The following command parameters (i.e. TLVs) may be appended to the command beforesending it: Default Text

Parameters:

qualifier - Get Input command qualifier


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





Class sim.toolkit.MEProfilejava.lang.Object | +----sim.toolkit.MEProfile

public final class MEProfile

extends Object

The MEProfile class contains methods to question the handset profile, regarding the SIM ApplicationToolkit and supposing that this profile has been set by the Terminal Profile APDU command. The followingtable gives the index value according to the facility to check. Only Release 97 facilities of the GSM 11.14 arelisted (version 6.2.0). This class contains only static methods, no instance of this class is necessary.

Facility Index

Profile download 0

SMS-PP data download 1

Cell Broadcast data download 2

Menu selection 3

New status word for SIM data download error 4

Command result 8

Call Control by SIM 9

Cell identity included in Call Control by SIM 10

MO short message control by SIM 11

Handling of the alpha identifier 12

UCS2 Entry supported 13

UCS2 Display supported 14

Proactive SIM: Display Text 16

Proactive SIM: Get Inkey 17

Proactive SIM: Get Input 18

Proactive SIM: More Time 19

Proactive SIM: Play Tone 20

Proactive SIM: Poll Interval 21

Proactive SIM: Polling Off 22

Proactive SIM: Refresh 23

Proactive SIM: Select Item 24

Class sim.toolkit.MEProfile 49

Proactive SIM: Send Short Message 25

Proactive SIM: Send SS 26

Proactive SIM: Send USSD 27

Proactive SIM: Set Up Call 28

Proactive SIM: Set Up Menu 29

Proactive SIM: Provide Local Information 30

Proactive SIM: Provide Local Information (NMR) 31

Proactive SIM: Set Up Event List 32

Event: MT call 33

Event: Call connected 34

Event: Call disconnected 35

Event: Location status 36

Event: User activity 37

Event: Idle screen available 38

Example of use in a standard Toolkit applet: private static final byte PROFILE_USSD = (byte)27;

if (MEProfile.check(PROFILE_USSD) == true) {

// USSD available on the handset

sendTheRequest();

} else {

// abort applet

return;

}

Method Index

check(byte)

Check a facility in the handset profile.

check(byte[], short, short)

Check a set of facilities in the handset profile.

Methods

check public static boolean check(byte index)

Check a facility in the handset profile. In case of phase 2 mobile, this method returns always



false, but no exception is thrown.

Parameters:

index - the number of the facility to check, according to the table above.

Returns:

true if the facility is supported, false otherwise

check public static boolean check(byte mask[], short offset,

Check a set of facilities in the handset profile. In case of phase 2 mobile, this method returns alwaysfalse, but no exception is thrown. The method checks all the facilities corresponding to bits set to 1 inthe mask buffer.

Parameters:

mask - a byte array containing the mask to compare with the profile

offset - the starting offset of the mask in the byte array

length - the length of the mask (at least 1)

Returns:

true if the set of facilities is supported, false otherwise



Class sim.toolkit.Registryjava.lang.Object | +----sim.toolkit.Registry

public final class Registry

extends Object

The Registry class offers basic services and methods to allow any Toolkit applet to register its configuration(supported events) during the install phase and possibly to change it during all the applet life time. Eachtoolkit applet should ask the system to build an instance of this class through theregisterToolkit() method of the ToolkitApplet class. The initial state of all the events is cleared.

Note: the constants related to the events are defined in the ToolkitConstants interface.

Example of use in a standard Toolkit applet: public class MyToolkitApplet extends ToolkitApplet implements ToolkitConstants {

// data fields

private Registry reg;

private byte[] menuEntry = { ... };

private byte[] myTAR = {(byte)0x11, (byte)0x22, (byte)0x33};

private byte menuId;

//

// Constructor of applet

//

public MyToolkitApplet() {

// get a Registry object for the applet...

reg = registerToolkit();

// ...and initialize it according to the applet characteristics

menuId = reg.createMenuEntry(menuEntry, (short)0, (short)menuEntry.length,

PRO_CMD_SET_UP_CALL, false);

reg.disableMenuEntry(menuId);

reg.setDataDownloadTAR(myTAR, (short)0);

reg.setEvent(EVENT_CALL_CONTROL_BY_SIM);

}

//

// Install method

// *param bArray the array containing installation parameters

// *param bOffset the starting offset in bArray

// *param bLength the length in bytes of the parameter data in bArray

//

public static void install(byte bArray[], short bOffset, byte bLength) throws ISOException {

// create and register applet

MyToolkitApplet applet = new MyToolkitApplet();

applet.register();

}

//

// Process toolkit events

// *param event the type of event to be processed

// *exception ToolkitException

//

public void processToolkit(byte event) throws ToolkitException {

if (event == EVENT_FORMATTED_SMS_PP) {

reg.enableMenuEntry(menuId);

} else if (event == EVENT_MENU_SELECTION) {

//...

}

}

Class sim.toolkit.Registry 52

}

See Also:

ToolkitApplet, ToolkitException, ToolkitConstants

Method Index

changeMenuEntry(byte, byte[], short, short, byte, boolean)

Change the value of a menu entry.

clearEvent(byte)

Clear an event in the Registry.

createMenuEntry(byte[], short, short, byte, boolean)

Create a new menu entry.

disableMenuEntry(byte)

Disable a menu entry.

enableMenuEntry(byte)

Enable a menu entry.

isEventSet(byte)

Allow to know if an event is set in the Registry.

setDataDownloadTAR(byte[], short)

Register the SMS-PP Data Download TAR.The TAR (Toolkit Application Reference) will be used to identify the target applet in case offormatted short message.

setEvent(byte)

Set an event in the Registry.

setEventList(byte[], short, short)

Set an event list in the Registry.

Methods

setEvent



public void setEvent(byte event) throws ToolkitException


Parameters:

event - value of the new event to register (between 0 and 255)


EVENT_NOT_SUPPORTED if the event is not supported EVENT_ALREADY_REGISTERED if the event has already been registered (for limitedevent like Call Control)

setEventList public void setEventList(byte eventlist[], short offset, ToolkitException


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


EVENT_NOT_SUPPORTED if one event is not supported EVENT_ALREADY_REGISTERED if one event has already been registered (for limited event likeCall Control)

clearEvent public void clearEvent(byte event)


Parameters:

event - the value of the event to unregister (between 0 and 255)

isEventSet public boolean isEventSet(byte event)




Parameters:

event - the value of the event (between 0 and 255)

Returns:

true if the event is set in the Registry, false otherwise

setDataDownloadTAR public void setDataDownloadTAR(byte tar[], short off sToolkitException

Register the SMS-PP Data Download TAR.The TAR (Toolkit Application Reference) will be used to identify the target applet in case offormatted short message. By calling this method the applet automatically registers to the eventEVENT_FORMATTED_SMS_PP.

Parameters:

tar - buffer containing the Toolkit Applet Reference value (on 3 bytes)

offset - the offset of the TAR within the buffer


INVALID_TAR if this TAR is already used

disableMenuEntry public void disableMenuEntry(byte id) throws ToolkitException


Parameters:

id - the menu entry identifier supplied by the createMenuEntry() method


ENTRY_NOT_FOUND if the menu entry does not exist for this applet

enableMenuEntry public void enableMenuEntry(byte id) throws ToolkitException


Parameters:






createMenuEntry public byte createMenuEntry(byte menuEntry[], short off sToolkitException

Create a new menu entry. The default state of the new menu entry is 'enabled'. The value of the"helpSupported" boolean parameter defines the registration status of theEVENT_MENU_SELECTION_HELP_REQUEST event. The applet automatically registers to theEVENT_MENU_SELECTION.

Parameters:

menuEntry - a reference on a byte array, containing the new menu entry string

offset - the position of the new menu entry string in the buffer

length - the length of the new menu entry string

nextAction - a byte coding the next action indicator for the new menu entry (or 0)

helpSupported - equals true if help is available for the new menu entry

Returns:

the identifier attached to the new menu entry


REGISTRY_ERROR if the new menu entry cannot be created

changeMenuEntry public void changeMenuEntry(byte id, byte menuEntry[], short offset, short length, byte nextAction, boolean helpSupported) throws ToolkitException

Change the value of a menu entry. The default state of the changed menu entry is'enabled'. The value of the "helpSupported" boolean parameter defines theregistration status of the EVENT_MENU_SELECTION_HELP_REQUEST event.

Parameters:


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





Class sim.toolkit.ToolkitAppletjava.lang.Object | +----javacard.framework.Applet | +----sim.toolkit.ToolkitApplet

public abstract class ToolkitApplet

extends Applet

This abstract class defines a Toolkit applet in a smart card. The ToolkitApplet class should be extended byany applet wishing to implement SIM Toolkit features, as described in the GSM 11.14 specification (e.g.Menu Selection event, Call Control by SIM event...), to be loaded onto, installed into and executed on a JavaCard compliant smart card. A toolkit applet can be triggered by the following events :

Event Description

EVENT_PROFILE_DOWNLOAD Terminal Profile command reception

EVENT_FORMATTED_SMS_PP 03.48 formatted envelope SMS-PPData Download reception

EVENT_UNFORMATTED_SMS_PP Unformatted SMS-PP Data Downloadreception

EVENT_UNFORMATTED_SMS_CB Unformatted Cell Broadcast DataDownload command reception

EVENT_MENU_SELECTION Envelope Menu Selection commandreception

EVENT_MENU_SELECTION_HELP_REQUEST Envelope Menu Selection HelpRequest command reception

EVENT_CALL_CONTROL_BY_SIM Envelope Call Control by SIMcommand reception

EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM Envelope MO Short Message Controlby SIM command reception

EVENT_EVENT_DOWNLOAD_MT_CALL Envelope Event Download - MT call

EVENT_EVENT_DOWNLOAD_CALL_CONNECTED Envelope Event Download - Callconnected

EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED Envelope Event Download - Calldisconnected

EVENT_EVENT_DOWNLOAD_LOCATION_STATUS Envelope Event Download - Locationstatus

EVENT_EVENT_DOWNLOAD_USER_ACTIVITY Envelope Event Download - Useractivity

EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE Envelope Event Download - Idlescreen available

Class sim.toolkit.ToolkitApplet 58

EVENT_CARD_RESET Card electrical reset event

EVENT_STATUS_COMMAND Status APDU command event

EVENT_UNRECOGNIZED_ENVELOPE Unrecognized Envelope commandreception

EVENT_PROPRIETARY_EVENT Reserved for proprietary events

Example of standard Toolkit applet: import javacard.framework.*;

import sim.toolkit.*;

//

// The HelloWorld class is a simple Toolkit applet, which may be used as an

// example to show how such an applet will be installed and registered and

// how it will be launched.

//

public class HelloWorld extends ToolkitApplet implements ToolkitConstants {

// data fields

private static final byte CMD_QUALIFIER = (byte)0x80;

private byte[] menuEntry = {'S','e','r','v','i','c','e','1'};

private byte[] textBuf = {'H','e','l','l','o',' ','w','o','r','l','d',' ','!'};

private Registry reg;

//

// Constructor of applet

//

public HelloWorld() {

// get a Registry object...

// ...and initialize it according to the applet characteristics

reg.createMenuEntry(menuEntry, (short)0, (short)menuEntry.length, PRO_CMD_DISPLAY_TEXT, false);

}

//

// Install method

// *param bArray the array containing installation parameters

// *param bOffset the starting offset in bArray

// *param bLength the length in bytes of the parameter data in bArray

//

public static void install(byte bArray[], short bOffset, byte bLength) throws ISOException {

// create and register applet

HelloWorld HelloWorldApplet = new HelloWorld();

HelloWorldApplet.register();

}

//

// Process toolkit events

// *param event the type of event to be processed

// *exception ToolkitException

//

public void processToolkit(byte event) throws ToolkitException {

// get the ProactiveHandler system instance

ProactiveHandler proHdlr = ProactiveHandler.getTheHandler();

if (event == EVENT_MENU_SELECTION) {

// prepare a Display Text command

proHdlr.init((byte) PRO_CMD_DISPLAY_TEXT, (byte)CMD_QUALIFIER, (byte)0x02);

proHdlr.appendTLV((byte)(TAG_TEXT_STRING|MASK_COMPREHENSION_REQUIRED), textBuf,

(short)0, (short)textBuf.length);

proHdlr.send();

}

}

}

See Also:



Registry, ToolkitException, ToolkitConstants

Constructor Index

ToolkitApplet()

Only this class's install method should create the ToolkitApplet object.

Method Index

processToolkit(byte)

This method is the standard entry point of a Toolkit applet and shall manage the currentToolkit event, as indicated in the event table.

registerToolkit()

This method is used by the Toolkit applet to register this applet instance with the Toolkitframework and to get the reference of the associated Registry object.

Constructors

ToolkitApplet protected ToolkitApplet()


Methods

registerToolkit protected final Registry registerToolkit() throws ToolkitException

This method is used by the Toolkit applet to register this applet instance with the Toolkitframework and to get the reference of the associated Registry object. At least on event shallbe registered. Other events will be registered with the setEvent() method.

Returns:

reference to a Registry object


REGISTRY_ERROR in case of register error

processToolkit public abstract void processToolkit(byte event) throws ToolkitException



This method is the standard entry point of a Toolkit applet and shall manage the current Toolkitevent, as indicated in the event table.

Parameters:

event - the type of event to be processed


in case of error



Interface sim.toolkit.ToolkitConstantspublic interface ToolkitConstants

ToolkitConstants encapsulates constants related to the Toolkit applets.

Variable Index

EVENT_CALL_CONTROL_BY_SIM

Event Constant: Call Control by SIM event

EVENT_CARD_RESET

Event Constant: Card electrical reset event

EVENT_EVENT_DOWNLOAD_CALL_CONNECTED

Event Constant: Event Download event - Call connected type

EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED

Event Constant: Event Download event - Call disconnected type

EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE

Event Constant: Event Download event - Idle screen available type

EVENT_EVENT_DOWNLOAD_LOCATION_STATUS

Event Constant: Event Download event - Location status type

EVENT_EVENT_DOWNLOAD_MT_CALL

Event Constant: Event Download event - MT call type

EVENT_EVENT_DOWNLOAD_USER_ACTIVITY

Event Constant: Event Download event - User activity type

EVENT_FORMATTED_SMS_PP

Event Constant: SMS-PP Data Download (03.48 formatted) event

EVENT_MENU_SELECTION

Event Constant: Menu Selection event

EVENT_MENU_SELECTION_HELP_REQUEST

Event Constant: Menu Selection Help Request event

Interface sim.toolkit.ToolkitConstants 62

EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM

Event Constant: MO Short Message Control by SIM event

EVENT_PROFILE_DOWNLOAD

Event Constant: Profile Download event

EVENT_PROPRIETARY_EVENT

Event Constant: Proprietary event

EVENT_STATUS_COMMAND

Event Constant: Status APDU command event

EVENT_UNFORMATTED_SMS_CB

Event Constant: Cell Broadcast Data Download event

EVENT_UNFORMATTED_SMS_PP

Event Constant: Unformatted SMS-PP event

EVENT_UNRECOGNIZED_ENVELOPE

Event Constant: Unrecognized Envelope event

FOUND_CR_NOT_SET

constant: result of the findTLV method

FOUND_CR_SET


MASK_COMPREHENSION_REQUIRED

Constant: mask to add to any tag to set the CR flag

NOT_FOUND


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



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



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



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



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_FORMATTED_SMS_PP public static final byte EVENT_FORMATTED_SMS_PP


EVENT_UNFORMATTED_SMS_PP public static final byte EVENT_UNFORMATTED_SMS_PP


EVENT_UNFORMATTED_SMS_CB public static final byte EVENT_UNFORMATTED_SMS_CB


EVENT_MENU_SELECTION public static final byte EVENT_MENU_SELECTION


EVENT_MENU_SELECTION_HELP_REQUEST public static final byte EVENT_MENU_SELECTION_HELP_REQUEST


EVENT_CALL_CONTROL_BY_SIM public static final byte EVENT_CALL_CONTROL_BY_SIM


EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM public static final byte EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM




EVENT_EVENT_DOWNLOAD_MT_CALL public static final byte EVENT_EVENT_DOWNLOAD_MT_CALL


EVENT_EVENT_DOWNLOAD_CALL_CONNECTED public static final byte EVENT_EVENT_DOWNLOAD_CALL_CONNECTED


EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED public static final byte EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED


EVENT_EVENT_DOWNLOAD_LOCATION_STATUS public static final byte EVENT_EVENT_DOWNLOAD_LOCATION_STATUS


EVENT_EVENT_DOWNLOAD_USER_ACTIVITY public static final byte EVENT_EVENT_DOWNLOAD_USER_ACTIVITY


EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE public static final byte EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE


EVENT_UNRECOGNIZED_ENVELOPE public static final byte EVENT_UNRECOGNIZED_ENVELOPE


EVENT_PROPRIETARY_EVENT public static final byte EVENT_PROPRIETARY_EVENT


EVENT_CARD_RESET public static final byte EVENT_CARD_RESET


EVENT_STATUS_COMMAND public static final byte EVENT_STATUS_COMMAND


TAG_COMMAND_DETAILS public static final byte TAG_COMMAND_DETAILS


TAG_DEVICE_IDENTITIES



public static final byte TAG_DEVICE_IDENTITIES


TAG_RESULT public static final byte TAG_RESULT


TAG_DURATION public static final byte TAG_DURATION


TAG_ALPHA_IDENTIFIER public static final byte TAG_ALPHA_IDENTIFIER


TAG_ADDRESS public static final byte TAG_ADDRESS


TAG_CAPABILITY_CONFIGURATION_PARAMETERS public static final byte TAG_CAPABILITY_CONFIGURATION_PARAMETERS


TAG_CALLED_PARTY_SUBADDRESS public static final byte TAG_CALLED_PARTY_SUBADDRESS


TAG_SS_STRING public static final byte TAG_SS_STRING


TAG_USSD_STRING public static final byte TAG_USSD_STRING


TAG_SMS_TPDU public static final byte TAG_SMS_TPDU


TAG_CELL_BROADCAST_PAGE public static final byte TAG_CELL_BROADCAST_PAGE


TAG_TEXT_STRING public static final byte TAG_TEXT_STRING




TAG_TONE public static final byte TAG_TONE


TAG_ITEM public static final byte TAG_ITEM


TAG_ITEM_IDENTIFIER public static final byte TAG_ITEM_IDENTIFIER


TAG_RESPONSE_LENGTH public static final byte TAG_RESPONSE_LENGTH


TAG_FILE_LIST public static final byte TAG_FILE_LIST


TAG_LOCATION_INFORMATION public static final byte TAG_LOCATION_INFORMATION


TAG_IMEI public static final byte TAG_IMEI


TAG_HELP_REQUEST public static final byte TAG_HELP_REQUEST


TAG_NETWORK_MEASUREMENT_RESULTS public static final byte TAG_NETWORK_MEASUREMENT_RESULTS


TAG_DEFAULT_TEXT public static final byte TAG_DEFAULT_TEXT


TAG_ITEMS_NEXT_ACTION_INDICATOR public static final byte TAG_ITEMS_NEXT_ACTION_INDICATOR




TAG_EVENT_LIST public static final byte TAG_EVENT_LIST


TAG_CAUSE public static final byte TAG_CAUSE


TAG_LOCATION_STATUS public static final byte TAG_LOCATION_STATUS


TAG_TRANSACTION_IDENTIFIER public static final byte TAG_TRANSACTION_IDENTIFIER


TAG_BCCH_CHANNEL_LIST public static final byte TAG_BCCH_CHANNEL_LIST


TAG_CALL_CONTROL_REQUESTED_ACTION public static final byte TAG_CALL_CONTROL_REQUESTED_ACTION


MASK_COMPREHENSION_REQUIRED public static final byte MASK_COMPREHENSION_REQUIRED


NOT_FOUND public static final byte NOT_FOUND


FOUND_CR_SET public static final byte FOUND_CR_SET


FOUND_CR_NOT_SET public static final byte FOUND_CR_NOT_SET


PRO_CMD_REFRESH public static final byte PRO_CMD_REFRESH


PRO_CMD_MORE_TIME



public static final byte PRO_CMD_MORE_TIME


PRO_CMD_POLL_INTERVAL public static final byte PRO_CMD_POLL_INTERVAL


PRO_CMD_POLLING_OFF public static final byte PRO_CMD_POLLING_OFF


PRO_CMD_SET_UP_EVENT_LIST public static final byte PRO_CMD_SET_UP_EVENT_LIST


PRO_CMD_SET_UP_CALL public static final byte PRO_CMD_SET_UP_CALL


PRO_CMD_SEND_SS public static final byte PRO_CMD_SEND_SS


PRO_CMD_SEND_USSD public static final byte PRO_CMD_SEND_USSD


PRO_CMD_SEND_SHORT_MESSAGE public static final byte PRO_CMD_SEND_SHORT_MESSAGE


PRO_CMD_PLAY_TONE public static final byte PRO_CMD_PLAY_TONE


PRO_CMD_DISPLAY_TEXT public static final byte PRO_CMD_DISPLAY_TEXT


PRO_CMD_GET_INKEY public static final byte PRO_CMD_GET_INKEY


PRO_CMD_GET_INPUT public static final byte PRO_CMD_GET_INPUT




PRO_CMD_SELECT_ITEM public static final byte PRO_CMD_SELECT_ITEM


PRO_CMD_SET_UP_MENU public static final byte PRO_CMD_SET_UP_MENU


PRO_CMD_PROVIDE_LOCAL_INFORMATION public static final byte PRO_CMD_PROVIDE_LOCAL_INFORMATION




Class sim.toolkit.ToolkitExceptionjava.lang.Object | +----java.lang.Throwable | +----java.lang.Exception | +----java.lang.RuntimeException | +----javacard.framework.CardRuntimeException | +----sim.toolkit.ToolkitException

public class ToolkitException

extends CardRuntimeException

This class extends the Throwable class and allows the classes of this package to throw specific exceptions incase of problems.

Table ToolkitException

reason Description

BUFFER_OVERFLOW Data larger than storage buffer

HANDLER_NOT_AVAILABLE Handler cannot be accessed (e.g. busy)

PROACTIVE_NOT_SUPPORTED Proactive SIM not supported by ME

UNAVAILABLE_ELEMENT No available element in the handler buffer

INVALID_TAR TAR already used

ENTRY_NOT_FOUND Menu entry not found

REGISTRY_ERROR Error in the registry information

EVENT_NOT_SUPPORTED Event code not supported

EVENT_ALREADY_REGISTERED Event already registered for limited events(e.g Call Control)

Variable Index

BUFFER_OVERFLOW

Constant: reason code for buffer overflow

ENTRY_NOT_FOUND

Constant: reason code for a non-existent menu entry

EVENT_ALREADY_REGISTERED

Class sim.toolkit.ToolkitException 74

Constant: reason code for event already registered (e.g Call Control)

EVENT_NOT_SUPPORTED

Constant: reason code for event code not supported

HANDLER_NOT_AVAILABLE

Constant: reason code for Handler cannot be accessed (e.g.

INVALID_TAR

Constant: reason code for TAR already used

PROACTIVE_NOT_SUPPORTED

Constant: reason code for Proactive command not supported by ME

REGISTRY_ERROR

Constant: reason code for error in the registry information

UNAVAILABLE_ELEMENT

Constant: reason code for unavailable element in the handler buffer

Constructor Index

ToolkitException(short)

Construct a ToolkitException instance with the specified reason.

Method Index

throwIt(short)

Throws the JCRE instance of the ToolkitException class with the specified reason.

Variables

BUFFER_OVERFLOW public static final short BUFFER_OVERFLOW


HANDLER_NOT_AVAILABLE public static final short HANDLER_NOT_AVAILABLE

Constant: reason code for Handler cannot be accessed (e.g. busy)

PROACTIVE_NOT_SUPPORTED



public static final short PROACTIVE_NOT_SUPPORTED


UNAVAILABLE_ELEMENT public static final short UNAVAILABLE_ELEMENT


INVALID_TAR public static final short INVALID_TAR


ENTRY_NOT_FOUND public static final short ENTRY_NOT_FOUND


REGISTRY_ERROR public static final short REGISTRY_ERROR


EVENT_NOT_SUPPORTED public static final short EVENT_NOT_SUPPORTED


EVENT_ALREADY_REGISTERED public static final short EVENT_ALREADY_REGISTERED


Constructors

ToolkitException public ToolkitException(short reason)

Construct a ToolkitException instance with the specified reason. To conserve on resourcesuse throwIt() method to re-use the JCRE instance of this class.

Parameters:

reason - the reason for the exception

Methods throwIt public static void throwIt(short reason) throws ToolkitException




Parameters:

reason - the reason for the exception.


always



Index of all Fields and Methods

A

AC_NOT_FULFILLED . Static variable in class sim.access.SIMViewException


appendArray(byte[], short, short). Method in class sim.toolkit.EditHandler


appendTLV(byte, byte). Method in class sim.toolkit.EditHandler


appendTLV(byte, byte, byte). Method in class sim.toolkit.EditHandler


appendTLV(byte, byte, byte[], short, short). Method in class sim.toolkit.EditHandler


appendTLV(byte, byte[], short, short). Method in class sim.toolkit.EditHandler


B

BUFFER_OVERFLOW. Static variable in class sim.toolkit.ToolkitException


C

changeMenuEntry(byte, byte[], short, short, byte, boolean). Method in class sim.toolkit.Registry

Change the value of a menu entry.

check(byte). Static method in class sim.toolkit.MEProfile

Index of all Fields and Methods 78

Check a facility in the handset profile.

check(byte[], short, short). Static method in class sim.toolkit.MEProfile

Check a set of facilities in the handset profile.

clear(). Method in class sim.toolkit.EditHandler


clearEvent(byte). Method in class sim.toolkit.Registry


compareValue(short, byte[], short, short). Method in class sim.toolkit.ViewHandler


copyAdditionalInformation(byte[], short, short). Method in classsim.toolkit.ProactiveResponseHandler


copyTextString(byte[], short). Method in class sim.toolkit.ProactiveResponseHandler

Copy the text string value from the first Text String TLV element of the current responsedata field.

copyValue(short, byte[], short, short). Method in class sim.toolkit.ViewHandler


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


D

disableMenuEntry(byte). Method in class sim.toolkit.Registry




E

EditHandler(byte[], short, short). Constructor for class sim.toolkit.EditHandler


enableMenuEntry(byte). Method in class sim.toolkit.Registry


ENTRY_NOT_FOUND. Static variable in class sim.toolkit.ToolkitException


EVENT_ALREADY_REGISTERED. Static variable in class sim.toolkit.ToolkitException


EVENT_CALL_CONTROL_BY_SIM. Static variable in interface sim.toolkit.ToolkitConstants


EVENT_CARD_RESET. Static variable in interface sim.toolkit.ToolkitConstants


EVENT_EVENT_DOWNLOAD_CALL_CONNECTED. Static variable in interfacesim.toolkit.ToolkitConstants


EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED. Static variable in interfacesim.toolkit.ToolkitConstants


EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE. Static variable in interfacesim.toolkit.ToolkitConstants


EVENT_EVENT_DOWNLOAD_LOCATION_STATUS. Static variable in interfacesim.toolkit.ToolkitConstants


EVENT_EVENT_DOWNLOAD_MT_CALL. Static variable in interfacesim.toolkit.ToolkitConstants


EVENT_EVENT_DOWNLOAD_USER_ACTIVITY. Static variable in interfacesim.toolkit.ToolkitConstants




EVENT_FORMATTED_SMS_PP. Static variable in interface sim.toolkit.ToolkitConstants


EVENT_MENU_SELECTION. Static variable in interface sim.toolkit.ToolkitConstants


EVENT_MENU_SELECTION_HELP_REQUEST. Static variable in interfacesim.toolkit.ToolkitConstants


EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM. Static variable in interfacesim.toolkit.ToolkitConstants


EVENT_NOT_SUPPORTED. Static variable in class sim.toolkit.ToolkitException


EVENT_PROFILE_DOWNLOAD. Static variable in interface sim.toolkit.ToolkitConstants


EVENT_PROPRIETARY_EVENT. Static variable in interface sim.toolkit.ToolkitConstants


EVENT_STATUS_COMMAND. Static variable in interface sim.toolkit.ToolkitConstants


EVENT_UNFORMATTED_SMS_CB. Static variable in interface sim.toolkit.ToolkitConstants


EVENT_UNFORMATTED_SMS_PP. Static variable in interface sim.toolkit.ToolkitConstants


EVENT_UNRECOGNIZED_ENVELOPE. Static variable in interface sim.toolkit.ToolkitConstants


F



FID_DF_DCS. Static variable in interface sim.access.SIMView


FID_DF_GSM. Static variable in interface sim.access.SIMView


FID_DF_TELECOM . Static variable in interface sim.access.SIMView


FID_MF . Static variable in interface sim.access.SIMView


FILE_INCONSISTENT. Static variable in class sim.access.SIMViewException


FILE_NOT_FOUND. Static variable in class sim.access.SIMViewException


findAndCompareValue(byte, byte, short, byte[], short, short). Method in classsim.toolkit.ViewHandler


findAndCompareValue(byte, byte[], short). Method in class sim.toolkit.ViewHandler


findAndCopyValue(byte, byte, short, byte[], short, short). Method in class sim.toolkit.ViewHandler


findAndCopyValue(byte, byte[], short). Method in class sim.toolkit.ViewHandler


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


FOUND_CR_SET. Static variable in interface sim.toolkit.ToolkitConstants




G

getAdditionalInformationLength(). Method in class sim.toolkit.ProactiveResponseHandler

Return the length of the additional information field from the first Result TLV element of thecurrent response data field.

getDurationInterval(). Method in class sim.toolkit.ProactiveResponseHandler


getDurationUnit(). Method in class sim.toolkit.ProactiveResponseHandler


getEnvelopeTag(). Method in class sim.toolkit.EnvelopeHandler


getGeneralResult(). Method in class sim.toolkit.ProactiveResponseHandler


getItemIdentifier(). Method in class sim.toolkit.EnvelopeHandler


getItemIdentifier(). Method in class sim.toolkit.ProactiveResponseHandler


getLength(). Method in class sim.toolkit.EditHandler


getTextStringCodingScheme(). Method in class sim.toolkit.ProactiveResponseHandler

Return the data coding scheme byte from the first Text String TLV element of the currentresponse data field.

getTextStringLength(). Method in class sim.toolkit.ProactiveResponseHandler

Return the text string length value from the first Text String TLV element of the currentresponse data field.

getTheHandler(). Static method in class sim.toolkit.EnvelopeHandler



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


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


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.



init (byte, byte, byte). Method in class sim.toolkit.ProactiveHandler

Initialize the next Proactive command with Command Details and Device Identities TLV.The source device is always the SIM card.

initDisplayText(byte, byte, byte[], short, short). Method in class sim.toolkit.ProactiveHandler

Build a Display Text Proactive command without sending the command.

initGetInkey(byte, byte, byte[], short, short). Method in class sim.toolkit.ProactiveHandler

Build a Get Inkey Proactive command without sending the command.

initGetInput(byte, byte, byte[], short, short, short, short). Method in classsim.toolkit.ProactiveHandler

Initialize the building of a Get Input Proactive command.

initPollInterval (byte, short). Method in class sim.toolkit.ProactiveHandler

Build a Poll Interval Proactive command without sending the command.

INTERNAL_ERROR. Static variable in class sim.access.SIMViewException


INVALID_MODE . Static variable in class sim.access.SIMViewException


INVALID_TAR . Static variable in class sim.toolkit.ToolkitException


invalidate(). Method in interface sim.access.SIMView


INVALIDATION_STATUS_CONTRADICTION. Static variable in classsim.access.SIMViewException


isEventSet(byte). Method in class sim.toolkit.Registry


M



MASK_COMPREHENSION_REQUIRED. Static variable in interface sim.toolkit.ToolkitConstants


MAX_VALUE_REACHED. Static variable in class sim.access.SIMViewException


MODE_ABSOLUTE. Static variable in interface sim.access.SIMView


MODE_CURRENT. Static variable in interface sim.access.SIMView


MODE_NEXT. Static variable in interface sim.access.SIMView


MODE_PREVIOUS. Static variable in interface sim.access.SIMView


N

NO_EF_SELECTED. Static variable in class sim.access.SIMViewException


NOT_FOUND. Static variable in interface sim.toolkit.ToolkitConstants


O

OUT_OF_BUFFER_BOUNDARIES. Static variable in class sim.access.SIMViewException


OUT_OF_FILE_BOUNDARIES. Static variable in class sim.access.SIMViewException


OUT_OF_RECORD_BOUNDARIES. Static variable in class sim.access.SIMViewException




P

PATTERN_NOT_FOUND. Static variable in class sim.access.SIMViewException


PATTERN_SIZE_INCONSISTENT. Static variable in class sim.access.SIMViewException


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


PRO_CMD_GET_INKEY. Static variable in interface sim.toolkit.ToolkitConstants


PRO_CMD_GET_INPUT. Static variable in interface sim.toolkit.ToolkitConstants


PRO_CMD_MORE_TIME. Static variable in interface sim.toolkit.ToolkitConstants


PRO_CMD_PLAY_TONE. Static variable in interface sim.toolkit.ToolkitConstants


PRO_CMD_POLL_INTERVAL. Static variable in interface sim.toolkit.ToolkitConstants


PRO_CMD_POLLING_OFF. Static variable in interface sim.toolkit.ToolkitConstants


PRO_CMD_PROVIDE_LOCAL_INFORMATION. Static variable in interfacesim.toolkit.ToolkitConstants




PRO_CMD_REFRESH. Static variable in interface sim.toolkit.ToolkitConstants


PRO_CMD_SELECT_ITEM. Static variable in interface sim.toolkit.ToolkitConstants


PRO_CMD_SEND_SHORT_MESSAGE. Static variable in interface sim.toolkit.ToolkitConstants


PRO_CMD_SEND_SS. Static variable in interface sim.toolkit.ToolkitConstants


PRO_CMD_SEND_USSD. Static variable in interface sim.toolkit.ToolkitConstants


PRO_CMD_SET_UP_CALL. Static variable in interface sim.toolkit.ToolkitConstants


PRO_CMD_SET_UP_EVENT_LIST. Static variable in interface sim.toolkit.ToolkitConstants


PRO_CMD_SET_UP_MENU. Static variable in interface sim.toolkit.ToolkitConstants


PROACTIVE_NOT_SUPPORTED. Static variable in class sim.toolkit.ToolkitException


processToolkit(byte). Method in class sim.toolkit.ToolkitApplet

This method is the standard entry point of a Toolkit applet and shall manage the currentToolkit event, as indicated in the event table.

R

readBinary(short, byte[], short, short). Method in interface sim.access.SIMView




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


registerToolkit(). Method in class sim.toolkit.ToolkitApplet

This method is used by the Toolkit applet to register this applet instance with the Toolkitframework and to get the reference of the associated Registry object.

REGISTRY_ERROR. Static variable in class sim.toolkit.ToolkitException


rehabilitate(). Method in interface sim.access.SIMView


S

seek(byte, byte[], short, short). Method in interface sim.access.SIMView


SEEK_FROM_BEGINNING_FORWARD. Static variable in interface sim.access.SIMView


SEEK_FROM_END_BACKWARD. Static variable in interface sim.access.SIMView


SEEK_FROM_NEXT_FORWARD. Static variable in interface sim.access.SIMView


SEEK_FROM_PREVIOUS_BACKWARD. Static variable in interface sim.access.SIMView


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).



select(short). Method in interface sim.access.SIMView

SELECT command as defined in GSM 11.11 standard.This SELECT method allows to update the current file without handling the Select ResponseBy default, the MF is selected at the beginning of each applet activation (current file = MF).

send(). Method in class sim.toolkit.ProactiveHandler


setDataDownloadTAR(byte[], short). Method in class sim.toolkit.Registry

Register the SMS-PP Data Download TAR.The TAR (Toolkit Application Reference) will be used to identify the target applet in case offormatted short message.

setEvent(byte). Method in class sim.toolkit.Registry


setEventList(byte[], short, short). Method in class sim.toolkit.Registry


SIMSystem(). Constructor for class sim.access.SIMSystem

SIMViewException(short). Constructor for class sim.access.SIMViewException

Constructs a SIMViewException object.

status(byte[], short, short). Method in interface sim.access.SIMView

STATUS command as defined in GSM 11.11 standard.This method returns the FCI (File Control Information) of the current DF (or MF) of thecalling applet.

T

TAG_ADDRESS. Static variable in interface sim.toolkit.ToolkitConstants


TAG_ALPHA_IDENTIFIER . Static variable in interface sim.toolkit.ToolkitConstants


TAG_BCCH_CHANNEL_LIST. Static variable in interface sim.toolkit.ToolkitConstants




TAG_CALL_CONTROL_REQUESTED_ACTION. Static variable in interfacesim.toolkit.ToolkitConstants


TAG_CALLED_PARTY_SUBADDRESS. Static variable in interface sim.toolkit.ToolkitConstants


TAG_CAPABILITY_CONFIGURATION_PARAMETERS. Static variable in interfacesim.toolkit.ToolkitConstants


TAG_CAUSE. Static variable in interface sim.toolkit.ToolkitConstants


TAG_CELL_BROADCAST_PAGE. Static variable in interface sim.toolkit.ToolkitConstants


TAG_COMMAND_DETAILS. Static variable in interface sim.toolkit.ToolkitConstants


TAG_DEFAULT_TEXT. Static variable in interface sim.toolkit.ToolkitConstants


TAG_DEVICE_IDENTITIES . Static variable in interface sim.toolkit.ToolkitConstants


TAG_DURATION. Static variable in interface sim.toolkit.ToolkitConstants


TAG_EVENT_LIST. Static variable in interface sim.toolkit.ToolkitConstants


TAG_FILE_LIST . Static variable in interface sim.toolkit.ToolkitConstants


TAG_HELP_REQUEST. Static variable in interface sim.toolkit.ToolkitConstants


TAG_IMEI . Static variable in interface sim.toolkit.ToolkitConstants




TAG_ITEM. Static variable in interface sim.toolkit.ToolkitConstants


TAG_ITEM_IDENTIFIER . Static variable in interface sim.toolkit.ToolkitConstants


TAG_ITEMS_NEXT_ACTION_INDICATOR. Static variable in interfacesim.toolkit.ToolkitConstants


TAG_LOCATION_INFORMATION. Static variable in interface sim.toolkit.ToolkitConstants


TAG_LOCATION_STATUS. Static variable in interface sim.toolkit.ToolkitConstants


TAG_NETWORK_MEASUREMENT_RESULTS. Static variable in interfacesim.toolkit.ToolkitConstants


TAG_RESPONSE_LENGTH. Static variable in interface sim.toolkit.ToolkitConstants


TAG_RESULT. Static variable in interface sim.toolkit.ToolkitConstants


TAG_SMS_TPDU. Static variable in interface sim.toolkit.ToolkitConstants


TAG_SS_STRING. Static variable in interface sim.toolkit.ToolkitConstants


TAG_TEXT_STRING. Static variable in interface sim.toolkit.ToolkitConstants


TAG_TONE. Static variable in interface sim.toolkit.ToolkitConstants


TAG_TRANSACTION_IDENTIFIER. Static variable in interface sim.toolkit.ToolkitConstants




TAG_USSD_STRING. Static variable in interface sim.toolkit.ToolkitConstants


throwIt(short). Static method in class sim.access.SIMViewException


throwIt(short). Static method in class sim.toolkit.ToolkitException


ToolkitApplet(). Constructor for class sim.toolkit.ToolkitApplet


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


updateBinary(short, byte[], short, short). Method in interface sim.access.SIMView


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




GSM 03.19

Documents

Transcript of GSM 03.19