ETSI TS 102 241 V11.1.0 (2015-11)

Smart Cards; UICC Application Programming Interface (UICC API) for Java Card (TM) (Release 11)

RTS/SCP-T0310vb10

General Information

• Status: Published
• Publication Date: 02-Nov-2015
• Technical Committee: SET TEC - SET-TEC
• Current Stage: 12 - Completion
• Due Date: 16-Oct-2015
• Completion Date: 03-Nov-2015
• Mandate: M/441

Standards Content (Sample)

TECHNICAL SPECIFICATION
Smart Cards;
UICC Application Programming Interface (UICC API)
for Java Card™
(Release 11)
�
Release 11 2 ETSI TS 102 241 V11.1.0 (2015-11)

Reference
RTS/SCP-T0310vb10
Keywords
API, smart card
ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE

Tel.: [phone]  Fax: [phone]

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

Important notice
The present document can be downloaded from:
http://www.etsi.org/standards-search
The present document may be made available in electronic versions and/or in print. The content of any electronic and/or
print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any
existing or perceived difference in contents between such versions and/or in print, the only prevailing document is the
print of the Portable Document Format (PDF) version kept on a specific network drive within ETSI Secretariat.
Users of the present document should be aware that the document may be subject to revision or change of status.
Information on the current status of this and other ETSI documents is available at
http://portal.etsi.org/tb/status/status.asp
If you find errors in the present document, please send your comment to one of the following services:
https://portal.etsi.org/People/CommiteeSupportStaff.aspx
Copyright Notification
No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying
and microfilm except as authorized by written permission of ETSI.
The content of the PDF version shall not be modified without the written authorization of ETSI.
The copyright and the foregoing restriction extend to reproduction in all media.

© European Telecommunications Standards Institute 2015.
All rights reserved.
TM TM TM
DECT , PLUGTESTS , UMTS and the ETSI logo are Trade Marks of ETSI registered for the benefit of its Members.
TM
3GPP and LTE™ are Trade Marks of ETSI registered for the benefit of its Members and
of the 3GPP Organizational Partners.
GSM® and the GSM logo are Trade Marks registered and owned by the GSM Association.
ETSI
Release 11 3 ETSI TS 102 241 V11.1.0 (2015-11)
Contents
Intellectual Property Rights . 5
Foreword . 5
Modal verbs terminology . 5
1 Scope . 6
2 References . 6
2.1 Normative references . 6
2.2 Informative references . 7
3 Definitions and abbreviations . 7
3.1 Definitions . 7
3.2 Abbreviations . 8
4 Description . 8
4.0 Purpose . 8
4.1 UICC Java Card™ architecture . 9
5 File access API . 10
5.0 Introduction . 10
5.1 FileView objects . 10
5.2 FileView operations . 11
5.3 BERTLVFileView operations . 11
6 Toolkit API and CAT Runtime Environment . 11
6.0 Introduction . 11
6.1 Applet triggering . 11
6.1.0 Triggering mechanism . 11
6.1.1 Exception handling . 12
6.2 Definition of events . 13
6.3 Registration . 19
6.4 Proactive command handling . 19
6.5 Envelope response handling . 20
6.6 System handler management . 20
6.7 CAT Runtime Environment behaviour. 22
6.7.0 Basic rules . 22
6.7.1 System proactive commands. 23
6.7.1.0 Overall behaviour . 23
6.7.1.1 SET UP MENU . 23
6.7.1.2 SET UP EVENT LIST . 24
6.7.1.3 POLL INTERVAL and POLLING OFF . 24
6.7.2 UICC memory reliability monitoring . 24
7 Toolkit applet . 25
7.1 Applet loading . 25
7.2 Data and function sharing . 25
7.3 Package, applet and object deletion . 25
8 UICC and ADF File System Administration API . 25
8.0 Overview . 25
8.1 AdminFileView objects . 25
8.2 AdminFileView operations . 26
9 UICC Java Card™ Services . 26
9.0 Introduction . 26
9.1 High update arrays. 26
Annex A (normative): Java Card™ UICC API . 28
Annex B (normative): Java Card™ UICC API identifiers . 29
ETSI
Release 11 4 ETSI TS 102 241 V11.1.0 (2015-11)
Annex C (normative): UICC API package version management . 30
Annex D (informative): Menu order example . 31
D.0 Preamble . 31
D.1 State after initialization . 31
D.2 Some application installation later . 31
D.3 Installation of application A with position of menu entry set to 3 . 31
D.4 Installation of application B with position of menu entry set to 3 . 31
D.5 Installation of application C with position of menu entry set to 2 and 3 . 32
D.5.1 Insert at position 2 . 32
D.5.2 Insert at position 3 . 32
D.6 Installation of application D with position of menu entry set to "00" . 32
D.7 Installation of application E with position of menu entry set to 20 . 33
D.8 Disabling/Locking of application legacy1 and application A with menu entries at position 1
respectively 6 . 33
D.9 Re-enabling/Unlocking of application legacy1 and application A with menu entries at position 1
respectively 6 . 33
D.10 Deletion of application A with menu entry at position 6 . 34
Annex E (informative): Change history . 35
History . 38

ETSI
Release 11 5 ETSI TS 102 241 V11.1.0 (2015-11)
Intellectual Property Rights
IPRs essential or potentially essential to the present document may have been declared to ETSI. The information
pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found
in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in
respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web
server (http://ipr.etsi.org).
Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee
can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web
server) which are, or may be, or may become, essential to the present document.
Foreword
This Technical Specification (TS) has been produced by ETSI Technical Committee Smart Card Platform (SCP).
The present document details the stage 1 aspects (overall service description) for the support of an "Application
Programming Interface and Loader Requirements" [11].
The contents of the present document are subject to continuing work within TC SCP and may change following formal
TC SCP approval. If TC SCP decides to modify the contents of the present document, it will be re-released by TC SCP
with an identifying change of release date and an increase in version number as follows:
Version x.y.z
where:
x: the first digit:
1 presented to TC SCP for information;
2 presented to TC SCP for approval;
3 or greater indicates TC SCP approved document under change control.
y: the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections,
updates, etc.
z: the third digit is incremented when editorial only changes have been incorporated in the document.
Modal verbs terminology
In the present document "shall", "shall not", "should", "should not", "may", "need not", "will", "will not", "can" and
"cannot" are to be interpreted as described in clause 3.2 of the ETSI Drafting Rules (Verbal forms for the expression of
provisions).
"must" and "must not" are NOT allowed in ETSI deliverables except when used in direct citation.
ETSI
Release 11 6 ETSI TS 102 241 V11.1.0 (2015-11)
1 Scope
The present document defines the stage two description of the "Application Programming Interface and Loader
Requirements" [11] internal to the UICC.
This stage two describes the functional capabilities and the information flow for the UICC API implemented on the
Java Card™ Platform, 3.0.1 Classic Edition [2], [3] and [4].
The present document includes information applicable to network operators, service providers and UICC, server and
database manufacturers.
2 References
2.1 Normative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
reference document (including any amendments) applies.
Referenced documents which are not found to be publicly available in the expected location might be found at
http://docbox.etsi.org/Reference.
• In the case of a reference to a TC SCP document, a non-specific reference implicitly refers to the latest version
of that document in the same Release as the present document.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are necessary for the application of the present document.
[1] Void.
[2] ORACLE: "Application Programming Interface, Java Card™ Platform, 3.0.1 Classic Edition".
[3] ORACLE: "Runtime Environment Specification, Java Card™ Platform, 3.0.1 Classic Edition".
[4] ORACLE: "Virtual Machine Specification Java Card™ Platform, 3.0.1 Classic Edition".
NOTE: ORACLE Java Card™ Specifications can be downloaded at
http://docs.oracle.com/javame/javacard/javacard.html.
[5] ETSI TS 101 220: "Smart Cards; ETSI numbering system for telecommunication application
providers".
[6] ETSI TS 102 221: "Smart Cards; UICC-Terminal interface; Physical and logical characteristics".
[7] ETSI TS 102 223: "Smart Cards; Card Application Toolkit (CAT)".
[8] ETSI TS 102 222: "Integrated Circuit Cards (ICC); Administrative commands for
telecommunications applications".
[9] ETSI TS 102 225: "Smart Cards; Secured packet structure for UICC based applications".
[10] ETSI TS 102 226: "Smart Cards; Remote APDU structure for UICC based applications".
[11] ETSI TS 102 240: "Smart Cards; UICC Application Programming Interface and Loader
Requirements; Service description".
[12] ETSI TS 123 040 (V6.6.0): "Digital cellular telecommunications system (Phase 2+); Universal
Mobile Telecommunications System (UMTS); Technical realization of Short Message Service
(SMS) (3GPP TS 23.040 version 6.6.0 Release 6)".
[13] ETSI TS 102 241: "Smart Cards; UICC Application Programming Interface (UICC API) for Java
Card™".
ETSI
Release 11 7 ETSI TS 102 241 V11.1.0 (2015-11)
[14] ETSI TS 102 671: "Smart Cards; Machine to Machine UICC; Physical and logical characteristics".
[15] GlobalPlatform: "GlobalPlatform Card Specification, Version 2.2.1".
NOTE: See http://www.globalplatform.org/.
[16] GlobalPlatform: "Java Card API and Export File for Card Specification, v2.2.1",
(org.globalplatform) v1.5.
NOTE: See http://www.globalplatform.org/.
2.2 Informative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
reference document (including any amendments) applies.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are not necessary for the application of the present document but they assist the
user with regard to a particular subject area.
Not applicable.
3 Definitions and abbreviations
3.1 Definitions
For the purposes of the present document, the following terms and definitions apply:
applet: application built up using a number of classes which will run under the control of the Java Card™ virtual
machine
bytecode: machine independent code generated by a Java™ compiler and executed by the Java interpreter
class: type that defines the implementation of a particular kind of object
NOTE: A Class definition defines instance and class variables and methods.
framework: defines a set of Application Programming Interface (API) classes for developing applications and for
providing system services to those applications
java: object oriented programming language developed by Sun Microsystems designed to be platform independent
method: piece of executable code that can be invoked, possibly passing it certain values as arguments
NOTE: Every Method definition belongs to some class.
object: principal building block of object oriented programs
NOTE: Each object is a programming unit consisting of data (variables) and functionality (methods).
package: group of classes
NOTE: Packages are declared when writing a Java Card™ program.
toolkit application: application on the UICC card which can be triggered by toolkit events issued by the Terminal and
which can send proactive commands to the terminal
NOTE: These applications can be downloaded via any type of network.
virtual machine: part of the Run-time environment responsible for interpreting the bytecode
ETSI
Release 11 8 ETSI TS 102 241 V11.1.0 (2015-11)
3.2 Abbreviations
For the purposes of the present document, the abbreviations given in ETSI TS 102 221 [6] and the following apply:
ADF Application Dedicated File
AID Application IDentifier
APDU Application Protocol Data Unit
API Application Programming Interface
DF Dedicated File (abbreviation formerly used for Data Field)
EF Elementary File
FFS For Further Study
JCRE Java Card™ Runtime Environment
MF Master File
NAA Network Access Application (e.g. SIM, USIM)
RFM Remote File Management
TLV Tag Length Value
4 Description
4.0 Purpose
The present document describes an API and a Runtime Environment for the UICC platform. This API and the Runtime
Environment allows application programmers to get access to the functions and data described in ETSI TS 102 221 [6]
and ETSI TS 102 223 [7] such that UICC based services can be developed and loaded onto a UICC, quickly and, if
necessarily, remotely, after the card has been issued.
This API is an extension to the "Application Programming Interface, Java Card™ Platform, 3.0.1 Classic Edition" [2],
the Runtime Environment is an extension of the "Runtime Environment Specification, Java Card™ Platform, 3.0.1
Classic Edition" [3].
ETSI
Release 11 9 ETSI TS 102 241 V11.1.0 (2015-11)
4.1 UICC Java Card™ architecture
The overall architecture of the UICC API is based on Java Card™ Platform, 3.0.1 Classic Edition [2], [3] and [4].

UICC File 102 221 based Other Toolkit Applet
System Applications Applications (e .g. Toolkit
Server (e.g . SIM not based on service,
Applet or 102 221 Remote
USIM Applet) Management
Applications,
ADF File Browser
System Server Applications)
TM
Java Card uicc.access uicc.toolkit uicc.system
Packages package package package
TM
Java Card Runtime Environment CAT Runtime Environment
Toolkit Toolkit Triggering
Handlers Registry Entity
Items that are defined in this specification

Figure 1: UICC Java Card™ architecture
Java Card™ Runtime Environment: this is specified in " Runtime Environment Specification, Java Card™ Platform,
3.0.1 Classic Edition" [3] and is able to select any specific applet and transmit to it the process of its APDU.
CAT Runtime Environment: this is the CAT Runtime Environment composed of, the Toolkit Registry, the Toolkit
Handlers and the Triggering Entity. It is an addition to the JCRE.
Toolkit Registry: this is handling all the registration information of the Toolkit applets, and their link to the JCRE
registry.
Toolkit Handlers: this is handling the availability of the system handler and the toolkit protocol (i.e. Toolkit applet
suspension).
UICC File System Server: it contains the File System of the UICC specified in ETSI TS 102 221 [6] (i.e. the EF and
DF under the MF).
ADF File System Server: it contains the files of an ADF as specified in ETSI TS 102 221 [6] (i.e. the EF and DF under
the ADF).
Applets: these derive from javacard.framework.applet and provide the entry points: process, select, deselect, install as
defined in the " Runtime Environment Specification, Java Card™ Platform, 3.0.1 Classic Edition" [3].
Toolkit Applets: are the Java Card™ based implementation of Toolkit Applications, these derive from
javacard.framework.applet, to provide the same entry points, and provide one object implementing the
uicc.toolkit.ToolkitInterface interface, so that these applets can be triggered by an invocation of the processToolkit()
method. The Toolkit applet(s) AID are defined in ETSI TS 101 220 [5].
ETSI
Release 11 10 ETSI TS 102 241 V11.1.0 (2015-11)
Remote Application Management Application: this is handling the loading, installation, management and removal of
applets and packages as specified in ETSI TS 102 226 [10].
Shareable interface: this is defined in the "Runtime Environment Specification, Java Card™ Platform, 3.0.1 Classic
Edition" specifications [2], [3] and [4].
CAT session: card session opened by a terminal supporting proactive UICC, starting with the download of the
Terminal Profile and ending with a subsequent reset or deactivation of the card.
5 File access API
5.0 Introduction
The file access API consists of the uicc.access package, which allows applets to access the file systems of the UICC.
5.1 FileView objects
MF
EF's
e.g.
DF Telecom
ADF 2
ADF 1
DF GSM
Figure 2: Logical structure of FileView
Any applet (not only Toolkit applets) is allowed to retrieve and use a FileView.
A FileView object can be retrieved by invoking one of the getTheFileView() methods defined in the UICCSystem class.
The UICC FileView allows to access the MF and all DFs and EFs that are located under the MF, including DF Telecom
and any access technology specific DF located under the MF, but not the files located under any ADF. This FileView
can be retrieved by invoking the getTheFileView() method from the UICCSystem. The only way to access the DF GSM
is to request the UICC FileView.
An ADF FileView allows to access only the DFs and EFs located under the ADF. It is not possible to access the MF or
any DF or EF located under the MF from an ADF FileView. An ADF FileView can be retrieved by invoking the
getTheFileView(…) method with passing as parameter the full AID of the application owning the ADF.
Each FileView object shall be provided as a permanent JCRE entry point object.
A separate and independent file context shall be associated with each and every FileView object: the operation
performed on files in a given FileView object shall not affect the file context associated with any other FileView object.
This context can be transient or persistent depending on what was required by the applet during the creation of the
FileView object.
Each FileView shall be given the access control privileges associated with the UICC or the corresponding ADF for the
applet. The access control privileges are defined by the UICC access application specific parameters specified in ETSI
TS 102 226 [10]. UICC administrative access application specific parameters shall not apply to objects retrieved from
the uicc.access.UICCSystem class. The access control privileges are verified against the access rules defined in ETSI
TS 102 221 [6] each time a method of the FileView object is invoked.
ETSI
Release 11 11 ETSI TS 102 241 V11.1.0 (2015-11)
The root of the context of a FileView object is the MF for the UICC FileView or the ADF for an ADF FileView.
At the creation of a FileView object, the current DF of the FileView's context is the root. When the transient context of a
FileView is cleared, the current DF becomes the root of the FileView.
5.2 FileView operations
The following functions are provided by the methods defined in the uicc.access.FileView interface see annex A:
• ACTIVATE FILE as defined in ETSI TS 102 222 [8].
• DEACTIVATE FILE as defined in ETSI TS 102 222 [8].
• INCREASE as defined in ETSI TS 102 221 [6].
• READ BINARY as defined in ETSI TS 102 221 [6].
• READ RECORD as defined in ETSI TS 102 221 [6].
• SEARCH RECORD as defined in ETSI TS 102 221 [6].
• SELECT by File ID or by Path as defined in ETSI TS 102 221 [6].
• STATUS as defined in ETSI TS 102 221 [6].
• UPDATE BINARY as defined in ETSI TS 102 221 [6].
• UPDATE RECORD as defined in ETSI TS 102 221 [6].
5.3 BERTLVFileView operations
BER TLV files functions may be optionally supported by an implementation. If supported, an implementation shall
provide the uicc.access.bertlvfile package and the 32-bit integer data type support defined optional in "Virtual Machine
Specification Java Card™ Platform, 3.0.1 Classic Edition" [4] is mandatory.
The interface uicc.access.bertlvfile.BERTLVFileView extends the interface uicc.access.FileView, i.e. objects
implementing the interface BERTLVFileView inherit FileView functionality.
If BER TLV files functions are supported by an implementation, the getTheFileView() and getTheUICCView() methods
defined in the UICCSystem class shall return the reference of an object implementing the BERTLVFileView interface.
The following functions are provided by the methods defined in the uicc.access.bertlvfile.BERTLVFileView interface
see annex A:
• RETRIEVE DATA as defined in ETSI TS 102 221 [6].
• SET DATA as defined in ETSI TS 102 221 [6].
6 Toolkit API and CAT Runtime Environment
6.0 Introduction
The toolkit API consists of the uicc.toolkit package, which allows applets to access the toolkit features defined in ETSI
TS 102 223 [7].
6.1 Applet triggering
6.1.0 Triggering mechanism
The application triggering portion of the CAT Runtime Environment is responsible for the activation of Toolkit applets,
based on the APDU received by the UICC.
ETSI
Event
Release 11 12 ETSI TS 102 241 V11.1.0 (2015-11)
APDU Event Trigger
Translator Triggering Entity Toolkit Applet
Toolkit Registry
Figure 3: Toolkit applet triggering diagram
The Translator converts the information from an incoming APDU into the corresponding Event information.
The Triggering Entity requests the information from the Toolkit Registry, which Toolkit applets are registered to this
Event. The Triggering Entity then triggers the Toolkit applet. The terminal shall not be adversely affected by the
presence of applets on the UICC card. For instance a syntactically correct Envelope shall not result in an error status
word in case of a failure of an applet. The applications seen by the terminal are first level applications (e.g. SIM,
USIM).
The difference between a Java Card™ applet and a Toolkit applet is that the latter does not handle APDUs directly. It
will handle higher-level messages. Furthermore the execution of a method could span over multiple APDUs, in
particular, the proactive protocol commands (Fetch, Terminal Response).
As written above, when a first level application is the selected application and when a Toolkit applet is triggered the
select() method of the Toolkit applet shall not be launched since the Toolkit applet itself is not selected.
The CAT Runtime Environment shall only trigger a Toolkit applet if it is in the selectable state as defined in ETSI
TS 102 226 [10].
The CAT Runtime Environment shall trigger the Toolkit applets according to their priority level assigned at installation
time. The priority level specifies the order of activation of an applet compared to the other applets registered to the same
event. If two or more applets are registered to the same event and have the same priority level, except for the internal
event EVENT_PROACTIVE_HANDLER_AVAILABLE (see clause 6.2), the applets are triggered according to their
installation time (i.e. the most recent applet is activated first). ETSI TS 102 226 [10] defined the priority level coding
and how this parameter is provided to the UICC.
When the CAT Runtime Environment has to trigger several applets on the same event, the next applet is triggered on
the return of the processToolkit() method of the previous Toolkit applet.
6.1.1 Exception handling
A Toolkit applet may throw an exception or an exception can occur during its processing. The CAT Runtime
Environment shall catch any exception type or class and process as described here after.
If more than one applet shall be triggered by the currently processed event all Exceptions shall be caught by the CAT
Runtime Environment and shall not be sent to the terminal. The CAT Runtime Environment shall proceed with the
triggering.
If only one applet shall be triggered by the currently processed event and an ISOException with the following reason
code is thrown it shall be sent to the terminal:
• ISOException with reason code REPLY_BUSY (0x9300).
Other Exceptions shall not be propagated to the terminal, this behaviour may be extended by an access technology
depended specification.
ETSI
Toolkit
Interface(s)
Release 11 13 ETSI TS 102 241 V11.1.0 (2015-11)
6.2 Definition of events
The following events can trigger a Toolkit applet.
Table 1: UICC toolkit event list
Event Name Reserved short value
Not to be used 0
EVENT_PROFILE_DOWNLOAD 1
Reserved by 3GPP 2
Reserved by 3GPP 3
Reserved by 3GPP 4
Reserved by 3GPP 5
Reserved by 3GPP 6
EVENT_MENU_SELECTION 7
EVENT_MENU_SELECTION_HELP_REQUEST 8
EVENT_CALL_CONTROL_BY_NAA 9
Reserved by 3GPP 10
EVENT_TIMER_EXPIRATION 11
EVENT_EVENT_DOWNLOAD_MT_CALL 12
EVENT_EVENT_DOWNLOAD_CALL_CONNECTED 13
EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED 14
EVENT_EVENT_DOWNLOAD_LOCATION_STATUS 15
EVENT_EVENT_DOWNLOAD_USER_ACTIVITY 16
EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE 17
EVENT_EVENT_DOWNLOAD_CARD_READER_STATUS 18
EVENT_STATUS_COMMAND 19
EVENT_EVENT_DOWNLOAD_LANGUAGE_SELECTION 20
EVENT_EVENT_DOWNLOAD_BROWSER_TERMINATION 21
EVENT_EVENT_DOWNLOAD_DATA_AVAILABLE 22
EVENT_EVENT_DOWNLOAD_CHANNEL_STATUS 23
Reserved by 3GPP 24
EVENT_EVENT_DOWNLOAD_ACCESS_TECHNOLOGY_CHANGE 25
EVENT_EVENT_DOWNLOAD_DISPLAY_PARAMETER_CHANGED 26
EVENT_EVENT_DOWNLOAD_LOCAL_CONNECTION 27
EVENT_EVENT_DOWNLOAD_NETWORK_SEARCH_MODE_CHANGE 28
EVENT_EVENT_DOWNLOAD_BROWSING_STATUS 29
Reserved by 3GPP 30
Reserved by 3GPP 31
EVENT_EVENT_DOWNLOAD_HCI_CONNECTIVITY 32
Reserved by 3GPP 33
EVENT_EVENT_DOWNLOAD_FRAMES_INFORMATION_CHANGED 34
EVENT_EVENT_DOWNLOAD_CONTACTLESS_STATE_REQUEST 35
RFU 36 to 118
Reserved by 3GPP 119
Reserved by 3GPP 120
Reserved by 3GPP 121
Reserved by 3GPP 122
EVENT_PROACTIVE_HANDLER_AVAILABLE 123
EVENT_EXTERNAL_FILE_UPDATE 124
EVENT_REMOTE_FILE_UPDATE 125
EVENT_APPLICATION_DESELECT 126
EVENT_FIRST_COMMAND_AFTER_ATR 127
EVENT_EVENT_DOWNLOAD_ACCESS_TECHNOLOGY_CHANGE_ 128
MULTIPLE
EVENT_MEMORY_FAILURE 129
RFU 130 to 32 767
EVENT_UNRECOGNIZED_ENVELOPE -1
Reserved for Proprietary Use: -
- range for Card manufacturer proprietary events 2 to -64
- range for Card Issuer proprietary events -65 to -128
RFU -129 to -32 768
ETSI
Release 11 14 ETSI TS 102 241 V11.1.0 (2015-11)
EVENT_PROFILE_DOWNLOAD
Upon reception of a TERMINAL PROFILE APDU command as defined in ETSI TS 102 221 [6] the CAT
Runtime Environment shall store the terminal profile and trigger all the Toolkit applet(s) registered to this
event.
EVENT_MENU_SELECTION, EVENT_MENU_SELECTION_HELP_REQUEST
Upon reception of an ENVELOPE (MENU SELECTION) APDU command as defined in ETSI
TS 102 221 [6] the CAT Runtime Environment shall only trigger the Toolkit applet registered to the
corresponding event with the associated menu identifier.
A Toolkit applet shall be triggered by the EVENT_MENU_SELECTION_HELP_REQUEST event only if
help is available for the corresponding Menu entry.
EVENT_CALL_CONTROL_BY_NAA
Upon reception of an ENVELOPE (CALL CONTROL) APDU command as defined in ETSI TS 102 221 [6]
the CAT Runtime Environment shall trigger the Toolkit applet registered to this event. Regardless of the
Toolkit applet state the CAT Runtime Environment shall not allow more than one Toolkit applet to be
registered to this event at a time, in particular, if a Toolkit applet is registered to this event but not in selectable
state the CAT Runtime Environment shall not allow another Toolkit applet to register to this event.
EVENT_TIMER_EXPIRATION
Upon reception of an ENVELOPE (TIMER EXPIRATION) APDU command as defined in ETSI
TS 102 221 [6] the CAT Runtime Environment shall only trigger the Toolkit applet registered to this event
with the associated timer identifier.
EVENT_EVENT_DOWNLOAD_MT_CALL
EVENT_EVENT_DOWNLOAD_CALL_CONNECTED
EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED
EVENT_EVENT_DOWNLOAD_LOCATION_STATUS
EVENT_EVENT_DOWNLOAD_USER_ACTIVITY
EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE
EVENT_EVENT_DOWNLOAD_CARD_READER_STATUS
EVENT_EVENT_DOWNLOAD_LANGUAGE_SELECTION
EVENT_EVENT_DOWNLOAD_BROWSER_TERMINATION
EVENT_EVENT_DOWNLOAD_DISPLAY_PARAMETER_CHANGED
EVENT_EVENT_DOWNLOAD_NETWORK_SEARCH_MODE_CHANGE
EVENT_EVENT_DOWNLOAD_BROWSING_STATUS
EVENT_EVENT_DOWNLOAD_FRAMES_INFORMATION_CHANGED
EVENT_EVENT_DOWNLOAD_HCI_CONNECTIVITY
EVENT_EVENT_DOWNLOAD_CONTACTLESS_STATE_REQUEST
Upon reception of an ENVELOPE (Event Download) APDU command as defined in ETSI TS 102 221 [6] the
CAT Runtime Environment shall trigger all the Toolkit applets registered to the corresponding event.
EVENT_EVENT_DOWNLOAD_ACCESS_TECHNOLOGY_CHANGE
Upon reception of an ENVELOPE (Event Download - Access Technology Change (single access technology))
APDU command as defined in ETSI TS 102 221 [6] the CAT Runtime Environment shall trigger all Toolkit
applets registered to this event.
ETSI
Release 11 15 ETSI TS 102 241 V11.1.0 (2015-11)
EVENT_EVENT_DOWNLOAD_ACCESS_TECHNOLOGY_CHANGE_MULTIPLE
Upon reception of an ENVELOPE (Event Download - Access Technology Change (multiple access
technologies)) APDU command as defined in ETSI TS 102 221 [6] the CAT Runtime Environment shall
trigger all Toolkit applets registered to this event.
EVENT_EVENT_DOWNLOAD_LOCAL_CONNECTION
Upon reception of an ENVELOPE (DOWNLOAD LOCAL CONNECTION) APDU as defined in ETSI
TS 102 221 [6] command the CAT Runtime Environment shall only trigger the Toolkit applet registered to
this event with the associated service identifier.
The registration to this event is effective once the Toolkit applet has issued a successful DECLARE SERVICE
(add) proactive command, and is valid until the first successful DECLARE SERVICE (delete) with the
corresponding service identifier, or the end of the card session.
EVENT_EVENT_DOWNLOAD_DATA_AVAILABLE
EVENT_EVENT_DOWNLOAD_CHANNEL_STATUS
Upon reception of an ENVELOPE (Event Download) APDU command as defined in ETSI TS 102 221 [6] the
CAT Runtime Environment shall only trigger the Toolkit applet registered to the corresponding event with the
associated channel identifier.
The registration to these events is effective once the Toolkit applet has issued a successful OPEN CHANNEL
proactive command. It is valid to the end of the card session or to, the first successful CLOSE CHANNEL
proactive command with the corresponding channel identifier.
A proactive command CLOSE CHANNEL for UICC Server Mode with command details set to "TCP in
LISTEN state" does not affect the registration of the Toolkit applet to the event.
When a Toolkit applet sends an OPEN CHANNEL proactive command and receives a TERMINAL
RESPONSE with General Result = "0x0X", the CAT Runtime Environment shall assign the channel identifier
to the calling Toolkit applet.
When a Toolkit applet sends a CLOSE CHANNEL proactive command and receives a TERMINAL
RESPONSE with General Result = "0x0X", the CAT Runtime Environment shall release the corresponding
channel identifier. An exception to this rule applies in the case of CLOSE CHANNEL for UICC Server Mode
with command details set to "TCP in LISTEN state": When this proactive command is sent by a Toolkit applet
and this applet receives a TERMINAL RESPONSE with General Result = "0x0X", the CAT Runtime
Environment shall not release the corresponding channel identifier.
EVENT_STATUS_COMMAND
Upon reception of an STATUS APDU command as defined in ETSI TS 102 221 [6] the CAT Runtime
Environment shall trigger all the Toolkit applet(s) registered to this event.
EVENT_APPLICATION_DESELECT
When an application session is terminated (as described in ETSI TS 102 221 [6]) the CAT Runtime
Environment shall trigger all the Toolkit applets registered to this event. The AID of the deselected application
is available to the Toolkit applet in the EnvelopeHandler, as an AID Simple TLV data object as defined in the
ETSI TS 102 223 [7].
The ProactiveHandler is not available for triggered Toolkit applets during the processing of this event.
EVENT_FIRST_COMMAND_AFTER_ATR
Upon reception of the first APDU after the ATR and before the Status Word of the processed command has
been sent back by the UICC, the CAT Runtime Environment shall trigger all the Toolkit applet(s) registered to
this event.
If the first APDU received is a Toolkit applet triggering APDU (e.g. TERMINAL PROFILE), the Toolkit
applets registered to the EVENT_FIRST_COMMAND_AFTER_ATR event shall be triggered first.
ETSI
Release 11 16 ETSI TS 102 241 V11.1.0 (2015-11)
The ProactiveHandler shall not be available at the invocation of the processToolkit method of the Toolkit
applet on the EVENT_FIRST_COMMAND_AFTER_ATR event.
EVENT_UNRECOGNIZED_ENVELOPE
Upon reception of an unrecognized ENVELOPE APDU command as defined in ETSI TS 102 221 [6] the CAT
Runtime Environment shall trigger all the Toolkit applet(s) registered to this event.
An ENVELOPE APDU command shall be considered as unrecognized by the CAT Runtime Environment if
its BER-TLV tag is not defined in the ToolkitConstants interface or if the BER-TLV tag is reserved for
GSM/3G/3GPP2 in ETSI TS 101 220 [5]. The EVENT_UNRECOGNIZED_ENVELOPE event allows a
Toolkit applet to handle the evolution of the ETSI TS 102 223 [7] specification.
As a consequence of the EnvelopeResponseHandler availability rules specified in clause 6.6, only the first triggered
Toolkit applet is guaranteed to be able to post a response.
EVENT_PROACTIVE_HANDLER_AVAILABLE
The CAT Runtime Environment shall trigger all the Toolkit applets registered to this event when the
ProactiveHandler is available and all the Toolkit applets registered to the previous event have been triggered
and have returned from the processToolkit() invocation.
As with other events, the applet with the highest priority level and newest installation date shall be triggered
first.
An applet that has the proactive handler may register for EVENT_PROACTIVE_HANDLER_AVAILABLE
before returning to allow implementing a simple co-operative "task switching" mechanism based on priorities.
Applets with the same priority level may implement "task switching" in a cyclic fashion.
If several applets have registered to EVENT_PROACTIVE_HANDLER_AVAILABLE and an applet returns
from this event, the sequence of triggering shall be determined as follows:
- The list of registered applets shall be re-evaluated.
- If there is an applet with a higher priority level than the applet that returned, the applet with the highest
priority shall be triggered.
- Else if there are one or more applet(s) with the same priority level as the applet that returned, all applets
with this priority level shall be triggered in a cyclic fashion: As long as there is at least one applet with
the same priority level and older installation date, the next older applet shall be triggered. If there is no
older one, the applet with newest installation date shall be triggered.
- Else if there are only applet(s) left with lower priority level as the applet that returned, the applet with the
next highest priority level and newest installation date shall be triggered.
When a Toolkit applet is triggered, it is automatically deregistered by the CAT Runtime Environment.
If the CAT session ends prior to an applet triggering, the applet will be triggered at the next CAT session.
NOTE: When the Toolkit applet is triggered the handlers' availability and content can be different from the
content at the registration time. Therefore, the Toolkit applet has to store any handler data in order to use
it in this event.
EVENT_EXTERNAL_FILE_UPDATE
Upon successful execution of an UPDATE BINARY or UPDATE RECORD or INCREASE or SET DATA APDU
command (sent by the Terminal and received by the UICC on the
...