ETSI ETS 300 917 ed.1 (1998-05)

Digital cellular telecommunications system (Phase 2+) (GSM); GSM Application Programming Interface (GSM-API) (GSM 07.08 version 5.2.1)

DE/SMG-040708Q

Digitalni celični telekomunikacijski sistem (faza 2+) – Aplikacijski programski vmesnik za GSM (GSM-API) (GSM 07.08, različica 5.2.1)

General Information

• Status: Published
• Publication Date: 13-May-1998
• Technical Committee: SMG 4 - Data Services
• Current Stage: 12 - Completion
• Due Date: 15-May-1998
• Completion Date: 14-May-1998
• Ref Project: SIST ETS 300 917 E1:2003 - Digital cellular telecommunications system (Phase 2+) (GSM); GSM Application Programming Interface (GSM-API) (GSM 07.08 version 5.2.1)

Standards Content (Sample)

SLOVENSKI STANDARD
SIST ETS 300 917 E1:2003
01-december-2003
'LJLWDOQLFHOLþQLWHOHNRPXQLNDFLMVNLVLVWHPID]D±$SOLNDFLMVNLSURJUDPVNL
YPHVQLN]D*60*60$3,*60UD]OLþLFD
Digital cellular telecommunications system (Phase 2+) (GSM); GSM Application
Programming Interface (GSM-API) (GSM 07.08 version 5.2.1)
Ta slovenski standard je istoveten z: ETS 300 917 Edition 1
ICS:
33.070.50 Globalni sistem za mobilno Global System for Mobile
telekomunikacijo (GSM) Communication (GSM)
SIST ETS 300 917 E1:2003 en
2003-01.Slovenski inštitut za standardizacijo. Razmnoževanje celote ali delov tega standarda ni dovoljeno.

---------------------- Page: 1 ----------------------

SIST ETS 300 917 E1:2003

---------------------- Page: 2 ----------------------

SIST ETS 300 917 E1:2003
EUROPEAN ETS 300 917
TELECOMMUNICATION May 1998
STANDARD
Source: SMG Reference: DE/SMG-040708Q
ICS: 33.020
Key words: Digital cellular telecommunications system, Global System for Mobile communications (GSM)
R
GLOBAL SYSTEM FOR
MOBILE COMMUNICATIONS
Digital cellular telecommunications system (Phase 2+);
GSM Application Programming Interface (GSM-API)
(GSM 07.08 version 5.2.1)
ETSI
European Telecommunications Standards Institute
ETSI Secretariat
Postal address: F-06921 Sophia Antipolis CEDEX - FRANCE
Office address: 650 Route des Lucioles - Sophia Antipolis - Valbonne - FRANCE
Internet: [e-mail] - http://www.etsi.fr - http://www.etsi.org
Tel.: [phone] - Fax: [phone]
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.

---------------------- Page: 3 ----------------------

SIST ETS 300 917 E1:2003
Page 2
ETS 300 917 (GSM 07.08 version 5.2.1): May 1998
Whilst every care has been taken in the preparation and publication of this document, errors in content,
typographical or otherwise, may occur. If you have comments concerning its accuracy, please write to
"ETSI Editing and Committee Support Dept." at the address shown on the title page.

---------------------- Page: 4 ----------------------

SIST ETS 300 917 E1:2003
Page 3
ETS 300 917 (GSM 07.08 version 5.2.1): May 1998
Contents
Foreword .7
Introduction.7
1 Scope .9
2 Normative references.9
3 Definitions and abbreviations .11
3.1 Definitions .11
3.2 Abbreviations .11
4 Profile A compatible part of GSM-API.11
5 Profile B compatible part of GSM-API.12
5.1 Overview .12
5.2 Parameter description.12
5.2.1 Additional Info.13
5.2.2 B Channel Information.13
5.2.3 B Protocol.14
5.2.4 B1 Protocol.14
5.2.5 B2 Protocol.15
5.2.6 B3 Protocol.15
5.2.7 B1 Configuration.16
5.2.8 B2 Configuration.16
5.2.9 B3 Configuration.16
5.2.10 BC .17
5.2.11 Called Party Number .17
5.2.12 Called Party Subaddress.18
5.2.13 Calling Party Number .18
5.2.14 Calling Party Subaddress.18
5.2.15 CIP Value .19
5.2.16 CIP mask.22
5.2.17 Connected Number .23
5.2.18 Connected Subaddress.23
5.2.19 Controller.24
5.2.20 Data.25
5.2.21 Data Length.25
5.2.22 Data Handle .25
5.2.23 Facility Selector .25
5.2.24 Facility Request Parameter .26
5.2.25 Facility Confirmation Parameter.26
5.2.26 Facility Indication Parameter .27
5.2.27 Facility Response Parameter .27
5.2.28 Flags.27
5.2.29 HLC .28
5.2.30 Info .28
5.2.31 Info Element .30
5.2.32 Info Mask.30
5.2.33 Info Number.31
5.2.34 LLC.32
5.2.35 Manu ID.32
5.2.36 Manufacturer Specific.32
5.2.37 NCCI.33
5.2.38 NCPI.34
5.2.39 PLCI .35
5.2.40 Reason .35

---------------------- Page: 5 ----------------------

SIST ETS 300 917 E1:2003
Page 4
ETS 300 917 (GSM 07.08 version 5.2.1): May 1998
5.2.41 Reason_B3 . 36
5.2.42 Reject. 37
6 GSM specific part of GSM-API (addition to ETS 300 838profile A). 37
7 GSM specific part of GSM-API (addition to ETS 300 838profile B). 38
7.1 Overview . 38
7.2 GSM specific functionality . 38
7.3 Extension mechanism. 38
7.4 Registration of GSM support. 39
7.4.1 Register GSM support facility message parameter. 39
7.5 Support of GSM Tele and Bearer Services. 40
7.5.1 Emergency Calls. 40
7.6 Basic GSM functions. 40
7.6.1 Facility message parameter. 41
7.6.1.1 Send Short Messages. 41
7.6.1.2 Receive Short Message. 42
7.6.1.3 Receive Cell Broadcast Messages . 44
7.6.1.4 In Call Modification. 44
7.6.1.5 Read SIM Data. 45
7.6.1.6 Update SIM Data. 47
7.6.1.7 Invalidate SIM file. 48
7.6.1.8 Rehabilitate SIM file . 48
7.6.1.9 Get SIM File Status. 49
7.6.1.10 Handle PIN code. 50
7.6.1.11 Get available PLMNs . 51
7.6.1.12 Set PLMN Mode. 52
7.7 GSM Supplementary Service functions. 52
7.7.1 Overview. 52
7.7.2 Enable GSM Supplementary Service Functionality . 53
7.7.3 GSM Supplementary Services Parameters. 53
7.7.3.1 ss_operation. 53
7.7.3.2 Forwarding Feature. 54
7.7.4 Facility message parameter. 54
7.7.4.1 Restrict SS Information. 54
7.7.4.2 Mobile Originated SS Transaction . 55
7.7.4.3 Clear Mobile Originated SS Transaction. 56
7.7.4.4 Receive SS Message. 57
7.7.4.5 Call Hold. 57
7.7.4.6 Call Retrieve. 58
7.7.4.7 Call Related Ussd . 58
7.7.4.8 Receive Call Related Facility. 59
7.8 Extended GSM functionality . 59
7.8.1 Facility Message parameter. 60
7.8.1.1 Get Service State. 60
7.8.1.2 RX Level and RX Quality . 60
7.8.1.3 Get SIM Present Info . 61
Annex A (informative): GSM Supplementary Services Message flow. 62
A.1 Restrict SS information. 62
A.2 Mobile Originated SS transaction . 62
A.3 Receive SS Message (Forward Check Indication) . 62
A.4 Mobile originated USSD . 63
A.5 Mobile terminated USSD . 63
A.6 Call related USSD. 63
A.7 Call hold. 64

---------------------- Page: 6 ----------------------

SIST ETS 300 917 E1:2003
Page 5
ETS 300 917 (GSM 07.08 version 5.2.1): May 1998
A.8 Receiving a Call related Facility .64
Annex B (informative): Change history .65
History.66

---------------------- Page: 7 ----------------------

SIST ETS 300 917 E1:2003
Page 6
ETS 300 917 (GSM 07.08 version 5.2.1): May 1998
Blank page

---------------------- Page: 8 ----------------------

SIST ETS 300 917 E1:2003
Page 7
ETS 300 917 (GSM 07.08 version 5.2.1): May 1998
Foreword
This European Telecommunication Standard (ETS) has been produced by the Special Mobile Group
(SMG) of the European Telecommunications Standards Institute (ETSI).
This ETS defines GSM-API, the application programming interface within the digital cellular
telecommunications system.
The contents of this ETS may be subject to continuing work within SMG and may change following formal
SMG approval. Should SMG modify the contents of this ETS, it will be submitted for OAP by ETSI with an
identifying change of release date and an increase in version number as follows:
Version 5.x.y
where:
y the third digit is incremented when editorial only changes have been incorporated in the
specification;
x the second digit is incremented for all other types of changes, i.e. technical enhancements,
corrections, updates, etc.
Introduction
This ETS defines GSM Application Programming Interface (GSM-API), the Application Programming
Interface as an extension to ETS 300 838 (HPCI).
GSM-API can be used by PCI applications without any modification. The same existing applications can
be used to transfer data inside GSM networks as well as between GSM networks and ISDNs. Thus it
unifies access to digital networks from application’s point of view.
GSM-API enables applications to access GSM interfaces like mobiles, adapter boards, handhelds, etc. in
a straightforward manner and allows unrestricted use of their functions through a standardized software
interface.
Applications which use this interface will not be affected by future expansions or hardware changes.
GSM-API makes the changes transparent to applications using it. Future expansions that retain
compatibility with existing software base are possible.
GSM-API provides an abstraction of GSM services and features that is independent from the network
provider and from the interfaces used to connect to the network. It provides an easy-to-use interface for
applications and offers a unique access to the different GSM services and features like data transfer, fax,
voice, modem, short message service, SIM access, etc.
GSM-API provides the base for modular applications development in GSM network systems.
Transposition dates
Date of adoption of this ETS: 1 May 1998
Date of latest announcement of this ETS (doa): 31 August 1998
Date of latest publication of new National Standard
or endorsement of this ETS (dop/e): 28 February 1999
Date of withdrawal of any conflicting National Standard (dow): 28 February 1999

---------------------- Page: 9 ----------------------

SIST ETS 300 917 E1:2003
Page 8
ETS 300 917 (GSM 07.08 version 5.2.1): May 1998
Blank page

---------------------- Page: 10 ----------------------

SIST ETS 300 917 E1:2003
Page 9
ETS 300 917 (GSM 07.08 version 5.2.1): May 1998
1 Scope
This European Telecommunication Standard (ETS) defines the GSM Application Programming Interface
(GSM-API) in two parts.
The first part describes, how compatibility to existing application interface ETS 300 838 [14] is covered for
the GSM network. So existing PCI applications are able to be used in a GSM environment. For these
applications the necessary mapping and local knowledge between application interface and network is
described. The only modifications needed in ETS 300 838 [14] to fulfil this requirements are covered by
changes of the parameter description. These changes of parameters are defined in clauses 4 and 5 of
this ETS.
An application compliant with this ETS shall not imply compliance with ETS 300 838 (HPCI).
Clause 4 is meant to replace subclause 5.7 message parameters of ETS 300 838 [14]. which defines the
parameters of the profile A of the HPCI.
NOTE 1: Clause 4is for further study.
Clause 5 replaces subclause 6.8 parameter description of ETS 300 838, which defines the parameters of
the profile B of the HPCI.
The second part defines GSM specific features. New GSM-API applications need extensions to ETS 300
838 [14] which are defined in section 6 and 7of this ETS.
These sections are meant as an addition to ETS 300 838 [14]. They do not replace any clause of ETS 300
838 [14].
Clause 6 defines the extensions according to the profile A of ETS 300 838 [14].
NOTE 2: Clause 6 is for further study.
Clause 7 defines the extensions according to the profile B of ETS 300 838 [14] (bit compatible to
COMMON ISDN API).
The messages and the operating system dependent part of ETS 300 838 [14] will not be changed for
GSM-API.
2 Normative references
This ETS incorporates by dated and undated reference, provisions from other publications. These
normative references are cited at the appropriate places in the text and the publications are listed
hereafter. For dated references, subsequent amendments to or revisions of any of these publications
apply to this ETS only when incorporated in it by amendment or revision. For undated references, the
latest edition of the publication referred to applies.
[1] GSM 01.04 (ETR 350): "Digital cellular telecommunications system (Phase 2+);
Abbreviations and acronyms".
[2] GSM 02.04 (ETS 300 918): "Digital cellular telecommunications system
(Phase 2+); General on supplementary services".
[3] GSM 02.30 (ETS 300 907): "Digital cellular telecommunications system
(Phase 2+); Man-Machine Interface (MMI) of the Mobile Station (MS)".
[4] GSM 03.38 (ETS 300 900): "Digital cellular telecommunications system
(Phase 2+); Alphabets and language-specific information".
[5] GSM 03.40 (ETS 300 901): "Digital cellular telecommunications system
(Phase 2+); Technical realization of the Short Message Service (SMS) Point to
Point (PP)".
[6] GSM 03.41 (ETS 300 902): "Digital cellular telecommunications system
(Phase 2+); Technical realization of Short Message Service Cell Broadcast
(SMSCB)".

---------------------- Page: 11 ----------------------

SIST ETS 300 917 E1:2003
Page 10
ETS 300 917 (GSM 07.08 version 5.2.1): May 1998
[7] GSM 04.08 (ETS 300 940): "Digital cellular telecommunications system
(Phase 2+); Mobile radio interface layer 3 specification".
[8] GSM 04.11 (ETS 300 942): "Digital cellular telecommunications system
(Phase 2+); Point-to-Point (PP) Short Message Service (SMS) support on
mobile radio interface".
[9] GSM 04.80 (ETS 300 950): "Digital cellular telecommunications system
(Phase 2+); Mobile radio interface layer 3 supplementary services specification
Formats and coding".
[10] GSM 04.90 (ETS 300 957): "Digital cellular telecommunications system;
Unstructured supplementary services operation - Stage 3".
[11] GSM 05.08 (ETS 300 911): "Digital cellular telecommunications system
(Phase 2+); Radiosubsystem link control".
[12] GSM 09.02 (ETS 300 974): "Digital cellular telecommunications system
(Phase 2+); Mobile Application Part (MAP) specification".
[13] GSM 11.11 (ETS 300 977): "Digital cellular telecommunications system
(Phase 2+); Specification of the Subscriber Identity Module - Mobile Equipment
(SIM - ME) interface".
[14] ETS 300 383 (1997): "Integrated Services Digital Network (ISDN); Harmonized
Programmable Communication Interface (HPCI) for ISDN".
[15] ETS 300-102-1 (1990): "Integrated Services Digital Network (ISDN),
Usernetwork interface layer 3, Specifications for basic call control".
[16] ITU-T Recommendation Q931 (1993): "Digital subscriber Signalling System No.
one (DSS1) - ISDN user network interface layer 3 specification for basic call
control".
[17] ISO 7776 (1986): "Information Processing systems; Data communications;
High-level data link control procedures: Description of the X.25 LAPD
compatible DTE data link procedures".
[18] IBM publication: "IBM Synchronous Data Link Control Concepts" (GA27-3093).
[19] ITU-T Recommendation Q921 (1993): "ISDN user network interface - Data link
layer specification".
[20] ITU-T Recommendation T.30 (1993): "Procedures for document facsimile
transmission in the general switched telephone Network".
[21] Request For Comment (RFC) 1661: "The Point-to-Point Protocol (PPP)".
[22] Request For Comment (RFC) 1618: "PPP over ISDN".
[23] CCITT Recommendation T.90 (1992): "Characteristics and protocols for
terminals for telematic services in ISDN".
[24] ISO 8208 (1990): "Information technology: Data communications; X.25 Packet
Layer Protocol for Data Terminal Equipment".
[25] ITU-T Recommendation X.213 (1992): "Information technology - Network
service definition for Open Systems".
[26] ITU-T Recommendation X.400: "Reference model open System interconnection
for CCITT applications".
[27] ITU-T Recommendation X.200: "Message handling system and service
overview".
[28] ETS 300 097 (1992): "Integrated Services Digital Network (ISDN), Connected
Line Identification Presentation (COLP) supplementary service; Digital
Subscriber Signalling System No. one (DSS1) protocol part 1; Protocol
implementation description".

---------------------- Page: 12 ----------------------

SIST ETS 300 917 E1:2003
Page 11
ETS 300 917 (GSM 07.08 version 5.2.1): May 1998
3 Definitions and abbreviations
3.1 Definitions
For the purposes of this ETS, the following definitions and those given in ETS 300 838 [14] apply:
Invalidate SIM File This is a procedure to change the availability of a SIM file. With the invalidate
function, the corresponding file will no longer be available. See GSM 11.11 [13].
Rehabilitate SIM File This function will make a SIM file available for an application. See
GSM 11.11 [13].
RP cause This is an error cause used in the GSM Short Messages Service at the SMR
(Short Message Relay) layer. All causes are listed in GSM 04.11 [16].
3.2 Abbreviations
For the purpose of this ETS, the following abbreviations apply:
API Application Programming Interface
ASN1 Abstract Syntax Notation Number 1. This notation is used in different
GSM services.
CAPI COMMON-ISDN-API
CBS Cell Broadcast Service. It is a specific GSM service used to broadcast
messages to all subscribers. See GSM 03.41 [6].
DCS Data Coding Scheme. It defines an alphabet and/or a class and/or a language
for a message. It is used for the SMS and the CBS. See GSM 03.38 [4].
DTMF Dual Tone Multi Frequency.
GSM-API GSM Application Programming Interface.
HPCI Harmonized Programmable Communication Interface
MI Message Identifier. Each page of a CBS message is identified by a MI.
PIN Code Personal Identification Number. See GSM 11.11 [13].
PLMN Public Land Mobile Network.
PPP Point to Point Protocol.
RLP Radio Link Protocol.
SC Service Centre. It is the network element which handle the SMS messages.
SeeGSM 03.40 [5].
SIM Subscriber Identity Module. See GSM 11.11 [13] for a full description of the SIM
files.
SMS Short Message Service. It is a specific GSM service used to send point to point
short messages. See GSM 03.40 [5] for a complete description.
SMS Command It is a TPDU initiated from a mobile station which invoke an operation in the
service centre. See GSM 03.40 [5].
SS Supplementary Services. All GSM supplementary services are defined in
GSM 02.04 [2].
TPDU Transfer Protocol Data Unit. It is used in the Short Messages Service. See
GSM 03.40 [5].
4 Profile A compatible part of GSM-API
(replaces subclause 5.7 of ETS 300 838 [14]).
For further study.

---------------------- Page: 13 ----------------------

SIST ETS 300 917 E1:2003
Page 12
ETS 300 917 (GSM 07.08 version 5.2.1): May 1998
5 Profile B compatible part of GSM-API
(replaces subclause 6.8 of ETS 300 838 [14].)
5.1 Overview
This part of GSM-API defines the parameter description which replaces subclause 6.8 of
ETS 300 838 [14] (i.e. Parameter description of Profile B). This replacement is necessary to run existing
COMMON-ISDN-API applications on a GSM network.
5.2 Parameter description
This subclause describes the parameters used in ETS 300 838 [14] profile B messages. Each parameter
is listed with its type, possible values and reference to the messages in which the parameter appears.
Some parameter values are defined according to ETS 300 102-1 [15], Q.931 [16] or GSM 04.08 [7] and
04.11 [8]. In that case there is no private Profile B coding for these parameters. These parameters are
coded as Profile B structures starting with a length octet and the remainder of the parameter being coded
as defined in ETS 300 102-1 [15] / Q.931 [16] or GSM specifications from octet three onwards.
References to the contents of a structure in this clause always use index 0 to identify the first octet of
information, i.e. the octet following the length octet.
Parameters may not be omitted, instead an empty structure shall be used. An empty structure shall be
coded as a single octet containing a value of 0.
Reserved structures shall be coded as empty structures. Reserved parameter values shall not be used by
GSM-API applications. In case of COMMON-ISDN-API applications using these reserved structures
respective parameter values the behaviour of GSM-API is described below.
Default values as described in the following subclause shall be implemented in Profile B. They need not
be valid for external ISDN equipment; in that case the external equipment defines the default values for its
usage.
Parameters may again contain parameters which are referred to as "sub parameters".
The GSM specific extensions of some of the ETS 300 838 [14] profile B parameters are mentioned in this
subclause even if they are related to the GSM specific part in clause 7.
These values shall be used by either the application and the GSM-API if and only if the application has
asked for GSM support as described in the clause 7.3 of this ETS.

---------------------- Page: 14 ----------------------

SIST ETS 300 917 E1:2003
Page 13
ETS 300 917 (GSM 07.08 version 5.2.1): May 1998
5.2.1 Additional Info
Additional Info (struct)
The purpose of the parameter additional info is to exchange signalling protocol specific information of the
network. Depending on the signalling protocol only relevant elements of this structure shall be used (e.g.
the B channel information has to be ignored in the message DISCONNECT_REQ).
The parameter has the following structure:
struct B channel information;
struct reserved, shall be ignored;
struct User user data (coded according to ETS 300 102-1 [15] / Q.931 [16]);
struct reserved, shall be ignored.
This information element appears in:
ALERT_REQ
CONNECT_REQ
CONNECT_IND
CONNECT_RESP
DISCONNECT_REQ
INFO_REQ
5.2.2 B Channel Information
B Channel Information (struct)
The purpose of the sub parameter B channel information is to choose between B channel data exchange,
D channel data exchange or pure user-user data exchange. If this struct is empty the default val
...