Mobile Application Part Interface (MAPI)

Mobile Application Part Interface

Preface

Security Warning

Permission to use, copy and distribute this documentation without modification, for any purpose and without fee or royalty is hereby granted, provided that both the above copyright notice and this permission notice appears in all copies and that the name of OpenSS7 Corporation not be used in advertising or publicity pertaining to distribution of this documentation or its contents without specific, written prior permission. OpenSS7 Corporation makes no representation about the suitability of this documentation for any purpose. It is provided “as is” without express or implied warranty.

OpenSS7 Corporation disclaims all warranties with regard to this documentation including all implied warranties of merchantability, fitness for a particular purpose, non-infringement, or title; that the contents of the document are suitable for any purpose, or that the implementation of such contents will not infringe on any third party patents, copyrights, trademarks or other rights. In no event shall OpenSS7 Corporation be liable for any direct, indirect, special or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with any use of this document or the performance or implementation of the contents thereof.

OpenSS7 Corporation is making this documentation available as a reference point for the industry. While OpenSS7 Corporation believes that these interfaces are well defined in this release of the document, minor changes may be made prior to products conforming to the interfaces being made available.

Abstract

This document is a Application Programming Interface containing technical details concerning the implementation of the Mobile Application Part Interface (MAPI) for OpenSS7. It contains recommendations on software architecture as well as platform and system applicability of the Mobile Application Part Interface (MAPI).

Purpose

The purpose of this document is to provide technical documentation of the Mobile Application Part Interface (MAPI). This document is intended to be included with the OpenSS7 STREAMS software package released by OpenSS7 Corporation. It is intended to assist software developers, maintainers and users of the Mobile Application Part Interface (MAPI) with understanding the software architecture and technical interfaces that are made available in the software package.

Intent

It is the intent of this document that it act as the primary source of information concerning the Mobile Application Part Interface (MAPI).

Audience

The audience for this document is software developers, maintainers and users and integrators of the Mobile Application Part Interface (MAPI).

Disclaimer

Although the author has attempted to ensure that the information in this document is complete and correct, neither the Author nor OpenSS7 Corporation will take any responsibility in it.

Revision History

Take care that you are working with a current version of this documentation: you will not be notified of updates. To ensure that you are working with a current version, check the OpenSS7 Project website for a current version.

A printed (or postscript) version of this document is an UNCONTROLLED version.

     
     mapi.texi,v
     Revision 0.9.2.8  2007/03/17 08:31:39  brian
     - corrected formatting problems
     
     Revision 0.9.2.7  2006/08/26 09:17:14  brian
     - better release file generation
     
     Revision 0.9.2.6  2006/08/22 12:44:17  brian
     - documentation updates
     
     Revision 0.9.2.5  2006/01/04 08:04:14  brian
     - corrected documentation
     
     

1 Introduction

This document specifies a STREAMS-based kernel-level instantiation of the 3GPP GSM/UMTS TS.29002 Mobile Application Part (MAP) service definition. The Mobile Application Part Interface (MAPI) enables the user of a mobile application service to access and use a wide variety of conforming mobile application service providers without specific knowledge of the provider's protocol. The service interface is designed to support any operation class of transaction protocol. This interface only specifies access to mobile application layer service providers, and does not address issues concerning mobile application layer management, protocol performance, and performance analysis tools.

This specification assumes that the reader is familiar with the 3GPP GSM/UTMS reference points and protocol stacks, Mobile Application Part services, and STREAMS.

1.1 Related Documentation

• 3GPP TS 29.002 Mobile Application Part (MAP)
• 3GPP TS 29.202
• 1993 ITU-T Q.771 Recommendation
• System V Interface Definition, Issue 2 – Volume 3
• CCITT Recommendation X.200
• CCITT Recommendation X.201

1.1.1 Role

This document specifies an interface that support the service provided by the Mobile Applications Part (MAP) specification for 3GPP GSM/UMTS as described in 3GPP TS 29.002. These specifications are targeted for use by developers and testers of protocol modules that require Mobile Applications Part services.

1.2 Definitions, Acronyms, Abbreviations

Application Context

Object Identifier

Calling Party

The Calling Party.

Called Party

The Called Party.

Operations Class

One of 5 ISO/OSI Transport Protocol Classes.

MAP

Mobile Applications Part

TCAP

Transaction Capabilities Application Part

SCCP

Service Connection Control Part

MTP

Message Transfer Part

TR

Transaction Sub-Layer

TC

Component Sub-Layer

IMSI

International Mobile Station Identifier

MSISDN

Mobile Station ISDN Directory Number (E.164)

ITU

International Telecommunications Union

ITU-T

International Telecommunications Union – Telecom Sector

OSI

Open Systems Interconnect

ISO

International Organization for Standardization

MAP User

A user of the Mobile Application Part (MAP) Interface.

MAP Provider

A provider of the Mobile Application Part (MAP) Interface.

MAPI

The Mobile Application Part (MAP) Interface.

MS

Mobile Station.

Components

Transaction components as defined in ITU-T Recommendation Q.771.

QoS

Quality of Service

STREAMS

A communication services development facility first available with UNIX System V Release 3.

2 The Mobile Application Layer

The Mobile Application Layer provides the means to manage the operation of a mobile network. It is responsible for the routing and management of data exchange between the MAP-User entities.

2.1 Model of the MAPI

The MAPI defines the services provided by the MAP layer to the MAP-User at the boundary between the MAP layer and the MAP layer user entity. The interface consists of a set of primitives defined as STREAMS messages that provide access to the MAP layer services, and are transferred between the MAP user entity and the MAP provider. These primitives are of two types: ones that originate from the MAP user, and others that originate from the MAP provider. The primitives that originate from the MAP user make requests to the MAP provider, or respond to an event of the MAP provider. The primitives that originate from the MAP provider are either confirmation of a request or are indications to the MAP user that the event has occurred. Figure 1 shows the model of the MAPI. (See Modelling Principles.)

Figure 1 – Module of the MAP Interface

The MAPI allows the MAP provider to be configured with any MAP user (such as an HLR, MSC or SGSN application) that also conforms to the MAPI. A MAP user can also be a user program that conforms to the MAPI and accesses the MAP provider using `putmsg()' and `getmsg()' system calls. ¹

2.2 MAP Services

The features of the MAP are defined in terms of the services provided by the MAP provider, and the individual primitives that may flow between the MAP users and the MAP provider.

The services provided by the MAP are based on a number of application contexts corresponding to the 3GPP TS 29.002 Mobile Application Part application contexts. In addition, the MAP supports services for local management.

• Local Management
• Common Services
• Mobility Services

2.2.1 Local Management

The MAP specifications also define a set of local management functions that apply to all application contexts. These services have local significance only.

Tables 1 and 2 summarizes the MAPI service primitives by their state and service.

2.2.2 Common Services

2.2.3 Specific Services

2.3 Service Categories

2.3.1 Mobility Management

2.3.1.1 Location Management Services

2.3.1.2 Paging and Search

2.3.1.3 Access Management Services

2.3.1.4 Handover Services

2.3.1.5 Authentication Management Services

2.3.1.6 Security Management Services

2.3.1.7 IEMI Managment Services

2.3.1.8 Subscriber Management Services

2.3.1.9 Identity Management Services

2.3.1.10 Fault Recovery Services

2.3.1.11 Subscriber Information Services

2.3.2 Operation and Maintenance

2.3.2.1 Subscriber Tracing Services

2.3.2.2 Miscellaneous Operation and Maintenance Services

2.3.3 Call Handling

2.3.3.1 Call Handling Services

2.3.4 Supplementary Service

2.3.4.1 Supplementary Service Services

2.3.5 SMS Management Services

2.3.5.1 Short Message Service Management Services

2.3.6 Network-Requested PDP Context Activation

2.3.6.1 Network-Requested PDP Context Activation Services

2.3.7 Location Service Management

2.3.7.1 Location Service Management Services

2.4 MAP User Entities

2.4.1 Mobile Switching Centre (MSC) Service Sets

2.4.2 Home Location Register (HLR) Service Sets

2.4.3 Visitor Location Register (VLR) Service Sets

2.4.4 Equipment Identity Register (EIR) Service Sets

2.4.5 Serving GPRS Support Node (SGSN) Service Sets

2.4.6 Gateway GPRS Support Node (GGSN) Service Sets

2.4.7 Interworking MSC (IWMSC) for Short Message Service Service Sets

2.4.8 Gateway MSC (GMSC) for Short Message Service Service Sets

2.4.9 Gateway Mobile Location Center (GMLC) Service Sets

3 MAPI Services Definition

This chapter describes the services of the MAP primitives. Time-sequence diagrams that illustrate the sequence of primitives is included. (Conventions for the time-sequence diagrams are defined in ITU-T X.210). The format of the primitives will be defined later in the document.

3.1 Local Management Services Definition

The services defined in this section are outside the scope of the international standards. These services apply to all applications contexts and specific service primitives. They are invoked for the initialization or de-initialization of a stream connected to the MAP provider. They are also used to manage options supported by the MAP provider and to report information on the supported parameter values.

3.1.1 MAP Information Reporting Service

This service provides information on the options supported by the MAP provider.

• MAP_INFO_REQ: This primitive requests that the MAP provider return the values of all the supported protocol parameters. This request may be invoked during any phase.
• MAP_INFO_ACK: This primitive is in response to the MAP_INFO_REQ primitive and returns the values of the supported protocol parameters to the MAP user.

The sequence of primitives for mobile application part information management is shown in Figure 2.

3.1.2 MAP User Bind Service

The service allows a network address and application contexts to be associated with a stream. It allows the MAP user to negotiate the number of dialogues that can remain outstanding for that MAP user (a dialogue is considered unacknowledged while it is awaiting a corresponding response or abort from the MAP user). This service also defines a mechanism that allows a stream (bound to a network address of the MAP user) to be reserved to handle remote initiated dialogues only. This stream is referred to as the listener stream.

• MAP_BIND_REQ: This primitive requests that the MAP user be bound to a particular network address and application context, and negotiate the number of allowable outstanding open indications for that address.
• MAP_BIND_ACK: This primitive is in response to the MAP_BIND_REQ primitive and indicates to the user that the specified MAP user has been bound to a network address and application context.

The sequence of primitives for the MAP user bind service is shown in Figure 3.

3.1.3 MAP User Unbind Service

This service allows the MAP user to be unbound from a network address and application context.

• MAP_UNBIND_REQ: This primitive requests that the MAP user be unbound from the network address and application context(s) to which it was previously bound.

The sequence of primitives for MAP user unbind service is shown in Figure 4.

3.1.4 Receipt Acknowledgement Service

• MAP_OK_ACK: This primitive indicates to the MAP user that the previous MAP user originated primitive was received successfully by the MAP provider.

An example showing the sequence of primitives for successful receipt acknowledgement is depicted in Figure 4.

3.1.5 Options Management Service

This service allows the MAP user to manage the QOS parameter values and other options associated with the MAP provider.

• MAP_OPTMGMT_REQ: This primitive allows the MAP user to select default values for QoS parameters within the range supported by the MAP provider, and to indicate the default selection of additional options supported by the MAP provider.

Figure 5 shows the sequence of primitives for MAP options management service.

3.1.6 Error Acknowledgement Service

• MAP_ERROR_ACK: This primitive indicates to the MAP user that a non-fatal error has occurred in the last MAP user originated request or response primitive (listed in Figure 6), on the stream.

Figure 6 shows the sequence of primitives for the error acknowledgement service.

3.2 Dialogue Handling Definition

This section describes the required MAP service primitives that define the Dialogue Handling interface.

The queue model for Dialogue Handling is discussed in more detail in CCITT X.219.

The queue module represents the operation of a MAP dialogue in the abstract by a pair of queues linking the two MAP user entities. There is one queue for each direction of information flow. Each queue represents a flow control function in one direction of transfer. The ability of a user to add objects to a queue will be determined by the behaviour of the user removing objects from that queue, and the state of the queue. The pair of queues is considered to be available for each potential MAP dialogue. Objects that are entered or removed from the queue are either as a result of interactions at the two MAP users, or as a result of MAP provider initiatives.

• A queue is empty until a dialogue object has been entered and can be returned to this state, with loss of its contents, by the MAP provider.
• Objects can be entered into a queue as a result of the actions of the source MAP user, subject to control by the MAP provider.
• Objects may also be entered into a queue by the MAP provider.
• Objects are removed from the queue under the control of the MAP user in n the same order as they were entered except:
  • if the object is of a type defined to be able to advance ahead of the preceding object (however, no object is defined to be able to advance ahead of another object of the same type), or
  • if the following object is defined to be destructive with respect to the preceding object on the queue. If necessary, the last object on the queue will be deleted to allow a destructive object to be entered – the will therefore always be added to the queue. For example, “abort” objects are defined to be destructive with respect to all other objects.

Table Y shows the ordering relationships among the queue model objects.

AA

Indicates that Object X is defined to be able to advance ahead of preceding Object Y.

DES

Indicates that Object X is defined to be destructive with respect to the preceding Object Y.

–

Indicates that Object X is neither destructive with respect to Object Y, nor able to advance ahead of Object Y.

N/A

Indicates that Object X will not occur in a position succeeding Object Y in a valid state of a queue.

3.2.1 Dialogue Establishment Phase

A pair of queues is associated with a MAP dialogue between two MAP user entities when the MAP provider receives a MAP_OPEN_REQ primitive at one of the MAP user interfaces resulting in the “begin” object being entered into the queue. The queues will remain associated with the MAP dialogue until a MAP_CLOSE_REQ or indication primitive (resulting in an “end” object) is either entered or removed from a queue. Similarly, in the queue from the called MAP user, objects can be entered into the queue only after the “continue” object associated with the MAP_OPEN_RES primitive has been entered into the queue. Alternatively, the called MAP user can enter a an “end” or “abort” object into the queue instead of the “continue” object to terminate the dialogue.

The MAP dialogue establishment procedure will fail if the MAP provider is unable to establish a TCAP dialogue, or if the destination MAP user is unable to accept the MAP_OPEN_IND.

3.2.1.1 User Primitives for Successful MAP Dialogue Establishment

• MAP_OPEN_REQ: This primitive requests that the MAP provider establish a dialogue to the specified destination under an application context.
• MAP_OPEN_RES: This primitives requests that the MAP provider accept a previous dialogue indication.

3.2.1.2 Provider Primitives for Successful MAP Dialogue Establishment

• MAP_OPEN_IND: This primitive indicates to the MAP user that a dialogue request has been made within an application context by a user at the specified source address.
• MAP_OPEN_CON: This primitive indicates to the MAP user that a dialogue request has been confirmed on the specified responding address.

The sequence of primitives for a successful MAP dialogue establishment is defined by the time sequence diagram as shown in Figure 7. The sequence of primitives for the MAP dialogue response token value determination is shown in Figure 8 (procedures for MAP response token value determination are discussed later).

3.2.2 Dialogue Component Transfer Phase

Flow control within the MAP dialogue is performed by management of the queue capacity, and by allowing objects of certain types to be inserted to the queues as shown in Table 4.

Yes

The addition of Object X may prevent further addition of Object Y.

No

The addition of Object X may not prevent the addition of Object Y.

3.2.2.1 User Primitives for Component Transfer

• Service Specific Requests: These primitives request that the MAP provider invoke a service and transfer the specified (and any subsequent) components.
• Service Specific Responses: These primitives request that the MAP provider return result for a service invocation and transfer the specified (and any subsequent) components.
• MAP_DELIM_IND: This primitive requests that the MAP provider deliver any accumulated components from previous service specific request or response primitives.

3.2.2.2 Provider Primitives for Component Transfer

• Service Specific Indications: These primitives indicate to the MAP user an invocation and the indicated (and any subsequent) components.
• Service Specific Confirmations: These primitives indicate to the MAP user a return result and the indicated (and any subsequent) components.
• MAP_DELIM_IND: This primitive indicates that the MAP provider has delivered any accumulated components belonging to the previous service specific indication or confirmation primitive.

Figure 9 shows the sequence of primitives for successful component transfer. The sequence of primitives may remain incomplete if a MAP_ABORT or MAP_CLOSE primitive occurs.

The sequence of primitives in a successful Class 1 operation is defined in the time sequence diagram as shown in Figure 10.

The sequence of primitives as shown above may remain incomplete if a MAP_UABORT, MAP_PABORT or MAP_CLOSE primitive occurs (see Table 3). A MAP user must not issue a Service Specific Response primitive if no Service Specific Indication primitive for a confirmed service has been received, or if all such Service Specific Indication primitives have been previously confirmed. Following a MAP_UABORT or MAP_PABORT, a MAP user may not issue a Service Specific Response to confirm outstanding Service Specific Indication primitives received before the abort procedure was signalled.

Note — The witholding of confirmation of a service by a MAP user can have an effect on the attainable throughput.

The sequence of primitives for component transfer is shown in the time sequence diagram in Figure 11. This sequence of primitives may remain incomplete if a MAP_ABORT or MAP_CLOSE primitive is issued.

3.2.3 Dialogue Termination Phase

The MAP dialogue release procedure is initialized by the insertion of an “abort” or “end” object into the queue. As shown in Table 3, the “abort” is destructive with respect to other objects in the queue, and eventually results in the emptying of queues and termination of the MAP dialogue.

The sequence of primitivies depends on the origin of the release action. The sequence of primitives may be:

1. invoked by one MAP user, with a request from that MAP user leading to an indication to the other;
2. invoked by both MAP users, with a request from each of the MAP users;
3. invoked by the MAP provider, with an indication to each of the MAP users;
4. invoked independently by one MAP user and the MAP provider, with a request from the originating MAP user and an indication to the other.

3.2.3.1 User Primitives for Dialogue Abort

• MAP_ABORT_REQ: This primitive requests that the MAP provider deny an outstanding request for an association (MAP_OPEN_IND) or abort an existing association.

3.2.3.2 Provider Primitives for Dialogue Abort

• MAP_UABORT_IND: This primitive indicates to the MAP user that either a request for association has been denied or an existing association has been terminated.
• MAP_PABORT_IND: This primitive indicates to the MAP user that either a request for association has been denied or an existing association has been terminated.

The sequence of primitives are shown in the time sequence diagrams in n Figures 16, 17, 18 and 19.

A MAP user may reject a MAP association establishment by issuing a MAP_ABORT_REQ. The originator parameter in the MAP_UABORT_IND primitive will indicate MAP user invoked release. The sequence of events is shown in Figure 20.

If the MAP provider is unable to establish a MAP association, it indicates this to the requester by a MAP_PABORT_IND. The originator in this primitive indicates a MAP provider invoked release. This is shown in Figure 21.

4 MAPI Primitives

This section describes the format and parameters of the MAPI primitives (Appendix A shows the mapping of the MAPI primitives to the primitives defined in 3GPP TS 29.002 and ANSI41-D). Also, it discusses the states in which the primitive is valid, the resulting state and the acknowledgement that the primitive expects. (The state/event tables for these primitives are shown in Appendix B. The precedence tables for the MAPI primitives are shown in Appendix C.) Rules for 3GPP and ANSI conformance are described in Addendum to this document.

Tables 5, 6 and 7 provide a summary of the MAP primitives and their parameters.

4.1 Management Primitives

These primitives appy to all protocol classes.

4.1.1 Information Request

MAP_INFO_REQ

This primitive requests the MAP provider to return the values of all supported protocol parameters (see MAP_INFO_ACK), and also the current state of the MAP provider. ²

Format

The format of the message is one `M_PROTO' message block and its structure is as follows:

     typedef struct {
             ulong PRIM_type;    /* always MAP_INFO_REQ */
     } MAP_info_req_t;
     

Parameters

PRIM_type:

Indicates the primitive type.

Valid States

This primitive is valid in any state where a local acknowledgement is not pending.

New State

The new state remains unchanged from the old state.

Acknowledgements

This primitive requires the MAP provider to generate one of the following acknowledgements upon receipt of the pirmitive:

• Successful: Acknowledgement of the primitive with the MAP_INFO_ACK primitive described in MAP_INFO_ACK.
• Non-fatal Errors: There are no errors associated with the issuance of this primitive.

4.1.2 Information Acknowledgement

MAP_INFO_ACK

This primitive indicates to the MAP users any relevant protocol-dependent parameters. ³ It should be initiated in response to the MAP_INFO_REQ primitive described above in MAP_INFO_REQ.

Format

The format of the message is one `M_PCPROTO' message block. The format of the `M_PCPROTO' message block is as follows:

     typedef struct {
         ulong PRIM_type;        /* always MAP_INFO_ACK */
         ulong TSDU_size;        /* maximum TSDU size */
         ulong ETSDU_size;       /* maximum ETSDU size */
         ulong CDATA_size;       /* connect data size  */
         ulong DDATA_size;       /* disconnect data size */
         ulong ADDR_size;        /* address size */
         ulong ADDR_length;      /* address length */
         ulong ADDR_offset;      /* address offset */
         ulong QOS_length;       /* default QOS values length */
         ulong QOS_offset;       /* default QOS values offset */
         ulong QOS_range_length; /* QOS range length */
         ulong QOS_range_offset; /* QOS range offset */
         ulong OPTIONS_flags;    /* bit masking for options */
         ulong TIDU_size;        /* transaction interface data size */
         long  SERV_type;        /* service type */
         ulong CURRENT_state;    /* current state */
         ulong PROVIDER_type;    /* type of provider */
         ulong NODU_size;        /* optimal TSDU size */
         ulong PROTOID_length;   /* length of bound protocol ids */
         ulong PROTOID_offset;   /* offset of bound protocol ids */
         ulong MAPI_version;     /* supported MAPI version number */
     } MAP_info_ack_t;
     

Parameters

PRIM_type

Indicates the primitive type.

TSDU_size

Specifies the maximum size (in octets) of Transaction Service User Data supported by the MAP provider.

ETSDU_size

Specifies the maximum size (in octets) of Expedited Transaction Service User Data supported by the MAP provider.

CDATA_size

Specifies the maximum number of octets of data that may be associated with a transaction initiation primitive for operations class 1, 2 and 3 operation.

DDATA_size

Specifies the maximum number of octets of data that may be associated with a transaction termination primitive for operations class 1, 2 and 3 operation.

ADDR_size

Specifies the maximum size (in decimal digits) of a network address.

ADDR_length, ADDR_offset

Specifies the length in bytes and offset from the beginning of the M_PCPROTO message block of the network address bound on the stream on which the MAP_INFO_REQ was issued (a network address is bound to a stream via a MAP_BIND_REQ).

QOS_length, QOS_offset

QOS_range_length, QOS_range_offset

OPTIONS_flags

TIDU_size⁴

This is the size of the MAP protocol interface data unit, and should not exceed the tunable system limit, if non-zero, for the size of a STREAMS message.

SERV_type

This field specified the service type supported by the MAP provider, and is one of the following:

CURRENT_state

THis is the current state of the MAP provider.

PROVIDER_type