XOM Mobile Application Part (XMAP)

XOM Mobile Application Part (XMAP) Specification

About This Manual

This is Edition 1.20110510, last updated 2011-10-28, of The XOM Mobile Application Part (XMAP) Specification, for Version 1.1 release 1.20110510 of the OpenSS7 package.

Preface

Notice

Software in this document and related software is released under the AGPL (see GNU Affero General Public License). Please note, however, that there are different licensing terms for some of the manual package and some of the documentation. Consult permission notices contained in the documentation of those components for more information.

This document is released under the FDL (see GNU Free Documentation License) with no invariant sections, no front-cover texts and no back-cover texts.

Abstract

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

This document specifies a XOM Mobile Application Part (XMAP) Specification in support of the OpenSS7 Mobile Application Part (MAP) protocol stacks. It provides abstraction of the Mobile Application Part interface to these components as well as providing a basis for Mobile Application Part control for other Mobile Application Part protocols.

Purpose

The purpose of this document is to provide technical documentation of the XOM Mobile Application Part (XMAP). 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 XOM Mobile Application Part (XMAP) 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 XOM Mobile Application Part (XMAP). This document is intended to provide information for writers of OpenSS7 XOM Mobile Application Part (XMAP) applications as well as writers of OpenSS7 XOM Mobile Application Part (XMAP) Users.

Audience

The audience for this document is software developers, maintainers and users and integrators of the XOM Mobile Application Part (XMAP). The target audience is developers and users of the OpenSS7 SS7 stack.

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 current version of this specification is normally distributed with the OpenSS7 package, openss7-1.1.1.20110510.¹

Version Control

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. 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. OpenSS7 Corporation reserves the right to revise this software and documentation for any reason, including but not limited to, conformity with standards promulgated by various agencies, utilization of advances in the state of the technical arts, or the reflection of changes in the design of any techniques, or procedures embodied, described, or referred to herein. OpenSS7 Corporation is under no obligation to provide any feature listed herein.

     $Log: xmap.texi,v $
     Revision 1.1.2.3  2011-07-18 19:42:14  brian
     - added documentation
     
     Revision 1.1.2.2  2011-02-07 02:21:48  brian
     - updated manuals
     
     Revision 1.1.2.1  2009-06-21 10:58:46  brian
     - added files to new distro
     

ISO 9000 Compliance

Only the TeX, texinfo, or roff source for this maual is controlled. An opaque (printed, postscript or portable document format) version of this manual is a UNCONTROLLED VERSION.

Disclaimer

OpenSS7 Corporation disclaims all warranties with regard to this documentation including all implied warranties of merchantability, fitness for a particular purpose, non-infrincement, or title; that the contents of the manual 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 or contract, negligence or other tortious action, arising out of or in connection with any use of this documentation or the performance or implementation of the contents thereof.

U.S. Government Restricted Rights

If you are licensing this Software on behalf of the U.S. Government ("Government"), the following provisions apply to you. If the Software is supplied by the Department of Defense ("DoD"), it is classified as "Commercial Computer Software" under paragraph 252.227-7014 of the DoD Supplement to the Federal Aquisition Regulations ("DFARS") (or any successor regulations) and the Government is acquiring only the license rights granded herein (the license rights customarily provided to non-Government users). If the Software is supplied to any unit or agency of the Government other than DoD, it is classified as "Restricted Computer Software" and the Government's rights in the Software are defined in paragraph 52.227-19 of the Federal Acquisition Regulations ("FAR") (or any successor regulations) or, in the cases of NASA, in paragraph 18.52.227-86 of the NASA Supplerment to the FAR (or any successor regulations).

Acknowledgements

The OpenSS7 Project was funded in part by:

• Monavacon Limited
• OpenSS7 Corporation

Thanks to the subscribers to and sponsors of The OpenSS7 Project. Without their support, open software like this would not be possible.

As with most open source projects, this project would not have been possible without the valiant efforts and productive software of the Free Software Foundation, the Linux Kernel Community, and the open source software movement at large.

1 Introduction

1.1 Overview

The XOM Mobile Application Part Application Programming Interface (abbreviated XMAP) defines an Application Program Inteface (API) to mobile application services. It is referred to as the interface throughout this specification.

The interface is designed to offer services that are consistent with, but not limited to, the 3GPP TS 29.002 and ITU-T Recommendation Q.711 standards. These standards were published in 1997 and have been stable for many years.

The interface is also designated to offer services that are consistent with the EIA/TIA ANSI-41D standards for CDMA mobile networks.

All of the above standards are referred to in this document as the Standards.

Access to other mobile application services through the API is not prohibited, but has not been explicitly considered.

The interface is designed to be used and implemented in conjunction with the use and implementation of the general-purpose XOM API (reference XOM).

A brief introduction to Mobile Application Services is given in Introductory Concepts. Following this is an overview of OSI-Abstract-DATA Manipulation OM, which provides the Data Abstraction service as defined in the XOM specification (reference XOM). Then the optional features of this specification are described, and the chapter closes with a list of abbreviations. In all cases the reader should refer to the Standards (reference TCAP, reference GSM MAP), or to the XOM Specification (reference XOM) for further authoritative details.

The structure of the remaining chapters and appendices are described in the Preface.

1.2 Format of the Specification

This specification describes a programming language-independent interface to the Mobile Application Services together with a specific C language binding of that interface. Several conventions are used to identify particular items. The general conventions are described in the Preface, while the C language binding conventions are described in C Language Binding.

1.3 Introductory Concepts

1.3.1 Relationship to MAP Protocols

The interaction between mobile application programs acting in a mobile application entity role are realized through the exchange of mobile application service information. The general communications service for the mobile applications is the Mobile Application Part. MAP defines the following operations:

This communication may be accomplished using the ITU-T or ANSI Transaction Capabilities Application Part protocol.

1.3.2 XMAP and the MAP Provider

The XMAP interface provides access to the MAP service provider, which offers all of the facilities defined in the Standards. It also provides facilities such as automatic association management and automatic dialog handling. The interface is designed not to restrict the services offered to those of specific service packages of GSM MAP.

The interface defined in this specification is “symmetrical” in the sense that it can be used to implement mobile application programs acting in any of the MAP producer or consumer roles (e.g, HLR, VLR). The interface supports:

• a mobile application program acting as a consumer of mobile application services. This is done by submitting service operation requests and receiving service operation responses.
• a mobile application program acting as a producer of mobile application services. This is done by receiving service operation requests and sending back service operation responses.

The interface provides the ability to send requests on the consumer side and to receive indications on the producer side within a mobile service interaction. Furthermore, if the service is confirmed, the producer will be able to send back responses that will be received as confirmations by the consumer.

1.4 Relationship to GSM and ANSI MAP

The API is essentially based on the abstract services of the GSM MAP and ANSI MAP, but is independent of the underlying communications stack. The API allows the manipulation of ITU-T and ANSI mobile application service information. Thus this API does not preclude and does not force the use of either the GSM MAP protocol or the ANSI MAP protocol.

The XMAP API offers two abstract mobile application service views: the one of GSM and the one of CDMA.

The contents of GSM MAP messages are described in 3GPP TS 29.002. These messages implicitly define GSM MAP services. The mapping between GSM MAP services and various service primitives and parameters of the XMAP API are described below.

The services offered by the XMAP API are a superset of those defined both by GSM MAP and ANSI MAP. The general communication protocol for ANSI MAP is the TCAP as specified in ANSI T1.114/2000. The general communication protocol for GSM MAP is the TCAP as specified in ITU-T Recommendation series Q.771 through Q.775.

The two abstract mobile application views of XMAP (GSM MAP and ANSI MAP) are independent of the underlying protocol. However, the ITU-T view on top of ANSI TCAP requires that an appropriate mapping of GSM MAP services over ANSI TCAP is widely available.

1.5 Relationship to Data Abstraction Services

XMAP is dependent on standard data abstraction services to ensure portability of management software written to the XMAP specification. XMAP functions pass most arguments by reference. The data referenced by these arguments is modelled and manipulated in an object-oriented fashion. Mobile application data abstraction services are provided by the XOM API (reference XOM).

The definitions below introduce the various concepts that are used by Mobile Application data abstraction services.

Syntax

A syntax is the classification and representation of values in OSI-Abstract-Data Manipulation. Examples of syntaxes are Boolean, Integer, Real, String(Octet), String(Object-Identifier) and Object.

Value

A value is a single datum, or piece of information. A value may be as simple as a Boolean value (for example, True), or as complicated as an entire OM object (for example, a Message).

OM Attribute

An OM attribute type is an arbitrary category into which a specification places some values. An OM attribute is an OM Attribute Type, together with an ordered sequence of one or more values. The OM Attribute Type can be thought of as the name of the OM attribute.

OM Object

An OM object is a collection of OM attributes.

OM Class

An OM class is a category of OM objects set out in a specification. It determines the OM attributes that may be present in the OM object, and details the constraints on those OM attributes.

Package

A Package is a set of OM classes that are grouped together by the specification, because tey are functionally related (for example, GSM service package).

Package Closure

A Package-Closure is the set of classes that need to be supported to be able to create all possible instances of all classes defined in the package. Thus an OM Class may be defined to have an OM Attribute whose value is an OM Obejct of an OM Class that is defined in some other package, but within the same Package-Closure.

Workspace

A workspace is allocated storage that contains one or more Package-Closures, together with an implementation of the Mobile Application data abstraction services, that supports all the OM classes of OM objects in the Package-Closures.

Descriptor

A descriptor is a defined data structure that is used to represent an OM Attribute Type and a single value. The structure has three components: a type, a syntax and a value.

Public Object

Public Objects are represented by data structures that are manipulated directly using programming language constructs. Use of Public Objects therefore simplifies programming by this direct access and by enabling objects to be statically defined, when appropriate. Programs can efficiently access public objects.

Private Objects

Private Objects are held in data structures that are private to the service and can only be accessed from programs indirectly using interface functions. They are of particular use for structures that are infrequently manipulated by programs, being passed by reference to the service, which can then manipulate them efficiently. An example of such objects in XMAP is the session object.

1.6 Mandatory and Optional Features

The interface defines an Application Program Interface (API) that application programs can use to access the functionality of the underlying Mobile Application Services. The interface does not define or imply any profile of that service.

Note that nothing in this specification requires that the implementation of the interface or the Mobile Application Services itself actually makes use of TCAP or other parts of the model, just so long as it provides the defined service. Also, the scope of the Mobile Application Services to which an application has access is not determined; it is not restricted to GSM MAP operations.

Some OM attributes are optional: these are marked (Optional Functionality) in the OM class definitions. They are:

• File-Descriptor in a Session object.

Some items of behaviour of the interface and a number of aspects of the Mobile Application Services provider are implementation-defined. These are:

• the maximum number of outstanding asynchronous operations
• whether an asynchronous function call returns before the operation is submitted to the Mobile Application Services provider
• the text and language of error messages
• the OM classes permitted as values of the Address and Title argument to interface functions.

The default values of some OM attributes on OM object Session are locally administered.

This API assumes the provision of automatic association management and automatic dialog handling by the MAP provider.

The interface enables negotiation of the use of the various defined features of the MAP provider and those of the interface.

1.7 Packages

The specification defines three Mobile Service packages (Common MAP package, GSM MAP package and ANSI MAP package), Interface Class Definitions. These packages define the OM classes required by the interface functions to perform GSM MAP or ANSI MAP services. The Common MAP package, which also includes the errors defined (see Errors), is mandatory. The GSM MAP package and the ANSI MAP package are optional, but at least one of them must be supported by the implementation. The ITU-T service view and the ANSI service view assume the support of the corresponding GSM MAP or ANSI MAP package by the implementation.

The use of the optional packages is negotiated using the Negotiate() function.

1.8 Terminology

The terms implementation-defined, may, should, undefined, unspecified, and will are used in this document with the meanings ascribed to them in reference XPG4, see also Glossary.

1.9 Abbreviations

2 C Language Binding

This chapter sets out certain characteristics of the C language binding to the interface. The binding specifies C identifiers for all the elements of the interface, so that application programs written in C can access the Mobile Application Services. These elements include function names, typedef names and constants. All of the C identifiers are mechanically derived from the language independent names as explained below. There is a complete list of all the identifiers in C Headers. For ease of use, some of these identifiers are defined in the specification alongside the language-independent name.

A Function() is indicated as shown.

A CONSTANT is in Roman font.

The names of [[ERRORS]] and other return codes are surrounded by square brackets.

The definitions of the C identifiers appear in four headers:

<xom.h>

This header file contains definitions for the associated OM interface.

<xmap.h>

This header file contains common definitions for the access to the Mobile Application Part service (see Interface Functions, and Common MAP Package). A listing of this header file is provided in xmap.h.

<xmap_gsm.h>

This header file contains specific definitions that reflect the Abstract Services of the GSM Mobile Services along with the ASN.1 productions of the related protocol (GSM MAP), See GSM MAP Package. A listing of this header file is provided in xmap_gsm.h.

<xmap_ansi.h>

This header file contains specific definitions that reflect the Abstract Services of the ANSI Mobile Services along with the ASN.1 productions of the related protocol (ANSI MAP), See ANSI MAP Package. A listing of this header file is provided in xmap_ansi.h.

<xmap_gsm_sm.h>

This header file contains specific definitions that reflect the Short Message GSM services along with ASN.1 productions of the related services (GSM MAP Short Message services), See GSM Short Message Service Package. A listing of this header file is provided in xmap_gsm_sm.h.

2.1 C Naming Conventions

The interfaces uses part of the C public namespace for its facilities. All identifiers start with the letters map, MAP or OMAP, and more detail of the conventions used are given in the following table. Note that the interface reserves all identifiers starting with the letters mapP for private (i.e. internal) use by implementations of the interface. It also reserves all identifiers starting with the letters mapX or MAPX for vendor-specific extensions of the interface. Application programmers should not use any identifier starting with these letters.

The OSI-Abstract-Data Manipulation API uses similar, though not identical, naming conventions, that are described in XOM (reference XOM). All its identifiers are prefixes by the letters OM or om.

A complete list of all identifiers used (except those beginning mapP, mapX, MAPX or OMAP) is given in C Headers. No implementation of the interface will use any other public identifiers. A public identifier is any name except those reserved in section 4.1.2.1 of the ISO C Standard, and the public namespace is the set of all possible public identifiers.

The C identifiers are derived from the language-independent names used throughput this specification by a purely mechanical process which depends on the kind of name:

• Interface function names are made entirely lower-case and prefixed by map_. Thus Service-Req() becomes map_service_req().
• C function parameters are derived from the argument and result names by making them entirely lower-case. In addition, the names of results have _return added as a suffix. Thus the argument Session becomes session, while the result of Result becomes result_return.
• OM class names are made entirely upper-case and prefixed by MAP_C_. Thus Service-Argument becomes MAP_C_SERVICE_ARGUMENT. Note that the symbolic OM class names are strictly those used in the abstract syntax ASN.1 of the TCAP and MAP with the exception that names containing multiple words are separated by hyphens.
• Enumeration tags are derived from the name of the corresponding OM type and syntax by prefixing MAP_. The case of letters is left unchanged. Thus Enum(User-reason) befomes MAP_User_reason.
• Enumeration constants, except erros, are made entirely upper-case and prefixed by MAP_T_. Thus resource-limitation becomes MAP_T_RESOURCE_LIMITATION.
• The name of an OM attribute is local to its OM class, that measn the same name of an OM attribute may appear in different OM classes, for example, OM attribute application-Context is defined in both OM classes Open-Arg and application-Context-List. Independent-language atribute application-Context appears as MAP_APPLICATION_CONTEXT in C-language. Note that the symbolic OM attribute names are strictly those used in the abstract syntax ASN.1 of the TCAP and MAP with the exception that names containing multiple words are separated with hyphens.
• Errors are treated as a special case. Constants that are the possible values of the OM attribute Error-Status of a subclass of the OM class Error are made entirely upper-case and prefixed by MAP_E_. Thus invalid-session becomes MAP_E_INVALID_SESSION.
• The constants in the Value Length and Value Number columns of the OM class definition tables are also assigned identifiers. (They have no names in the language-independent specification.) Where the upper limit in on eof these columns is not “1” (one), it is given a name consisting of the OM attribute name, prefixed by MAP_VL_ for value length, or MAP_VN_ for value numbers.
• The sequence of octets for each object identifier is also assigned an identifier, for internal use by certain OM macros. These identifiers are all upper case and are prefixed by OMP_O_. See reference XOM for further details on the use of object identifiers.

  Note that hyphens are translated everywhere to underscores.

2.2 Use and Implementation of Interfaces

Each of the following statements applies unless explicitly state otherwise in the detailed descriptions that follow:

If an argument to a function has an invalid value (such as a value outside the domain of the function, or a pointer outside the address space of the program, or a null pointer), the behaviour is undefined.

Any function declared in a header may be implemented as a macro defined in the header, so a library function should not be declared explicitly if its header is included. Any macro definition of a function can be suppressed locally be encoding the name of the function in parentheses, because the name is not then followed by the left parentheses that indicate expansion of a macro function name. For the same syntactic reason, it is permitted to take the address of a library function even if it is also defined as a macro. The use of #undef to remove any macro definition will also ensure that an actual function is referred to. Any invocation of a library function that is implemented as a macro will expand to code that evaluates each of its arguments exactly once, fully protected by parentheses where necessary, so it is generally safe to use arbitrary expressions as arguments. Likewise, those function-like macros described in the following sections may be invoked in an expression anywhere a function with a compatible return type could be called.

2.3 Function Return Values

The return value of a C function is always bound to the result of the language-independent description. Functions return a value of MAP_status, which is an error indication. If and only if the function succeeds, its value will be success, expressed in C by the constant MAP_SUCCESS. If a function returns a status other than this, then it has not updated the return parameters. The value of the status, in this case, is an error as described in Errors. In most cases the integer returned in Status is sufficient for error processing. However, in a few cases additional information is available if desired.

Since C does not provide multiple return values, functions must return all other results by writing into storage passed by the application program. Any argument that is a pointer to such storage has a name ending with _return. For example, the C parameter declaration ‘OM_sint *invoke_id_return’ in the Service-Req() function indicates that the function will return an signed integer Invoke-Id as a result, so the actual argument to the function must be the address of a suitable variable. This notation allows the reader to distinguish between an input parameter that happes to be a pointer, and an output parameter where the <*> is used to simulate the semantics of passing by reference.

2.4 Compilation and Linking

All applications programs that use this interface include the <xom.h> and <xmap.h> headers in that order, and at least one of the <xmap_gsm.h> and <xmap_ansi.h> headers.

3 Description

The interface comprises a number of functions together with many OM classes and OM objects that are used as the arguments and results of the functions. Both the functions and the OM objects are based closely on the Abstract Service that is specified in the Standards (references GSM MAP and ANSI MAP).

The interface models mobile application interactions as service requests made through a number of interface functions, which take a number of input arguments. Each valid request causes an operation within the producer which eventually returns a status and any result of the operation.

All interactions between a Consumer and a Producer belong to a session, which is represented by an OM object passed as the first argument to most interface functions.

The other arguments to the function include a context and various service-specific arguments. The context includes a number of parameters that are common to many functions and that seldom change from operation to operation.

Each of the components of this model is described below, along with other features of the interface such as asynchronous function calls and security.

3.1 Services

As mentioned above, the Standards define Abstract Services that Consumers and Producers use. Each of these Absract Services maps to a single function call with the same name. The services are Service-req and Service-rsp.

These are three functions called Receive(), Wait(), and Abandon() which have no counterpart in the Abstract Service. Receive() is used to receive indications and results of asynchronous operations, and is explained in Interface Functions. Wait() is used to suspend execution until indications are available for specified sessions. Abandon() is used to abandon locally the result of a pending asynchronous operation. Two additional functions Bind()² and Unbind() are used to open and close a user-session.

There are also other interface specific functions called Get-Assoc-Info(), Get-Last-Error(), Validate-object(), Error-Message(), Initialize(), Shutdown() and Negotiate().

The detailed specifications are given in Interface Functions.

3.1.1 Negotiation Sequence

The interface has an initialize and shutdown sequence that permits the negotiation of optional features. This involves the functions Initialize(), Negotiate(), and Shutdown().

Every application program must first call Initialize(), that returns a workspace. This workspace supports only the standard Common MAP package, See Interface Class Definitions.

The workspace can be extended to support either the GSM MAP or ANSI MAP package or both (see Interface Class Definitions, and any combination of the optional Mobile Application Services packages), or any vendor extensions. Vendor extensions may include additional packages, and may also include additional or modified functionality. All such packages or other extensions are identified by means of OSI Object Identifiers, and the Object Identifiers are supplied to the Negotiate() function to incorporate the extensions into the workspace. Features defined by this specification are described and assigned Object Identifiers in Interface Functions. A feature represents any package or any additional or modified functionality that is subject to negotiation. The Negotiate() function allows some particular features to be made available.

After a workspace with the required features has been negotiated in this way, the application can use the workspace as required. It can create and manipulate OM objects using the OM functions, and can start one or more management sessions using Bind().³ All the sessions on a given workspace share the same features.

Eventually, when it has completed its tasks, terminated all its mobile application sessions using Unbind(), and released all its OM objects using OM-Delete(), the application should ensure that resources associated with the interface are freed by calling Shutdown().

A miscellaneous error arises if an attempt is made to use an unavailable feature. If an instance of a class that is not in an available package is supplied as a function argument, the bad-class error arises.

3.1.2 Names, Addresses and Titles

To address a wide variety of mobile application transport protocols the interface is capable of accepting various forms of object names, system addresses and program or system titles.

• Name is an “abstract class” that contains various subclass types used to define specific subscribers or systems responsible for producing mobile application services.
• Address is an “abstract class” that contains various subclass types used to define the specific location to contact a particular consumer or producer of mobile services. For example, the SCCP-Address subclass is typically used to define the location of a producer or consumer.
• Title is an “abstract class” that contains various subclass types used to define a specific subscriber or system name responsible for producing mobile application services.

All three abstract classes participate in an implementation-specific name resolution scheme. It is assumed that given a Name, an implementation can determine the Title responsible for that Name. It is also assumed that given a Title, an implementation can determine the Address of that Title.⁴

The producer of an invoked operation may be explicitly designated at the interface boundary using the following precedence rules:

1. A default Title or Address may be supplied as parameters to a bound “session”. If both are provided, the implementation will verify that the Title resolves to the Address.
2. If automatic association management is used, a provider Title or Address may be supplied as parameters within the “context” or a specific operation request. If both are provided, the implementation will verify that the Title resolves to the Address. The “context” Title or Address takes precedence over the “session” Title or Address for unassociated session objects.
3. A consumer address may be supplied as a parameter within the “argument” of a specific operation request. The “argument” Address takes precedence over either the “session” Title or Address or the “context” Title or Address.
4. If the producer of an invoked operation is not explicitly designated at the interface boundary, the implementation will resolve the Name to the appropriate Title or Address.

3.2 Session

A session identifies to which mobile application entity a particular operation will be sent. It contains some Bind-Arguments, such as the name of the consumer. The session is passed as the first argument to most interface functions.

A session is described by an OM object of OM class Session. It is created, and appropriate parameter values may be set, using the OSI-Abstract-Data Manipulation functions. A mobile application session is then started with Bind()⁵ and later is terminated with Unbind(). A session with default parameters can be started by passing the constant Default-Session (‘(OM_object)MAP_DEFAULT_SESSION’) as the Session argument to Bind().

Bind() must be called before the Session can be used as an argument to any other function in the interface. After Unbind() has been called, Bind() must be called again if another session is to be started.

The interface supports multiple concurrent sessions, so that an application implemented as a single process, such as a server in a client-server model, can interact with the Mobile Application Services using several identities; and so that a process can interact directly and concurrently with different mobile application services.

Detailed specifications of the OM class Session are given in Interface Class Definitions.

A session can be used either acting as a consumer of mobile application services, or acting as a producer of mobile application services, or both.

A session can be restricted for use only with a designated program called the responder. When the responder is omitted and automatic association management is used, the session can be used to exchange mobile application service information with all processes.

The responder (title and address) parameters of an opened session, if present, specifies the producer of the requested operation. The precedence rules on address and title of the responder are described in Names.

Other OM attributes (vendors' implementation extensions) may be included to specify characteristics of the underlying protocol used.

There are three type of session objects:

3.2.1 AAM Enabled Session

The Session collects together all the information that described a particular management interaction. The parameters that are to control such a session are set up in an instance of this OM class, which is then passed as an argument to Bind().⁶ This sets the OM attributes that describe the actual characteristics of the session, and starts the session. Such a started session can be passed as the first argument to interface functions.

No attribute of a bound or connected session may be changed. The result of modifying a started session is unspecified.

Finally, Unbind() is used to terminate the session, after which the parameters can be modified and a new session started using the same instance, if required. Multiple concurrent sessions can be run, by using multiple instances of this OM class.

A session allows a requesting program (the requester) to exchange mobile application information with another program designated (the responder) or by default to all programs.

An AAM enabled session thus allows a mobile application entity to access either a portion of the mobile application services (that is, that are accessible via the designated responder) or all mobile application services. In the later case, the producer mobile application entity resolution is performed by the Mobile Application Service provider, according to the mobile application services invoked.

This type of session object can not be used to receive or send ACSE related primitives or operations explicitly. To use ACSE explicitly, see AAM Disabled Session.

3.2.2 AAM Disabled Session

A session object can have Automatic Association Management disabled when it belongs to a workspace that has Automatic Association Management disabled via Negotiate(), which allows the user to explicitly send and receive ACSE operations to build and tear down associations. It gives explicit control over associations to the user. The Mobile Application Service provider does no ACSE operations on behalf of the user.

When the user creates and binds a session object in a workspace with AAM disabled, only the following attributes within the session object can be specified:

• requestor-Address
• requestor-Title

The session object is then passed as an argument to Bind(),⁷ which binds the session. This bound session can only be used to send ACSE related operations an to receive ACSE related primitives. The following can be sent/received using this type of bound session:

• Receive() (map_receive()/‘MAP_ASSOC_IND’)
• Receive() (map_receive()/‘MAP_ASSOC_CNF’)
• Assoc-req() (map_assoc_req())
• Assoc-rsp() (map_assoc_rsp())

The other attributes that relate to ACSE are specified within an Assoc-Argument or Assoc-Result object that is passed to, or returned from, Assoc-req(), Assoc-rsp(), or Receive().

3.2.3 Associated Session

Once a user has created a bound session that has AAM disabled, an association can be created. An association is represented by an associated or partially associated session object. An associated session is returned as the result of building a new association. The associated session is used, like a bound session, by sending and receiving mobile application dialog handling or service operations. The major difference is that an associated session object can only be used to send and receive operations to, or from, a single remote mobile application entity. After a session is associated, the user can abort the association, which implicitly unbinds the associated, or partially associated, session.

The precedence rules for common parameters within the Session and the Context objects are different for associated session objects. Once a session is in the associated state; the responder-Address and responder-Title cannot be overridden by the context object.

To terminate this type of session, the user should either abort the session, which implicitly unbinds the session. If the user unbinds the associated session prior to aborting the association, the service provider will abort the association.

3.2.4 ADH Enabled Session

The ADH enabled session allows a mobile application entity to invoke and respond to mobile application services requests and indications without regard for dialog handling. The Mobile Application Service provider provides all dialog handling.

This type of session cannot be used to send dialog handling primitives or operations explicitly. To use dialog handling explicitly, see ADH Disabled Session.

3.2.5 ADH Disabled Session

A session object can have Automatic Dialog Handling disabled when it belongs to a workspace that has Automatic Dialog Handling disabled using the Negotiate() function. This allows the user to explicitly send and receive dialog handling operations to establish and tear down dialogs. It gives explicit control over dialogs to the user. The Mobile Application Service provider does no dialog handling operations on behalf of the user.

Once the session object is bound (AAM enabled) or associated (AAM disabled) and has ADH disabled, the session must explicitly issue dialog handling operations for each mobile application service request or response. This bound or associated session can only be used to send dialog handling primitives. The following can be sent/received using this type of bound or associated session:

• Receive() (map_receive()/‘MAP_OPEN_IND’)
• Receive() (map_receive()/‘MAP_ACCEPT_CNF’)
• Receive() (map_receive()/‘MAP_REFUSE_CNF’)
• Open() (map_open())
• Accept() (map_accept())
• Refuse() (map_refuse())

The other attributes that relate to dialog handling are specified within the Open-Argument, Accept-Result or Refuse-Result objects that are passed to, or returned from, Open(), Accept(), Refuse(), or Receive().

3.2.6 Dialog Session

Once a user has created a bound or associated session that has ADH disabled, a dialog can be created. A dialog is represented by a fully formed, or partially formed dialog, session object. A dialog session is returned as the result of building a new dialog. The dialog session is used, like a bound or associated session, by sending and receiving mobile application service operations. The major difference is that a dialog session object can only be used to send and receive operations within a single dialog with a single remote mobile application entity. After a session forms a dialog, the user can close or abort the dialog, which returns the session to the bound or associated state.

The precedence rules for common parameters within the Session and the Context objects are different for dialog session objects. Once a session has formed a dialog, the dialog related arguments, application-Context-Name, cannot be overridden by the context object.

To terminate this type of session, the user should either abort or close the dialog, which implicitly unbind the session. If the user unbinds the dialog session prior to either closing or aborting the dialog, the service provider will first attempt to close the dialog, and if that is rejected, will abort the dialog.

3.3 Context

The context defines the characteristics of the mobile application interaction that are specific to a particular mobile application operation, but are often used unchanged for many operations. Since the parameters are presumed to be relatively static for a given user during a particular mobile application interaction, these arguments are collected into an OM object of OM class Context, which is supplied as the second argument of each mobile application operation. This serves to reduce the number of arguments passed to each function.

The context includes various administrative details, such as the mode defined in the Abstract Service, which affect the processing of each mobile application operation. These include a number of Service Controls and Local Controls that allow control over some aspects of the operation. The Service Controls include mode, responder-Address, and responder-Title. The Local Controls include asynchronous, reply-Limit and time-Limit. Each of these is mapped onto an OM attribute in the Context, and they are detailed in Interface Class Definitions.

The effect is as if they were passed as a group of additional arguments on every function call. The value of each component of the context is determined when the interface function is called, and remains fixed throughout the operation.

The precedence rules on address and title of the responder are described in Names.

Some of the OM attributes in the Context have default values, some of which are locally adminstered. The constant Default-Context (‘MAP_DEFAULT_CONTEXT’) can be pased as the value of the Context argument to the interface functions, and has the same effect as a context OM object created with default values. The context must be a private object, unless it is Default-Context.

Detailed specifications of the OM class Context are given in Interface Class Definitions.

3.4 Function Arguments

The Abstract Service defines specific arguments for each operation. These are mapped onto corresponding arguments to each interface function (which are also called input parameters). Although each service has different arguments, some specific arguments recur in several operations; these are briefly introduced here. As far as the GSM MAP package is concerned, OM classes are defined with a one-to-one mapping to the ASN.1 Abstract Syntax of GSM MAP. Full details of these and all the other arguments are given in the function definitions in Interface Functions, and the OM class definitions in Interface Class Definitions.

All arguments that are OM objects can generally be supplied to the interface functions as public objects (i.e, descriptor lists) or as private objects. Private objects must be created in the workspace that was returned by Initialize(). In some cases, constants can be supplied instead of OM objects.

Note that wherever a function is stated as accepting an instance of a particular OM class as the value of an argument, it will also accept an instance of any subclass of that OM class. For example, the Service-Req function has a parameter argument, which accepts values of OM class Service-Argument. Any of the subclasses of Service-Argument may be supplied as the value of argument.

Rules for interpretation of ‘ANY’ syntax appearing in function arguments are defined in Encoding and Decoding.

3.4.1 Encoding and Decoding

XMAP specifies two alternatives for encoding and decoding of Mobile Application Packages OM-Attribute values of type ‘ANY’, or any OM-Attribute values in a Mobile Application Services package.

1. The encoding and decoding functionality can be provided internally with the XMAP API, without requiring the application to invoke any encoding or decoding functions. This option allows the application to be free from any knowledge of encoding rules. In this case, the OM class and attribute type and corresponding representation are defined in a mobile application or services package. The XMAP API uses the package definition to attempt encoding or decoding; if automatic decoding fails, an OM String(Encoding) is used.
2. The application can perform encoding and decoding itself. This option gives the application responsibility and control over the encoding and decoding of OM attributes. In this case, all OM attribute values appear as an OM String(Encoding).

The encoding and decoding alternative to be used is negotiated through the Negotiate() function; See Negotiate.

The XMAP API does not specify the use of OM-Encode or OM-Decode for the OM classes defined in this specification, or in mobile application or services packages used with this specification.

To ensure interoperability, the sender and receiver must follow the same encoding rules when converting between OM syntax and encoded syntax. If an algorithm is used to generate OM packages, then the algorithm must ensure that the generated OM syntax is consistent with the input abstract syntax (that is, the same encoded values must result from applying the encoding rules to either representation). The encoding rules used with the GSM MAP and ANSI MAP packages defined by this specification are ANS.1 BER. This does not imply that other encoding rules cannot be used with other packages defined in the future.

For the API to encode and decode the OM attribute values according to the ASN.1 standard scheme, ASN.1 tagging information must be stored for each OM object and each OM attribute. Thus, the package definitions in the workspace need to incorporate the ASN.1 tagging information for each OM object and each OM attribute definition for all Mobile Application Services packages.

As a minimum, the following requirements apply:

• All rules specified in ISO/IEC 8825 – Specification of Basic Encoding Rules for Abstract Syntax Notation One (ASN.1) shall be adhered to. Any exceptions or restrictions must be stated.
• ASN.1 tagging information must be retained for each OM object and each OM attribute in the Mobile Application Services packages.
• The specified encoding and decoding scheme (and any implementation thereof) should be extensible to accommodate the new encoding rules established subsequent to ISO/IEC 8825.

3.4.2 Argument and Response

Most operations and notifications take an argument to specify the argument of the operation and a response when issuing the response of the operation. These arguments and responses are specified to accept values of OM classes that are consistent with the abstract service view (GSM MAP or ANSI MAP) of the current operation.

The argument for a Service-req() function is represented by an instance of the OM Class GSM-Service-Req-Argument for a GSM MAP operation or an instance of the OM Class ANSI-Service-Req-Argument for an ANSI MAP operation.

The reponse for a Service-rsp() function is represented by an instance of the OM Class GSM-Service-Result, GSM-Linked-Reply-Argument Service-Error or GSM-Service-Reject to represent the possible responses of the GSM service request operation, or an instance of the ANSI-Service-Result, ANSI-Linked-Reply-Argument Service-Error or ANSI-Service-Reject to represent the possible responses of the ANSI service request operation.

3.5 Function Results

All functions return a Status (which is the C function result). Most return an Invoke-ID which identifies the particular invocation. The confirmed operations each return a Result. (The Invoke-ID and Result are returned using pointers that are supplied as arguments of the C function). These three kinds of function results are introduced below.

All OM objects returned by interface functions (results and errors) will be private objects in the workspace associated with the session private object.

3.5.1 Invoke-ID

All interface functions that invoke a mobile application service operation return an Invoke-ID; an integer that identifies the particular invocation of an operation. The Invoke-ID is only relevant for asynchronous confirmed operations and may be used later to receive the Status and Result, or to abandon them. The Invoke-ID is also used to respond to a previously requested confirmed operation. Asynchronous operations are fully described in Synchronous and Asynchronous Operation. The interface functions that can be used to start them are the Service-req() function.

The numerical value of the invoke-Id returned from a call that successfully invoke an asynchronous confirmed operation is guaranteed to be unique amongst all outstanding operations in given session. The value is such as could be returned from TCAP, the Transaction Capabilities Application Part defined in ITU-T Recommendation Q.771 through Q.775. Invoke IDs used by XMAP are not necessarily those that are actually sent via a protocol such as TCAP. Invoke IDs may be mapped or altered by the Mobile Application Service provider.

The value returned for a synchronous operation or an asynchronous non-confirmed operation is unspecified, as is that for a call that fails to invoke an operation.

3.5.2 Result

Functions invoking confirmed mobile application service operations return a result only if they succeed. All errors from these functions are reported in the Status described below, as are errors from all other functions.

The value returned by a function call that invokes an asynchronous operation is unspecified, as is that for a call that fails to invoke an operation. The result of an asynchronous operation is returned by a later call to Receive().

The result of a function invoking a confirmed operation can be composed of a single reply, or of multiple linked replies. In the later case, the term partial result is used to designate one of these linked replies. Only a confirmed Service-req may produce multiple results. Multiple replies to a single mobile application service operation may only occur if the invoker specifies multiple-reply in the functional unit attribute of the Session object.

In asynchronous mode, the partial results can be retrieved one at a time by subsequent calls to Receive(), which each time returns an instance of OM class Linked-Reply-Argument. In synchronous mode, the function returns an instance of OM class Multiple-Reply, which contains a list of sub-objects of OM class Linked-Reply-Argument.

The result (or partial result) of an operation is returned in a private object whose OM class is appropriate to the particular operation. The format of mobile application service operation results is driven both by the Abstract Service and by the need to provide asynchronous execution of functions. To simplify processing of asynchronous results, the result (or partial result) of a single operation is returned in a single OM object (corresponding to the abstract result defined in the Standards). The components of the result (or partial result) of an operation are represented by OM attribute in the operation's result object. All information contained in the Abstract Service result is made available to the application program. The result (partial result) is inspected using the functions provided in the OSI-Abstract-Data Manipulation API.

Only confirmed mobile application service operations produce results, and each type of operation has a specific OM class of OM object for its result. These OM classes are defined in Interface Class Definitions.

The actual OM class of the result can always be a subclass of that named, to allow flexibility for extensions. Thus, the function OM-Instance() should always be used when testing the OM class.

3.5.3 Status

Every interface function returns a Status value, which is either the constant success (‘(MAP_status)0’ or ‘MAP_SUCCESS’) or an error. Function call errors are represented as integer constants and grouped in categories of System, Library and Communications as described in Errors.

Additional error information is available for System and Communications errors via the Get-Last-Error() function call. Additional error information is available for the bad-argument Library error via the Validate-object() function call.

A synchronous call with multiple linked replies is considered successful unless the reply limit or time limit is exceeded. The function returns a Status value equal to success, and the argument Result is an OM object of OM class Multiple-Reply, which contains all the linked replies.

It should be noted that OM object Linked-Reply-Argument may contain an OM attribute that reflects an error.

If the reply limit or time limit is exceeded, the synchronous call fails and returns a status of the appropriate Library error. However, the Result is still considered valid and may contain an OM-Object Multiple-Reply, which contains all the received linked replies. A result of MAP_ABSENT_OBJECT means no replies were received.

In most cases other results of functions are initialized to Null (MAP_ABSENT_OBJECT) if the status does not have the value success. However, the Result is still considered valid and may contain an OM-Object of partial replies. A result of MAP_ABSENT_OBJECT means no replies were received.

3.6 Synchronous and Asynchronous Operation

The asynchronous or synchronous mode of a requested operation is specified at the interface, and determined for each operation by the value of the OM attribute Asynchronous in the Context passed to the interface function. The default value of this OM attribute is false, causing all operations to by synchronous. Support for both synchronous and asynchronous operation is mandatory. There is a limit to the number of pending asynchronous operations; this limit is given by the constant max-outstanding-operations, and has a minimum value of 10.

In synchronous mode, all functions wait until the operation is complete before returning. Thus the thread of control is blocked within the interface after calling a function, and the application can make use of the result immediately after the function returns.

In asynchronous mode, some functions return before the operation is complete. The application is then able to continue with other processing while the operation is being executed by the Mobile Application Service provider, and can then access the result by calling Receive(). An application may initiate several concurrent asynchronous operations on the same session before receiving any of the results, subject to the limit described below. The results are not guaranteed to be returned in any particular order. The functions that can execute asynchronously are the Service-req() function. This corresponds to the mobile application services of the Standards that operate in a confirmed mode. Moreover, only confirmed operations return service results.

An asynchronous function call of a confirmed service returns an Invoke-ID of the operation to the application. The same Invoke-ID will be returned by Receive() on the corresponding result.

An Invoke-ID is also returned by Receive() on an indication of an invoked mobile application service operation. The same Invoke-ID will be used to respond to this operation.

Implementations of the interface are free to return from asynchronous function calls as soon as possible or may wait until the operation has been submitted to the underlying Mobile Application Service provider. The actual policy used is implementation-defined.

Implementations will define a limit to the number of asynchronous operations that may be outstanding at any one time on any one session. An asynchronous operation is outstanding from the time that the function is called until the last reply of the result is returned by Receive(), or the operation is abandoned by Abandon(), or the session is closed by Unbind(). The limit is given by the constant max-outstanding-operations (‘MAP_MAX_OUTSTANDING_OPERATIONS’) and is at least 10 for conforming XMAP implementations. While this number of operations is outstanding, attempts to invoke further asynchronous operations will report a Library-Error (too many operations).

Asynchronous operation calls can be aborted by executing an Abandon() or Unbind() call. In this case, the operation is no longer outstanding and the result will never be returned by further Receive() function calls.

If an error is detected before an asynchronous request is submitted to the Mobile Application Service provider, the function will return immediately and there will be no outstanding operation generated. Other errors are notified later by Receive(), when the result of the outstanding asynchronous confirmed operation is returned. All errors occurring during a synchronous request are reported when the function returns. Full details of error handling are given in Errors.

Where vendors provide suitable system primitives (such as System V poll(2s), or BSD select(2)), applications can obtain a file descriptor from the Session by inspecting the value of the OM attribute File-Descriptor. Applications may use the file descriptor to suspend the process until data is received on the particular file descriptor.

Applications should ensure that there are no outstanding asynchronous operations on a session when Unbind() is called on that session. Once Unbind() has been called there is no way to determine whether any outstanding operations succeed or even whether they were ever sent to the Mobile Application Service provider. Also no errors or results of any kind will be reported to the application. It is strongly recommended that Receive() is called repeatedly until Completion-Flag takes the value nothing.

3.7 Other Features

These features are not part of the interface itself, but are mandatory when specified by the Mobile Application Service provider.

The Mobile Applications are not restricted to those defined by GSM MAP.

All the features listed below are for the most part necessary for ease of use in a mobile application environment. These features are classified as given registered identifiers (Object Identifier). They can be negotiated using the Negotiate() function in the same manner as packages. Other types of information that are critical in servicing an environment that includes implementation from multiple vendors on various machines can also be classified and handled with the Negotiate() function. Features defined by this specification are described and assigned Object Identifiers in Interface Functions.

3.7.1 Automatic Association Management

When the Mobile Application Services provider makes use of association oriented communication services, such as TCAP, the Mobile Application Service provider implementations are assumed to provide automatic handling of the association between mobile application entities, establishing and releasing associations at its discretion. Such management is intended to bring benefits such as reduced communication charges. To allow this flexibility to the implementation, the interface does not specify when communication takes place. Automatic Association Management (AAM) may be enabled or disabled on a per-workspace basis using the Negotiate() function.

3.7.2 Automatic Dialog Handling

When the Mobile Application Services provider makes use of dialog oriented communication services, such as that provided by TCAP, the Mobile Application Service provider implementations are assumed to provide automatic handling of dialogs between mobile application entities, establishing and releasing dialogs at its discretion. Such management is intended to bring benefits such as reduced communication overheads. To allow this flexibility to the implementation, the interface does not specify when communication takes place. Automatic Dialog Handling (ADH) may be enabled or disabled on a per-workspace basis using the Negotiate() function.⁸

3.7.3 Automatic Performer Resolution

The performer of an invoked operation may be explicitly designated by the responder name and responder address parameters of the bound session used.

However, in the case where the responder is specified as a wildcard, the Mobile Application Service provider may be assumed to provide automatic mobile application service and application context to consumer resolution: to find out the consumer that is in charge of the selected mobile application service specified in the mobile application service operation.

3.7.4 Responder Versatility

Responder versatility is the ability to change the consumer within a same bound-session at each function call. It is useful when the automatic consumer resolution is either not supported by the Mobile Application Service provider or not requested. This applies if the underlying Mobile Application Service provider is connection-less.

3.7.5 Automatic Name to Address Resolution

Mobile Application Service provider implementation may provide automatic resolution between program name and address to find the network address of a mobile application entity from its name using directory or translation services.

3.7.6 Automatic Dispatching to Appropriate Stack

The Mobile Application Services provider implementation may provide a loop back facility if the destination of the operation or notification is local. It also may provide routing of the mobile application services operation to the proper underlying communications stack according to the implied mobile application service and the destination (for example over a ITU-T SCCP stack or an ANSI SCCP stack).

3.8 Function Sequencing

A minimum set of sequencing rules applies when using the interface to exchange mobile application service information between mobile application programs acting as a mobile application entity. These rules need to be respected by mobile application programs to ensure that interface functions are called in the proper sequence and that the state of the interface is not violated, otherwise Library-error status will be returned.⁹

The general rules to follow are:

1. Initialize a workspace (‘map_initialize()’)
2. Negotiate features of the interface (‘map_negotiate()’)
3. Open one or several sessions (‘map_bind()’)
4. Perform mobile application service interactions (operations) using the offered interface functions. An interaction is identified by its Invoke-Id.
5. Close the opened sessions (‘map_unbind()’)
6. Discard the workspace (‘map_shutdown()’)

Seven states are defined in the interface to cover both interface service operations and mobile application service interactions:

UNINIT

Workspace uninitialized.

INIT

Workspace initialized.

UNBND

Session closed.

BND

Session opened.

IDLE

OUTOP

Outstanding operation requested in a mobile application service interaction.

OPIND

Operation indication received in a mobile application service interaction.

4 Interface Functions

4.1 Abandon()

NAME

Abandon – abandon locally the result of a pending asynchronous operation.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_abandon(
             OM_private_object  session,
             OM_sint32          invoke_id
     );

DESCRIPTION

This function abandons the result of an outstanding asynchronous function call. The function is no longer outstanding after this function returns, and the result (or the remaining results in case of multiple linked replies) will never be returned by Receive().

Abandon() may, but need not, cause the Mobile Application Service provider to abandon the outstanding asynchronous operation itself (as opposed to simply discarding the result). Note that the specified behaviour is a local mater, and no statement is made about underlying mobile application service operations that may or may not be abandoned.

This function can only be called in synchronous mode.

ARGUMENTS

Session (Object(Session))

The mobile application session in which the confirmed operation was requested. This must be a private object previously returned from Bind().¹⁰

Invoke-ID (Integer)

Selects the specific outstanding asynchronous operation submitted via the Session to be terminated. The outstanding operation may be a non-confirmed service. In that case the abandon is without effect. The value of Invoke-ID must be that which was returned by the function call that initiated the asynchronous management operation that is now to be abandoned.

RESULTS

Status (Status)

Indicates whether or not the abandon function succeeded.

ERRORS

This function can return a System-Error or one of the following Library-Errors: bad-class, bad-session, bad-procedural-use, miscellaneous, session-terminated.

This function can return a Communications-Error.

Note that the abandon function is successful even if the operation to be abandoned does not exist (any longer) or is not confirmed. The abandon is then without effect.

The function can also return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] and [[MAP_INSUFFICIENT_RESOURCE]].

4.2 Abort()

NAME

Abort – Abort Association.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_abort(
             OM_private_object  session,
             OM_private_object  context,
             OM_object          argument
     );

DESCRIPTION

This function is one of a group of dialogue handling functions: Open(), Accept(), Refuse(), Issue(), Close(), Abort(), Receive(), used to manage the MAP dialogue when AAM is disabled on a session. When AAM is enabled on a session, this dialogue handling function is neither necessary nor permitted.

This function is used to abort a mobile application session that is either associated or partially associated. The service is defined as an unconfirmed service: a reply is not expected.

Once an abort is issued, the associated session is implicitly disassociated and unbound. All outstanding requests that pertain to this session are returned with the error session-terminated. This includes any Wait() request on that session.

ARGUMENTS

Session (Object(Session))

The associated (or partially associated) session against which this operation is perfomed. This must be a private object previously returned as part of an Accept-Result or Open-Argument, or returned explicitly from an asynchronously called Open(). This session object must have AAM disabled.

Context (Object(Context))

The management context to be used for this operation. This argument must be a private object. Once a session is connected or partially connected, the precedence rules for common parameters within the Session and the Context objects are different. Once connected, the responder address and responder title cann not be overriden by the Context object. (See also Names.)

Argument (Object(Abort-Argument))

The information supplied as the argument of an Abort operation. (See Abort-Argument.)

RESULTS

As this function is not confirmed, there are no results returned.

ERRORS

This function can return a Communications-Error, or one of the following Library-Errors: bad-argument, bad-class, bad-context, bad-session, miscellaneous, missing-type, session-terminated, reply-limit-exceeded, time-limit-edceeded.

The function can also return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] and [[MAP_INSUFFICIENT_RESOURCES]].

CORRESPONDENCE

This function corresponds to the MAP-U-ABORT request primitive of 3GPP TS 29.002 Section 7.

4.3 Abort-req()

NAME

Abort-req — abort a mobile application association.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_abort_req(
             OM_private_object   session,
             OM_private_object   context,
             OM_object           response
     );

DESCRIPTION

This function is used to abort a mobile application session that is either associated or partially associated. The service is defined as an unconfirmed service. A reply is not expected.

Once an abort request has been issued, the associated session is implicitly disassociated and unbound. All outstanding requests that pertain to this session are returned with the error session-terminated. This includes any Wait() requests on that session.

ARGUMENTS

Session (Object(Session))

The associated (or partially associated) session against which this operation is performed. This must be a private object previously returned as part of an Assoc-Result or Assoc-Argument, or returned explicitly from an asynchronously called Assoc-req(). This session object must have AAM disabled.

Context (Object(Context))

The mobile application context to be used for this operation. This argument must be a private object.

Once a session is associated or partially associated, the precedence rules for common parameters within the Session and Context objects are different. Once associated, the responder-Address and responder-Title cannot be overridden by the Context object.

Response (Object(Abort-Result))

The information supplied as the response of an Abort operation.

RESULTS

Status (Status)

The value success indicates that the operation was completed.

ERRORS

This function can return a Communications-Error, or one of the following Library-Errors: bad-argument, bad-class, bad-context, bad-session, miscellaneous, missing-type, session-terminated, reply-limit-exceeded, time-limit-exceeded.

This function can also return the error constants [[MP_NO_WORKSPACE]], [[MP_INVALID_SESSION]] or [[MP_INSUFFICIENT_RESOURCES]].

4.4 Accept()

NAME

Accept — accept an indicated mobile application open operation.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_accept(
             OM_private_object       session,
             OM_private_object       context,
             OM_object               response,
             OM_sint32               dialog_id,
             OM_private_object      *connected_session_return
     );

DESCRIPTION

This function is one of a group of dialogue handling functions: Open(), Accept(), Refuse(), Issue(), Close(), Abort(), Receive(), used to manage the MAP dialogue when AAM is disabled on a session. When AAM is enabled on a session, this dialogue handling function is neither necessary nor permitted.

This function is used to accept a previously indicated Open operation. This function can only be called in syncrhonous mode.

ARGUMENTS

Session (Object(Session))

The mobile application session against which this operation is to be performed. This must be a private object previously returned from Bind().¹¹

Context (Object(Context))

The mobile application context to be used for this operation. This argument must be a private object or the constant Default-Context (‘MAP_DEFAULT_CONTEXT’).

Response (Object(Accept-Result))

The information supplied in acceptance of the previously indicated Open operation. This is an instance of OM class Accept-Result, indicating that the open indication is to be accepted. The user provides negotiated ACSE parameters in this object as input to the service provider. A newly formed dialog object is returned in the Accept-Result object, so this is an in/out parameter to this function. The new Session object represents a fully formed dialog session.

Dialog-ID (Integer)

The Dialog-ID of the requested dialog to which the reply applies. This Dialog-ID must have been returned from a call to Receive() for the corresponding association that is being accepted.

RESULTS

Status (Status)

Indicates whether or not the Accept response was completed.

Connected-Session (Object(Session))

When successful, this function returns a newly connected session object. The returned Session object is in a connected state, and contains the final negotiated ACSE parameters for the new association.

It is not specified whether the association has been formed by the underlying Mobile Application Service provider at the time that this function returns. The underlying Mobile Application Service might wait until a Issue() function call before fully forming the association. Nevertheless, the association is considered to be in the “connected” state from the standpoint of the interface.

ERRORS

This function can return a System-Error or one of the following Library-Errors: bad-class, bad-context, bad-result, bad-session, miscellaneous, no-such-operation, not-supported, session-terminated.

This function can return a Communications-Error.

This function can also return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] and [[MAP_INSUFFICIENT_RESOURCES]].

CORRESPONDENCE

This function corresponds to the MAP-OPEN response primitive (with a parameter indicating acceptance) of 3GPP TS 29.002 Section 7.

4.5 Assoc-req()

NAME

Assoc-req — establish mobile application association.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_assoc_req(
             OM_private_object   session,
             OM_private_object   context,
             OM_object           argument,
             OM_private_object  *result_return
     );

DESCRIPTION

This function is used to request the establishment of a mobile application association. The service is defined as a non-confirmed service. No reply is expected.

This operation may only be called in synchronous mode.

ARGUMENTS

Session (Object(Session))

The mobile application session against which this operation is performed. This must be a private object previously returned from Bind().¹² This session must also have AAM (Automatic Association Management) disabled.

Context (Object(Context))

The mobile application context to be used for this operation. This argument must be a private object.

Argument (Object(Assoc-Argument))

The information supplied as an argument of an Assoc operation. This is an Assoc-Argument object with optional ACSE information contained within it. An associated Session object is returned in the Result of this function.

RESULTS

Status (Status)

The value success indicates that the action was completed.

Result (Object(Assoc-Result))

Upon successful completion, when the Assoc-req has been accepted/rejected by the Mobile Application Service provider, one instance of the OM class Assoc-Result Object is returned. This Assoc-Result object either contains information as to why an association was rejected, or contains a Session object in an associated state, and contains the final negotiated ACSE parameters for the new association.

ERRORS

This functoin can return one of the following Library-Errors: bad-argument, bad-class, bad-context, bad-session, miscellaneous, missing-type, session-terminated, reply-limit-exceeded, time-limit-exceeded.

This function can return a Communications-Error.

This function can also return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] or [[MAP_INSUFFICIENT_RESOURCES]].

SEE ALSO

Assoc-rsp().¹³

4.6 Assoc-rsp()

NAME

Assoc-rsp — reply to a requested association operation.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_assoc_rsp(
             OM_private_object   session,
             OM_private_object   context,
             OM_object           response,
             OM_sint32           assoc_id
     );

DESCRIPTION

This function is used to reply to a previously invoked Assoc operation.

This function can only be called in syncrhonous mode.

ARGUMENTS

Session (Object(Session))

The mobile application session against which this operation is performed. This must be a private object previously returned from Bind().¹⁴

Context (Object(Context))

The mobile application context to be used for this operation. This must be a private object or the constant Default-Context (‘MAP_DEFAULT_CONTEXT’).

Response (Object(Assoc-Result))

The information supplied as a response to an Assoc operation. This is one of the following:

• When an association is accepted, one instance of the OM class Assoc-Result is given as the response. The user provides negotiated ACSE parameters in this object as input to the service provider, and also indicates that the association is to be accepted by setting the assoc-Result attribute to accept. A newly associated session object is returned in the Assoc-Result object, so this is an in/out parameter to this function. The new Session object is in an associated state, and contains the final negotiated ACSE parameters for the new association.
• When an association is to be rejected, one instance of the OM class Assoc-Result is given as a response. The Assoc-Result should have the assoc-Result attribute set to either reject-permanent or reject-transient. The assoc-Diagnostic can also optionally be set to indicate why the reject has occurred.

Assoc-ID (Integer)

The Assoc-ID of the requested operation to which the reply applies.

RESULTS

Status (Status)

Indicates whether or note the Assoc response was completed.

ERRORS

Ths function can return a System-Error or one of the following Library-Errors: bad-class, bad-context, bad-result, bad-session, miscellaneous, no-such-operation, not-supported, session-terminated.

SEE ALSO

Assoc-req().¹⁵

4.7 Bind()

NAME

Bind — open a mobile application session.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_bind(
             OM_object           session,
             OM_workspace        workspace,
             OM_private_object  *bound_session_return
     );

DESCRIPTION

This function opens a mobile application session. It creates a Session OM object describing the session suitable for supplying to other XMAP functions. A session must be opened before any mobile application service interactions can take place.

If the OM attribute requestor-Title is specified, only one unconnected session can be opened with the same value of the OM attribute. There can be multiple connected or partially connected session objects with the same requestor-Title.

To allow for the implementation of automatic association management, it is undefined as to whether Bind() causes any communication with the remote management entity.

ARGUMENTS

Session (Object(Session))

Specifies a program together with other details of the service required. This argument may be either a public object or a private object. The constant Default-Session (‘MAP_DEFAULT_SESSION’) may also be used as the value of this argument, causing a new session to be created with default values for all its OM attributes.

Workspace (Workspace)

Sepcifies the workspace (obtained from a call to Initialize()) which is to be associated with the session. All function results from mobile application operations using this session will be returned as private objects in this workspace. If the Session argument is a private object, it must be a private object in this workspace.

RESULTS

Status (Status)

Indicates whether or not the function completed successfully.

Bound-Session (Object(Session))

Upon successful compltion, contains an instance of a mobile application session that may be used as an argument to other functions (e.g. Service-req()). This will be a new private object if the value of Session was Default-Session or a public object, otherwise, it will be that supplied as an argument. In the later case, the session provided should not be already in use. The function will supply default values for any of the OM attribute that were not present in the Session instance supplied as an argument. It will also set the value of the File-Descriptor OM attribute (the value will be No-Valid-File-Descriptor (‘MAP_NO_VALID_FILE_DESCRIPTOR’) if the functionality is not supported).

When AAM is disabled with Negotiate(), any session bound using Bind() is unconnected and may only be used to receive and send ACSE-related primitives, (i.e. it cannot be used for Mobile Application Service operations).

ERRORS

This function can return a System-Error or one of the following Library-Errors: bad-address, bad-session, bad-title, miscellaneous, not-supported, too-many-sessions.

This function can return a Communications-Error.

This function can also return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] and [[MAP_INSUFFICIENT_RESOURCES]].

SEE ALSO

Unbind(),¹⁶ Negotiate().¹⁷

4.8 Close()

NAME

Close — terminate a mobile application association.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_close(
             OM_private_object       session,
             OM_private_object       context,
             OM_object               argument
     );

DESCRIPTION

This function is used to request the termination of a mobile application association. The service is defined as an unconfirmed service. No reply is expected.

This operation may only be called in synchronous mode.

ARGUMENTS

Session (Object(Session))

The connected session against which this operation is performed. This must be a private object previously returned as part of an Accept-Result or Open-Argument. This session object must have AAM diabled, and it must be in a connected state.

Context (Object(Context))

The mobile application context to be used for this operation. This argument must be a private object.

Once a session is connected or partially connected, the precedence rules for common parameters within the Session and the Context objects are different. Once connected, the responder address and title cannot be overridden by the Context object.

Argument (Object(Close-Argument))

The information supplied as the argument of a Close operation.

RESULTS

Status (Status)

The value success indicates that the operation was completed.

ERRORS

This function can return a Communications-Error, or one of the following Library-Errors: bad-argument, bad-class, bad-context, bad-session, miscellaneous, missing-type, session-terminated, reply-limit-exceeded, time-limit-exceeded.

This function can also return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] and [[MAP_INSUFFICIENT_RESOURCES]].

SEE ALSO

Abort().¹⁸

CORRESPONDENCE

This function corresponds to the MAP-CLOSE request primitive of 3GPP TS 29.002 Section 7.

4.9 Error-Message()

NAME

Error-Message — return an error message describing a particular error.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     OM_sint map_error_message(
             MAP_status          error,
             OM_sint             length,
             unsigned char      *error_text_return
     );

DESCRIPTION

This function returns an error message string that describes the error. The caller provides a buffer-address and buffer-length argument. The error message is stored in the client's buffer.

ARGUMENTS

Error (Status)

Length

The length of the buffer. The error text buffer is an unsigned character array. This is necessary if the intent is to support NLS (the X/Open Native Language System).

RESULTS

Error-text (String)

A message describing the error. The error message text is terminated by a NUL character.

The error message text will be truncated if the length of the error-text-buffer is less than the length of the error message text.

Length (Integer)

Indicates the length of the returned mesage. If the length parameter is 0 or the *error_text_return parameter is NULL, then the length_return value indicates the amount of buffer space required to host the error message.

ERRORS

This function returns no errors. (A default error message reports faulty arguments or other problems).

4.10 Get-Assoc-Info()

NAME

Get-Assoc-Info — retrieve negotiated association values.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_get_assoc_info(
             OM_private_object       receive_result_or_argument,
             OM_uint                 request_mask,
             OM_uint                 result_mask,
             OM_public_object        *pres_layer_args,
             OM_public_object        *acse_args,
             OM_public_object        *map_assoc_args
     );

DESCRIPTION

This function returns the negotiated association values corresponding to an incoming Result-Or-Argument object previously supplied by Receive(). The caller provides a request_mask to identify which values are to be returned in result objects.

This function may be used with automatic association management enabled or disabled or with automatic dialog handling enabled or disabled. In any case, the values returned are those associated with the underlying association or dialog within which the incoming Result-Or-Argument arrived.

Certain reqeusted values may not be available for the input object (that is, inappropriate for the underlying protocol) and may therefore be absent from the result. The values actually returned are indicated by the function result.

ARGUMENTS

Result-Or-Argument (Object(*))

This object contains an asynchronous response or indication, as previously returned to the user from the Receive() function.

Request-Mask (Integer)

The request-mask indicates which association values should be returned as result objects. The mask is composed of bit values that must be set on (‘1’) to request that the corresponding association value be returned. Association values that can be obtained by calling this function are:

• presentation-Context-List
• responder-Address
• responder-Title
• application-Context
• application-Context-List
• version-List

RESULTS

Result-Mask (Integer)

A mask indicating which association values have been returned as part of the result objects below. This mask has the same structure as the Request-Mask argument. All bits off (‘0’) indicates no values were available for the input object.

Pres-Layer-Args (Object(Presentation-Layer-Args))

Upon completion of this function, this object contains the negotiated values associated with the Result-Or-Argument object. This object is returned only when one of the following Result-Mask bits is set on:

• ‘MAP_T_PRESENTATION_CONTEXT_LIST’

Otherwise, [[MAP_ABSENT_OBJECT]] is returned for this object.

Acse-Args (Object(Acse-Args))

Upon completion of this function, this object contains the negotiated values associated with the Result-Or-Argument object. This object is returned only when one of the following Result-Mask bits is set on:

• ‘MAP_T_RESPONDER_ADDRESS’
• ‘MAP_T_RESPONDER_TITLE’
• ‘MAP_T_APPLICATION_CONTEXT’

Otherwise, [[MAP_ABSENT_OBJECT]] is returned for this object.

Map-Assoc-Args (Object(Map-Assoc-Args))

Upon completion of this function, this object contains the negotiated values associated with the Result-Or-Argument object. This object is returned only when the one of the following Result-Mask bits is set on:

• ‘MAP_T_APPLICATION_CONTEXT_LIST’
• ‘MAP_T_VERSION_LIST’

otherwise, [[MAP_ABSENT_OBJECT]] is returned for this object.

ERRORS

This function can return error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] or [[MAP_INSUFFICIENT_RESOURCES]].

4.11 Get-last-error()

NAME

Get-last-error — retrieve secondary return code of the most recent function call Communications or System error.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_get_last_error(
             OM_workspace        workspace,
             OM_uint32          *additional_return_error
     );

DESCRIPTION

This function is used to return additional error information related to the last function call that returned a status of:

• [[MAP_E_COMMUNICATIONS_PROBLEM]]
• [[MAP_E_BROKEN_SESSION]]
• [[MAP_E_INVALID_CONNECTION_ID]]
• [[MAP_E_SYSTEM]]

The returned integer value is implementation dependent.

In a multiple thread environment where there are multiple XMAP function calls, additional error information is stored in the workspace of the invoking call on a thread basis. The map_get_last_error call must be invoked from the same thread.

For most XMAP function calls, the Workspace anchor to store additional information is dervied from the ‘bound_session’. For Bind() and Wait(), the workspace parameter on the calls is used.

ARGUMENTS

Workspace (Workspace)

The workspace (obtained from a prior call to Initialize() of the function call that had the status error.

RESULTS

Status (Status)

Indicates whether or not the function call completed.

Additional-Error (Integer)

The secondary integer related to the last function call that returned a Communications or System error.

ERRORS

This function can return error constants [[MAP_NO_WORKSPACE]] or [[MAP_INVALID_SESSION]].

4.12 Initialize()

NAME

Initialize — initialize the interface.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     OM_workspace map_initialize(
             void
     );

DESCRIPTION

This function performs any necessary initialization of the interface and allocates a workspace. It must be called before any other mobile application interface functions are called. It may be called multiple times, in which case each call returns a workspace that is distinct from other workspaces created by Initialize() but not yet deleted by Shutdown().

ARGUMENTS

None.

RESULTS

Workspace (Workspace)

Upon successful completion, contains a handle to a workspace in which OM objects can be created and manipulated. Objects created in this workspace, and only such objects, may be used as arguments to the other management interface functions. This function returns NULL if it fails.

ERRORS

None.

SEE ALSO

Shutdown().¹⁹

EXAMPLE

     OM_workspace workspace;
     
     if ((workspace = map_initialize()) == NULL) {
     	exit(1);
     }

4.13 Issue()

NAME

Issue — issue pending service requests and responses.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_issue(
             OM_private_object       session,
             OM_private_object       context,
             OM_sint32               dialog_id
     );

DESCRIPTION

This function is one of a group of dialogue handling functions: Open(), Accept(), Refuse(), Issue(), Close(), Abort(), Receive(), used to manage MAP dialogues when AAM is disabled on a session. When AAM is enabed on a session, this dialogue hanglin function is neither necessary nor permitted.

This function is used to issue pending mobile application service requests and responses. The function can only be called in synchronous mode.

When an Open(), Accept() or Refuse() function is called, the underlying Mobile Application Service provider might not issue the corresponding TCAP transactions immediately, but may wait for the accumulation of mobile application service requests or responses to combine with the dialogue. The Issue() function tells the underlying Mobile Application Service provider to release pending dialogue handling primitives with the service requests and responses currently accumulated.

One typical order of dialogue handling function calls would be as follows:

• Bind() — bind the session.
• Open() — open the dialogue.
• Service-req() — generate one or more service requests.
• Issue() – issue pending dialogue handing and accumulated service requests or responses.
• Service-req() — generate one or more service requests.
• Close() — close the dialogue (also issuing any pending dialogue handling and accumulated service requests or responses).

ARGUMENTS

Session (Object(Session))

The mobile application session against which this operation is to be performed. This must be a private object previously reutrned from Bind().²⁰

Context (Object(Context))

The mobile application context to be used for this operation. This argument must be a private object or the constant Default-Context (‘MAP_DEFAULT_CONTEXT’).

Dialog-ID (Integer)

The Dialog-ID of the requested dialog to which the reply applies. This Dialog-ID must have been returned from a call to Receive() for the corresponding association for which pending service requests and responses are being issued.

RESULTS

Status (Status)

Indicates whether or not the Issue request was completed.

ERRORS

This function can return a System-Error or one of the following Library-Errors: bad-class, bad-context, bad-result, bad-session, miscellaneous, no-such-operation, not-supported, session-terminated.

This function can return a Communications-Error.

This function can also return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] and [[MAP_INSUFFICIENT_RESOURCES]].

CORRESPONDENCE

This function corresponds to the MAP-DELIM request primitive of 3GPP TS 29.002 Section 7.

4.14 Negotiate()

NAME

Negotiate — negotiate features of the interface and service.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_negotiate(
             MAP_feature         feature_list[],
             OM_workspace        workspace
     );

DESCRIPTION

This function negotiates features of the interface; each feature is represented as an Object Identifier. Several features are defined and registered within this specification. Features may also include mobile application services packages, vendor extensions, and new features defined in future versions of this specification. Features can be negotiated after a workspace has been initialized, and can be renegotiated any time until the workspace is discarded. Note that all sessions on a given workspace share the same features.

ARGUMENTS

Feature-List (Feature-List)

An ordered sequence of features, each represented by an object identifier and a request value. The request value can contain one of the following values: Activate, Deactivate, Query State, and Query Supported.

The sequence is terminated by an object identifier having no components (a length of zero and a value of the data pointer in the C representation). The response value is returned upon completion of the Negotiate invocation.

In the C binding, the Feature-List argument is a single array of structures of type MAP_feature, which is defined as:

          
               #define MAP_ACTIVATE            0
               #define MAP_DEACTIVATE          1
               #define MAP_QUERY_STATE         2
               #define MAP_QUERY_SUPPORTED     3
               
               typedef struct {
                       OM_object_identifier    feature;
                       OM_sint                 request;
                       OM_boolean              response;
               } MAP_feature;
          

The following Features are defined and registered by this specification:

• Mobile Application Packages
  The GSM Mobile Application package and the ANSI Mobile Application package are specified in Interface Class Definitions. Additional Mobile Application packages may be specified in the future. Note that multiple Mobile Application Packages can be activated within the same workspace.
• Automatic Association Management
  This feature provides for automatic establishment and release of the underlying protocol associations(s) (if any); refer to Automatic Association Management. The Object-Identifier associated with this feature is ‘{ iso(1) org(3) dod(6) internet(1) private(4) enterprises(1) openss7(29591) xom-packages(1) xmap(1) common(1) automatic-association-management(1) }’. This Object-Identifier is represented by the constant ‘MAP_AUTOMATIC_ASSOCIATION_MANAGEMENT’. Automatic Association Management is enabled by default.
• Automatic Dialog Handling This feature provides for automatic establishment and release of the underlying protocol dialog(s) (if any); refer to Automatic Dialog Handling. The Object-Identifier associated with this feature is ‘{ iso(1) org(3) dod(6) internet(1) private(4) enterprises(1) openss7(29591) xom-packages(1) xmap(1) common(1) automatic-dialog-handling(2) }’. This Object-Identifier is represented by the constant ‘MAP_AUTOMATIC_DIALOG_HANDLING’.
• Automatic ASN.1 BER Encoding and Decoding
  This feature provides for automatic encoding and decoding of OM class and attribute types using ASN.1 BER;refer to Encoding and Decoding. The Object-Identifier associated with this feature is ‘{ iso(1) org(3) dod(6) internet(1) private(4) enterprises(1) openss7(29591) xom-packages(1) xmap(1) common(1) automatic-decoding(3) }’. This Object-Identifier is reprsented by the constant ‘MAP_AUTOMATIC_DECODING’. Automatic ASN.1 BER Encoding and Decoding is enabled by default.

Mobile Application Services packages are also negotiated as part of the Feature-List. Mobile Application Services packages may be defined by the OpenSS7 Project, by standards organizations or consortia, by vendors, or by users.

Registered Object Identifiers representing future features and vendor extensions may also be included in the Feature-List for negotiation.

Workspace

The handle to the workspace for which features are negotiated.

RESULTS

Status (Status)

Whether or not the function completed successfully.

Response (Boolean-List)

If the function completed successfully, this result contains an ordered list of Boolean values, with the same number of elements as the Feature-List. The significance of the values is shown as follows:

Request	Response	Meaning
Activate	True	Activated
	False	Cannot activate feature (or the feature is not supported).
Deactivate	True	Deactivated
	False	Cannot deactivte feature (or the feature is not supported).
Query-state	True	Activated
	False	Deactivated (or the feature is not supported).
Query-supported	True	Supported
	False	Not supported
Invalid	True	Cannot be returned
	False	Invalid argument

In the C binding, this result is combined with the Feature-List argument as a single array of structures of type MAP_feature as defined above.

ERRORS

This function can return a System-Error or Library-Error “miscellaneous”.

This function does not return a Communications-Error, nor any mobile application errors.

The function can also return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] and [[MAP_INSUFFICIENT_RESOURCE]].

EXAMPLE

     MAP_status status;
     OM_workspace workspace;
     int i;
     
     workspace = map_initialize();
     
     MAP_feature feature_list[] = {
     	{MAP_COMMON_PKG, MAP_ACTIVATE, 0}
     	, {MAP_GSM_PKG, MAP_ACTIVATE, 0}
     	, {MAP_GSM_SM_PKG, MAP_ACTIVATE, 0}
     	, {MAP_GSM_LS_PKG, MAP_ACTIVATE, 0}
     	, {MAP_GSM_IN_PKG, MAP_ACTIVATE, 0}
     	, {MAP_GSM_CH_PKG, MAP_ACTIVATE, 0}
     	, {NULL, 0, 0}
     };
     
     if ((status = map_negotiate(feature_list, workspace)) != MAP_SUCCESS)
     	exit(1);
     
     for (i = 0; i < 6; i++)
     	if (!feature_list[i].response)
     		exit(1);

4.15 Open()

NAME

Open – Request establishment of a Mobile Application Services association (dialogue).

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_open(
             OM_private_object       session,
             OM_private_obect        context,
             OM_object               argument,
             OM_private_object       *result_return,
             OM_sint32               *dialog_id_return
     );

DESCRIPTION

This function is used to request the creation of a mobile application entity association (dialogue). The service is defined as a confirmed service: a reply is expected.

This operation may be called in asynchronous mode. Note that when operating in this mode, results may not only be locally discarded (when Abandon() is used), as may be done with outer asynchronous calls.

ARGUMENTS

Session (Object(Session))

The mobile application session against which this operation is performed. This must be a private object previously returned from Bind().²¹ This session must also have ADH (Automatic Dialog Handling) disabled.

Context (Object(Context))

The mobile application context to be used for this operation. This argument must be a private object.

Argument (Object(Assoc-Argument))

The information supplied as the argument of an Assoc operation. This is an Assoc-Argument object with optional ACSE information contained within it. When called asynchronously, a partially connected Session object is returned in the Result of this function.

RESULTS

Status (Status)

If the function is called syncrhonously, the value success indicated that the action was completed. If called asynchronously, it indicates that the operation was initiated.

Result (Object(*))

Upon successful completion of a synchronous call, the results is one of the following:

• When the Open request has been accepted by the remote peer, one instance of the OM class Accept-Result Object is returned. This Accept-Result object contains a session attribute that returns a Session object for which a dialog has been fully formed. The Accept-Result object also contains the final negotiated dialog parameters for the new dialog.
• When the Open request has been refused by the remote peer, one instance of the OM class Refuse-Result Object is returned. This Refuse-Result object contains information as to why the dialog was refused. No session attribute is present in this result and no dialog session is formed.
• When the Open request has been aborted by the remote peer or by the provider, one instance of the OM class Abort-Argument is returned. This Abort-Argument object contains information pertaining to the abort. No session attribute is present in this result and no dialog session is formed.

Upon successful completion of an asynchronous call, a partially formed dialog Session object is returned in the Result.

Note:

The original Session object passed to this function is unaffected and still remains in the bound or associated state. This session object can still be used in additional concurrent Open() or Receive() function calls.

Dialog-ID (Integer)

The returned Dialog-ID of the management operation when used asynchronously.

ERRORS

This function can return one of the following Library-Errors: bad argument, bad-class, bad-context, bad-session, miscellaneous, missing-type, session-terminated, reply-limit-exceeded, time-limit-exceeded.

This function can return a Communications-Error.

This function can also return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] and [[MAP_INSUFFICIENT_RESOURCES]].

SEE ALSO

Abort(),²² Assoc-rsp(), Accept(),²³ Refuse().²⁴

CORRESPONDENCE

This function corresponds to the MAP-OPEN request primitive of 3GPP TS 29.002 Section 7.

4.16 Receive()

NAME

Receive — get the argument of an operation or retrieve the (partial) result of an asynchronously executed operation.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_receive(
             OM_private_object   session,
             OM_sint            *mode_return,
             OM_sint            *primitive_return,
             OM_sint            *completion_flag_return,
             MAP_status         *operation_status_return,
             OM_private_object  *result_or_argument_return,
             OM_sint32          *invoke_or_dialog_id_return
     );

DESCRIPTION

This function is used to retrieve the argument of an invoked operation and to retrieve a partial result (linked reply) or the completed result of a previous asynchronous operation.

The function results include two status indications. One, called Status, indicates that the function call itself was successful; it is always returned. The other, called Operation-Status, is used to return the status of the completed asynchronous operation, and is only returned if there is one.

ARGUMENTS

Session (Object(Session))

The moble application session against which this mobile application operation is performed. This must be a private object previously returned from Bind(),²⁵ or a connected or partially connected session object returned from Open(),²⁶ Accept(),²⁷ or Receive().

RESULTS

Status (Status)

Takes an error value if one of the library errors or system errors listed below occurred during execution of this function. Takes the value success (‘MAP_SUCCESS’) if this function returned successfuly.

Primitive (Integer)

The mobile application service primitives (‘MAP_SERVICE_IND’, ‘MAP_SERVICE_CNF’).

The MAP association service primitives (‘MAP_OPEN_IND’, ‘MAP_ACCEPT_CNF’, ‘MAP_REFUSE_CNF’, ‘MAP_DELIM_IND’, ‘MAP_CLOSE_IND’, ‘MAP_ABORT_IND’, ‘MAP_P_ABORT_IND’).

Determines the operation of this result or argument.

This result is only valid if Completion-Flag has the value completed, incoming or partial.

Mode (Integer)

This indicates the mode of an indication. When confirmed (‘MAP_T_CONFIRMED’) the invoked operation has to be confirmed, a reply is expected. When non-confirmed (‘MAP_T_NON_CONFIRMED’), the requested service is not to be confirmed.

This result is only valid if Completion-Flag has the value incoming.

Completion-Flag (Integer)

This flag indicates the statue of the received data, if any.

completed

(‘MAP_COMPLETED’)
This flag indicates that a final response has been received. For mobile application primitives this may be the confirmation for a service request or the last confirmation of a linked reply. In the latter case, the Result-Or-Argument parameter will be the Absent-Object.

incoming

(‘MAP_INCOMING’)
An indication has been received.

nothing

(‘MAP_NOTHING’)
There are no indications or confirmations to receive. Further, there are no outstanding asynchronous requests.

outstanding

(‘MAP_OUTSTANDING’)
There are no indications or confirmations to receive. There are still outstanding requests, but no confirmations have yet arrived.

parial

(‘MAP_PARTIAL’) A confirmation has been received which is part of a linked reply. This is used for all but the last in a series of linked replies. (See completed, above.)

This result is only valid if Status has the value success. In that case, the validity of the other results is given as follows:

Completed	yes(1)	no	yes	yes(1)	yes
Incoming	yes	yes	no	yes	yes
Nothing	no	no	no	no	no
Outstanding	no	no	no	no	no
Partial(3)	yes(1)	no	yes	yes(1)	yes

Operation-Status (Status)

Takes an error value if a communications error occurred during the execution of the asynchronous operation, and success (‘MAP_SUCCESS’) otherwise. The possible error values are listed for each individual operation in the corresponding function description.

This result is only valid if Completion-Flag has the value completed or partial.

Result-or-Argument (Object(*))

This object contians the results of an asynchronous request, or information about an indication. The class of object received is dependent upon the values of the Primitive and Completion-Flag parameters. The following table for the three applicable Completion-Flag values. The actual class returned is dependent on the value of Primitive.

Completion-Flag set to completed:

Service-Result	‘MAP_SERVICE_CNF’
Service-Error	‘MAP_SERVICE_CNF’
Service-Reject	‘MAP_SERVICE_CNF’
Accept-Result	‘MAP_ACCEPT_CNF’
Refuse-Result	‘MAP_REFUSE_CNF’
Absent-Object	All confirmations.

Note that Absent-Object may be returned in two cases:

1. The confirmation contains no data.
2. As the terminator of a linked reply list. In this case, the Invoke-or-Dialog-ID parameter can be used to determine which linked reply has been terminated.

Completion-Flag set to incoming:

Service-Argument	‘MAP_SERVICE_IND’
Open-Argument	‘MAP_OPEN_IND’
Close-Argument	‘MAP_CLOSE_IND’
Abort-Argument	‘MAP_ABORT_IND’

Completion-Flag set to partial:

Linked-Reply-Argument

For Completion-Flag values of completed or partial, the Result-or-Argument parameter is valid only if the Operation-Status contains the value success. The parameter is not valid for Completion-Flag values of nothing or outstanding.

Invoke-or-Dialog-ID (Integer)

The Invoke-ID or Dialog-ID of the operation whose error, result or argument is being returned.

This result is only valid of the Status has the value success and Completion-Flag has the value completed, partial or incoming.

ERRORS

This function can return a System-Error or one of the following Library-Errors: bad-class, bad-context, bad-session, miscellaneous, session-terminated, time-limit-exceeded.

This function does not report any Communication-Errors, in its Status result. (Any such errors related to the completed asynchronous operation is reported in Operation-Status, as described above.)

This function can also return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] and [[MAP_INSUFFICIENT_RESOURCES]].

4.17 Refuse()

NAME

Refuse – refuse an indicated association operation.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_refuse(
             OM_private_object       session,
             OM_private_object       context,
             OM_object               response,
             OM_sint32               dialog_id
     );

DESCRIPTION

This function is one of a group of dialogue handling functions: Open(), Accept(), Refuse(), Issue(), Close(), Abort(), Receive(), used to manage the MAP dialogue when AAM is disabled on a session. When AAM is enabled on a session, this dialogue handling function is neither necessary nor permitted.

This function is used to refuse a previously indicated Open operation. This function can only be called in syncrhonous mode.

ARGUMENTS

Session (Object(Session))

The mobile application session against which this operation is to be performed. This must be a private object previously returned from Bind().²⁸

Context (Object(Context))

The mobile application context to be used for this operation. This argument must be a private object or the constant Default-Context (‘MAP_DEFAULT_CONTEXT’).

Response (Object(Refuse-Result))

The information supplied in refusal of the previously indicated Open operation. This is an instance of OM class Refuse-Result, indicating that the open indication is to be refused. The user provides alternate ACSE parameters in this object as input to the service provider. The refuse-Reason and diagnostic-Information can be set to indicate why the reject occured.

Dialog-ID (Integer)

The Dialog-ID of the requested dialog to which the reply applies. This Dialog-ID must have been returned from a call to Receive() for the corresponding association that is being accepted.

RESULTS

Status (Status)

Indicates whether or not the Refuse response was completed.

ERRORS

This function can return a System-Error or one of the following Library-Errors: bad-class, bad-context, bad-result, bad-session, miscellaneous, no-such-operation, not-supported, session-terminated.

This function can return a Communications-Error.

This function can also return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] and [[MAP_INSUFFICIENT_RESOURCES]].

CORRESPONDENCE

This function corresponds to the MAP-OPEN response primitive (with a parameter indicating refusal) of 3GPP TS 29.002 Section 7.

4.18 Release-req()

NAME

Release-req —

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_release_req(
     );

DESCRIPTION

ARGUMENTS

RESULTS

ERRORS

4.19 Release-rsp()

NAME

Release-rsp —

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_release_rsp(
     );

DESCRIPTION

ARGUMENTS

RESULTS

ERRORS

4.20 Service-req()

NAME

Service-req — request mobile appliction service.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_service_req(
             OM_private_object   session,
             OM_private_object   context,
             OM_object           argument,
             OM_private_object  *result_return,
             OM_sint32          *invoke_id_return
     );

DESCRIPTION

This function is used to request mobile application service.

ARGUMENTS

Session (Object(Session))

The mobile application session against which this operation is performed. THis must be a private object previously returned from Bind().

Context (Object(Context))

The mobile application context to be used for this operation. This argument must be a private object or the constant Default-Context (‘MAP_DEFAULT_CONTEXT’).

The service may be requested in a confirmed mode or a non-confirmed mode. In confirmed mode, a reply is expected.

Argument (Object(Service-Argument))

The information supplied as the argument of a mobile application service request is an instance of a subclass of the OM class Service-Argument. Normally, concrete subclasses of this class are defined in Mobile Application Services packages. For example, the MO-Forward-SM-Arg subclass of Service-Argument is defined in the GSM Short Message Services package (see MO-Forward-SM-Arg) and may be used as an argument to this function.

RESULTS

Status (Status)

If the function is called synchronously, the values success indicated that the action was completed. If called asynchronously, it indicates that the operation was initiated.

Result (Object(*))

Upon successful completion of a syncrhonous coall, when the operation was requested in a confirmed mode, the result is one of the following:

• When the service is requested in a non-confirmed mode, no results are expected and the constant Absent-Object (‘MAP_ABSENT_OBJECT’) is returned as the result.
• When a confirmed mode services is requested, this is indicated by on instance of the OM class Service-Result, or Service-Error, or when multiple replies are provided, an instance of OM class Multiple-Reply, which contains a set of instances of the OM class Service-Linked-Reply-Argument. Each Service-Linked-Reply-Argument contains exactly one of the following OM attributes:
  • service-Result
  • service-Error
  • processing-Failure

Invoke-ID (Integer)

The Invoke-ID of the initiated mobile application service operation when invoked asynchronously. It is significant in the case of a confirmed mode request only.

ERRORS

This function can return a System-Error or one of the following Library-Errors: bad-argument, bad-class, bad-context, bad-session, miscellaneous not-supported, session-terminated, reply-limit-exceeded, time-limit-exceeded.

This function can return a Communications-Error.

This function can also return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] or [[MAP_INSUFFICIENT_RESOURCES]].

SEE ALSO

Abandon(),²⁹ Service-rsp().³⁰

CORRESPONDENCE

This function corresponds to the MAP-XXX request primitive of 3GPP TS 29.002 Section 7.

4.21 Service-rsp()

NAME

Service-rsp — reply to a requested mobile application service operation.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_service_rsp(
             OM_private_object   session,
             OM_private_object   context,
             OM_object           response,
             OM_sint32           invoke_id
     );

DESCRIPTION

This function is used to reply to a previously invoked confirmed mobile application service operation. This function can only be called in synchronous mode.

ARGUMENTS

Session (Object(Session))

The mobile application session against which the operation is performed. This must be a private object previously returned from Bind().

Context (Object(Context))

The mobile application context to be used for this operation. This argument must be a private object or the constant Default-Context (‘MAP_DEFAULT_CONTEXT’).

Response (Object(*))

The information supplied as response to an service operation. The response is one of the following:

• An instance of a concrete subclass of the OM class Service-Result as the response.
• An instance of a concrete subclass of the OM class Service-Error as the response, including the problem cause and its associated parameter that may be returned. See Service-Error.
• An instance of a concrete subclass of the OM class Service-Reject including the problem cause and its associated parameter may be returned: duplicate-invocation, mistyped-argument, resource-limitation, unrecognized-operation.
• When a service request requires multiple responses, this is indicated by one or more Service-rsp() calls, once for each response, followed by a final “empty” Service-rsp(). Each Service-rsp() call includes a response that contains an instance of a concrete subclass of OM class Service-Linked-Reply-Argument, containing exacly one of the following OM attributes:
  • service-Result
  • service-Error
  • processing-Failure
  The final “empty” Service-rsp() call includes a response that contains only the constant Absent-Object (‘MAP_ABSENT_OBJECT’).

For more details about the OM classes and OM attributes mentioned above, refer to Interface Class Definitions.

Invoke-ID (Integer)

The Invoke-ID of the requested operation to which the reply applies. This is the Invoke-ID that was returned from a call to Receive() that indicated the service request to which this service response corresponds.

RESULTS

Status (Status)

Indicates whether or not the action response was completed.

ERRORS

This function can return a System-Error or one of the following Library-Errors: bad-class, bad-context, bad-error, bad-linked-reply, bad-result, bad-session, miscellaneous, no-such-operation, not-supported, session-terminated.

This function can return a Communications-Error.

This function can also return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] or [[MAP_INSUFFICIENT_RESOURCES]].

SEE ALSO

Receive(),³¹ Service-req().³²

CORRESPONDENCE

This function corresponds to the MAP-XXX response primitive of 3GPP TS 29.002 Section 7.

4.22 Service-parameter()

NAME

Service-parameter –

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_xxx(
     );

DESCRIPTION

ARGUMENTS

RESULTS

ERRORS

CORRESPONDENCE

This function corresponds to the MAP-PARAMETER request primitive of 3GPP TS 29.002 Section 7.

4.23 Shutdown()

NAME

Shutdown — delete a workspace and the associated resources.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_shutdown(
             OM_workspace    workspace
     );

DESCRIPTION

This function deletes a workspace established by Initialize()³³ and all the associated resources. It may enable the service to release resources.

All the remaining opened sessions are closed, all the remaining OM objects are deleted, and the workspace is deleted.

No other function may reference the specified workspace after it has been deleted.

ARGUMENTS

Workspace (Workspace)

Specifies the workspace (obtained from a call to Initialize()) which is to be deleted.

RESULTS

Status (Status)

Inidcates whether or not the shutdown function succeeded.

ERRORS

This function can return the error constants [[MAP_NO_WORKSPACE]] or [[MAP_INSUFFICIENT_RESOURCES]].

SEE ALSO

Initialize().³⁴

EXAMPLE

     OM_workspace workspace;
     MAP_status status;
     
     if ((workspace = map_initialize()) == NULL)
     	exit(1);
     
     /* perform functions within the workspace */
     
     if ((status = map_shutdown(workspace)) != MAP_SUCCESS)
     	exit(1);
     exit(0);

4.24 Unbind()

NAME

Unbind — unbind from a mobile application session.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_unbind(
             OM_private_object   session
     );

DESCRIPTION

This function terminates the given mobile application session, and makes the argument unavailable for use with other interface functions (except Bind()).

Note that this means the results of any outstanding asynchronous operations that were intiiated uinsg the given Session can no longer be received. Any such operations may be terminated prematurely. For this reason it is recommended that all outstanding asynchronous operations are processed using Receive() before Unbind() is called.

The unbound session may be used again as an argument to Bind() possible after modification by the XOM functions (reference XOM). When it is no longer required, it must be deleted using the XOM functions.

The Library-Error “session-terminated” will be returned as the error value to a synchronous function call using the terminated session.

ARGUMENTS

Session (Object(Session))

The management session that is to be unbound. This must be a private object previously returned by Bind(). The value of the File-Descriptor OM attribute will be No-Valid-File-Descriptor (‘MAP_NO_VALID_FILE_DESCRIPTOR’) if the function succeeds. The other OM attributes will be unchanged.

RESULTS

Status (Status)

Takes the value success if Session was unbound, and take an error value if not.

ERRORS

This function can return a System-Error or one of the following Library-Errors: bad-class, bad-session, miscellaneous, session-terminated.

This function does not return a Communications-Error or any mobile application errors.

This function can return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] or [[MAP_INSUFFICIENT_RESOURCES]].

SEE ALSO

Bind().³⁵

4.25 Validate-object()

NAME

Validate-object — analyze OM-Object and return Bad-Argument details if necessary.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_validate_obejct(
             OM_workspace        workspace,
             OM_object           test_object,
             OM_private_object  *bad_argument_return
     );

DESCRIPTION

This function is used to analyze any OM-Object to validate its structure. It may be used as a debug tool prior to issuing other XMAP function calls. It may also be used after XMAP function calls that return [[MAP_E_BAD_ARGUMENT]].

It is not the intention of this function to be able to validate all OM objects in all packages. Its purpose is to validate only those primary OM objects that may be validly passed as arguments to function defined in this specification.

This function is not intended to validate private objects, only client or service generated public objects. When passed a private object, provided that the private object is of a known OM class, success will be returned. That is, the function does not analyze the contents of a private object.

ARGUMENTS

Test-Object (Object(*))

The OM-Object to analyze and validate.

Workspace (Workspace)

Specifies the workspace (obtained from a call to Initialize(), in which Bad-Argument OM object will be created if the return status is [[MAP_E_BAD_ARGUMENT]]. Test-Objects does not need to be from this workspace.

RESULTS

Status (Status)

Indicates whether or not the validation was successful. A value of [[MAP_E_BAD_ARGUMENT]] indicates a validation failure and problem details are in the Bad-Argument parameter.

Bad-Argument (Object(Bad-Argument))

When Status is [[MAP_E_BAD_ARGUMENT]], the result is one instance of the OM class Bad-Argument.

ERRORS

This function can return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INSUFFICIENT_RESOURCES]], [[MAP_E_SYSTEM]] or [[MAP_E_BAD_ARGUMENT]].

EXAMPLE

Following is a ‘C’ binding example of validating a user-generated public object from the GSM MAP Short Message services package:

     OM_object argument = {
         OM_OID_DESC(OM_CLASS, MAP_C_MO_FORWARD_SM_ARG)
         , {MAP_SM_RP_DA, OM_S_OBJECT, {
             OM_OID_DESC(OM_CLASS, MAP_C_SM_RP_DA)
             , {MAP_IMSI, MAP_S_TBCD_STRING, OM_STRING("\x21\x43\x65\x87")}
             , OM_NULL_DESCRIPTOR
           } }
         , {MAP_SM_RP_OA, OM_S_OBJECT, {
             OM_OID_DESC(OM_CLASS, MAP_C_SM_RP_OA)
             , {MAP_NO_SM_RP_OA, OM_S_NULL, NULL}
             , OM_NULL_DESCRIPTOR
           } }
         , {MAP_SM_RP_UI, OM_S_OCTET_STRING, (OM_string) {data_length, data_pointer} }
         , {MAP_IMSI, MAP_S_TBCD_STRING, OM_STRING("\x21\x43\x65\x87")}
         , OM_NULL_DESCRIPTOR
     };
     MAP_status status;
     OM_private_object bad_argument;
     
     status = map_validate_object(workspace, argument, &bad_argument);
     
     if (status == MAP_E_BAD_ARGUMENT)
         exit(1);

4.26 Wait()

NAME

Wait — wait for the availability of manaement message(s) from one or more bound Sessions.

SYNOPSIS

     #include <xom.h>
     #include <xmap.h>
     
     MAP_status map_wait(
             MAP_waiting_sessions    bound_session_list[],
             OM_workspace            workspace,
             OM_uint32               timeout
     );

DESCRIPTION

This function is used to suspend the caller until a mobile application operation is available for a bound Session. A timeout value specifies the maximum number of milliseconds to suspend before returning when no messages are available. It should be noted that, in a multithreaded environment, Wait() may report the presence of a message that will have been processed by another thread by the time the first thread call Receive() to process it.

ARGUMENTS

Bound_session_list (Bound-Session-List)

An ordered sequence of mobile application sessions to wait upon. The last value must evaluate to NULL.

Workspace (Workspace)

Specifies the workspace (obtained from a call to Initialize(), in which a MAP_status object will be created if the return status is other than [[MAP_SUCCESS]]. Session(s) specified in the bound-session-list do no need to be from this workspace.

Timeout (Integer)

The maximum number of milliseconds to suspend before returning when there are no messages from the list of Session(s). A value of zero specifies an indefinite timeout.

RESULTS

Status (Status)

Indicates whether or not the function completed successfully. A successful completion means that either a message is available from a Session or that the timeout limit has been reached. The Receive() function must be called to determine whether a message is available. (See note in description above.)

Activated (Boolean-List)

If the function was completed successfully, this result is an ordered list of Boolean values, with the same number of elements as the bound-session-list. If true, each value indicates that the corresponding Session has data waiting in queue. If false, each valud indicates that the corresponding Session does not has data waiting in queue.

In the C binding, this result is combined with the bound-session-list argument as a single array of structures of type MAP_waiting_sessions, which is defined as:

          
               typedef struct {
                       OM_private_object   bound_session;
                       OM_boolean          activated;
               } MAP_waiting_sessions;
          

ERRORS

This function can return one of the following Library-Errors: bad-address, bad-session, bad-workspace, miscellaneous, session-terminated.

The function can also return the error constants [[MAP_NO_WORKSPACE]], [[MAP_INVALID_SESSION]] and [[MAP_INSUFFICIENT_RESOURCE]].

SEE ALSO

Initialize(),³⁶ Receive(),³⁷ Bind().³⁸

EXAMPLE

Following is a ‘C’ language binding example of using the Wait() function in conjunction with the Receive() function to process indications or confirmations:

     MAP_waiting_sessions bound_session_list[] =
         { {session, OM_FALSE} , {NULL,} };
     
     for (;;) {
         if ((status = map_wait(bound_session_list, workspace, 0)) != MAP_SUCCESS)
             exit(1);
         if (bound_session_list[0].activated) {
             OM_sint mode;
             OM_sint primitive;
             OM_sint completion_flag;
             MAP_status operation_status;
             OM_private_object result;
             OM_sint32 received_invoke_id;
     
             if ((status = map_receive(session, &mode, &primitive, &operation_status,
                                 &result, &received_invoke_id)) != MAP_SUCCESS)
                     exit(1);
             /* process received result */
             om_delete(result);
         }
     }

5 Interface Class Definitions

This chapter defines, in alphabetical order, the OM classes that constitute the Common MAP package (COMMON), the GSM Mobile Application package (GSM) and the ANSI Mobile Application package (ANSI). The common errors are defined in the Common MAP package, while the variant specific errors are defined in the GSM MAP and ANSI MAP packages.

The Object-Identifier associated with the Common MAP package is:

{ iso(1) org(3) dod(6) internet(1) private(4) enterprises(1) openss7(29591) xom-packages(1) xmap(1) common(1) }

This Object-Identifier is represented by the constant Common-Package (‘MAP_COMMON_PKG’).

The Object-Identifier associated with the GSM MAP package is:

{ iso(1) org(3) dod(6) internet(1) private(4) enterprises(1) openss7(29591) xom-packages(1) xmap(1) gsm(2) }

This Object-Identifier is represented by the constant GSM-Package (‘MAP_GSM_PKG’).

The Object-Identifier associated with the ANSI MAP package is:

{ iso(1) org(3) dod(6) internet(1) private(4) enterprises(1) openss7(29591) xom-packages(1) xmap(1) ansi(3) }

This Object-Identifier is represented by the constant ANSI-Package (‘MAP_ANSI_PKG’).

The Object-Identifier associated wtih the GSM MAP Short Message Service package is:

{ iso(1) org(3) dod(6) internet(1) private(4) enterprises(1) openss7(29591) xom-packages(1) xmap(1) gsm(2) sm(22) }

This Object-Identifier is represented by the constant GSM-SM-Package (‘MAP_GSM_SM_PKG’).

The XMAP API may also make use of Mobile Application Services packages. These optional packages define OM classes that are additional to those in the Mobile Application packages, to extend the capabilities of the interface.

The concepts of OSI-Abstract-Data Manipulation are briefly described in Relationship to Data Abstraction Services. The notation is introduced below. Both are fully explained in the XOM Specification (see reference XOM).

Each OM class is described in a separate section, which identifies the OM attributes specific to that OM class. The OM classes are listed in alphabetic order; the OM attributes for each OM class are listed in the order in which they occur in corresponding ASN.1 definitions. The OM attributes that may be found in an instance of an OM class are those OM attributes specific to that OM class and those inherited from each of its super-classes. The OM class-specific OM attributes are defined in a table. The table gives the name of each OM attribute, the syntax of each of its values, any restrictions upon the length (in bits, octets (bytes), or characters) of each value, any restrictions upon the number of values, and the value, if any, the OM-Create() function supplies.

Vendor Extensions

Vendors may provide additional OM attributes in their implementation of particular OM classes and their individual documentation will give details of the specification and usage of these. Extensions must be negotiated through use of the Negotiate() function.

All such OM attributes have default values which lead to the behaviour described in this specification.

5.1 Global Class Hierarchy

This section depicts the hierarchical organization of the OM classes defined in this chapter, and thus shows which OM classes inherit additional OM attributes from their super-classes. Sub-classification is indicated by indentation, and the names of abstract OM classes are rendered in italics. Thus, for example, the concrete class Itut-SCCP-Address is an immediate subclass of the abstract class Address which in turn is an immediate subclass of the abstract class Object. The Create() function applies to all concrete OM classes.

The application is not permitted to create or modify instances of some OM classes, because these OM classes are only returned by the interface and never supplied to it (for example, some subclasses of Error).

5.1.1 Interface Common Objects

• Object (defined in the XOM Specification: see reference XOM)
  • Abort-Argument
  • Acse-Args
  • Address
  • Assoc-Argument
  • Assoc-Information
  • Assoc-Result
  • Context
  • Extension
    • SNMP-Object-Name
  • Presentation-Context
  • Presentation-Layer-Args
  • Session
  • Title

5.1.2 Interface Common Error Definitions

• Object (defined in the XOM Specification: see reference XOM)
  • Bad-Argument
  • Error
    • Service-Error
    • Service-Reject

5.1.3 GSM MAP Package Objects

• Object (defined in the XOM Specification: see reference XOM)

5.1.3.1 GSM SM package Objects

• Object (defined in the XOM Specification: see reference XOM)

5.1.4 ANSI MAP Package Objects

• Object (defined in the XOM Specification: see reference XOM)

5.2 Common MAP Package

The Common MAP package introduces some additional OM syntaxes that are derivations of the String(Octet) syntax. These additional OM syntaxes are used to represent digit strings for telephony numbers and SCCP addresses.

5.2.1 String(TBCD)

This OM syntax is indicated in OM Attribute tables as String(TBCD).

In the C binding, the OM Syntax name for String(TBCD) is declared as ‘MAP_S_TBCD_STRING’.

A TBCD string is a Telephony Binary Coded Decimal encoding where digits ‘0’ through ‘9’, ‘*’, ‘#’, ‘a’, ‘b’ and ‘c’ keys are coded ‘0000’ through ‘1001’, ‘1010’, ‘1011’, ‘1100’, ‘1101’ and ‘1110’. The (2n)'th digit is encoded in the n'th octet in bits ‘4321’ and the (2(n-1)+1)'th digit iin bits ‘8765’. Code ‘1111’ is used as a filler when the number of digits is odd.

A Telephony Binary Coded Decimal (TBCD) String is used to represent several digits from ‘0’ through ‘9’, ‘*’, ‘#’, ‘a’, ‘b’, ‘c’, two digits per octet, each digit encoded ‘0000’ to ‘1001’ (‘0’ to ‘9’), ‘1010’ (‘*’), ‘1011’(‘#’), ‘1100’ (‘a’), ‘1101’ (‘b’), ‘1110’ (‘c’); ‘1111’ used as a filler when there is an odd number of digits. Bits ‘8765’ of octet n encodes digit 2n. Bits ‘4321’ of octet n encoding digit 2(n-1)+1.

5.2.2 String(Sccp-Address)

This OM syntax is indicated in OM Attribute tables as String(Sccp-Address).

In the C binding, the OM Syntax name for String(Sccp-Address) is declared as ‘MAP_S_SCCP_ADDRESS_STRING’.

An SCCP Address string is a encoded octet string where the encoding is the encoding of an SCCP address in either ITU-T or ANSI format in accordance with the format specified for the SCCP Called Party Address in ANSI T1.112/2000 Section 3.4 and ITU-T Recommendation Q.713 Section 3.4. This encoding is formatted as follows:

Octet 1

The first octet contains the address indicator, which is always present. The bits of the address indicator are interpreted as follows:

bit 8

0

A ‘0’ in bit 8 indicates that the address is formatted as an ITU-T address.

1

A ‘1’ in bit 8 indicates that the address is formatted as an ANSI address.

bit 7

0

A ‘0’ in bit 7 indicates that SCCP translation is required and routing is based on global title.

1

A ‘1’ in bit 7 indicates that SCCP translation is not required and routing is based on signalling point code and subsystem number.

bits 6543

These bits contain the global title indicator that determines the format of the Global Title.

bit 2

0

A ‘0’ in bit 2 indicates that the address does not contain a signalling point code.

1

A ‘1’ in bit 2 indicates that the address contains a signalling point code.

bit 1

0

A ‘0’ in bit 1 indicates that the address does not contain a subsystem number.

1

A ‘1’ in bit 1 indicates that the address contains a subsystem number.

ITU-T Format

When bit 8 in octet 1 is set to ‘0’, the remainder of the address is formatted according to ITU-T format as follows:

Octet 2a and 2b

Octets 2a and 2b, when present as indicated by the point code indicator (bit 2 in Octet 1), contains the ITU-T formatted signalling point code. Otherwise, octets 2a and 2b are not included. Octet 2a contains the least significant eight bits of the 14-bit signalling point code; octet 2b contains the most significant 6-bits of the signalling point code, aligned to the least significant bit, with the two most significant bits padded to zeroes.

Octet 3

Octet 3, when present as indicated by the subsystem number indicator (bit 1 in Octet 1), contains the ITU-T formatted subsystem number. Otherwise, octet 3 is not included.

Global Title

GTI ‘0000’

When the global title indicated is coded ‘0000’, there is no global title octets in the address.

GTI ‘0001’

When the global title indicates is coded ‘0001’, the global title octets are formatted as follows:

Octet 4a

Contains the nature of address indicator.

Octet 5a and onwards.

Contains the address signals. When BCD encoding is indicated, the address signals are in the format of a String(TBCD).

GTI ‘0010’

When the global title indicates is coded ‘0010’, the global title octets are formatted as follows:

Octet 4a

Contains the translation type.

Octet 5a and onwards

Contains the address signals. When BCD encoding is indicated, the address signals are in the format of a String(TBCD).

GTI ‘0011’

When the global title indicates is coded ‘0011’, the global title octets are formatted as follows:

Octet 4a

Contains the translation type.

Octet 4b

Contains the numbering plan and encoding scheme as follows:

bits 8765

Contain the numbering plan.

bits 4321

Contain the encoding scheme.

Octet 5a and onwards

Contains the address signals. When BCD encoding is indicated, the address signals are in the format of a String(TBCD).

GTI ‘0100’

When the global title indicates is coded ‘0100’, the global title octets are formatted as follows:

Octet 4a

Contains the translation type.

Octet 4b

Contains the numbering plan and encoding scheme as follows:

bits 8765

Contain the numbering plan.

bits 4321

Contain the encoding scheme.

Octet 4c

Contains the nature of address indicator (with the odd/even indicator unused).

Octet 5a and onwards

Contains the address signals. When BCD encoding is indicated, the address signals are in the format of a String(TBCD).

ANSI Format

When bit 8 in octet 1 is set to ‘1’, the remainder of the address is formatted according to ANSI format as follows:

Octet 2

Octet 2, when present as indicated by the subsystem number indicator (bit 1 in Octet 1), contains the ANSI formatted subsystem number. Otherwise, octet 2 is not included.

Octets 3a, 3b, 3c

Octets 3a, 3b, 3c, when present as indicated by the point code indicator (bit 2 in Octet 1), contains the ANSI formatted signalling point code. Otherwise, octets 3a, 3b and 3c are not included. Octet 3a contains the member component of the signalling point code; 3b the cluster; and 3c the network.

Global Title

GTI ‘0000’

When the global title indicated is coded ‘0000’, there is no global title octets in the address.

GTI ‘0001’

When the global title indicates is coded ‘0001’, the global title octets are formatted as follows:

Octet 4a

Contains the translation type.

Octet 4b

Contains the numbering plan and encoding scheme as follows:

bits 8765

Contain the numbering plan.

bits 4321

Contain the encoding scheme.

Octet 5a and onwards

Contains the address signals. When BCD encoding is indicated, the address signals are in the format of a String(TBCD).

GTI ‘0010’

When the global title indicates is coded ‘0010’, the global title octets are formatted as follows:

Octet 4a

Contains the translation type.

Octet 5a and onwards

Contains the address signals. When BCD encoding is indicated, the address signals are in the format of a String(TBCD).

5.2.3 Abort-Argument

An instance of OM abstract class Abort-Argument represents the base information passed as the Argument argument to the Abort() function (see Abort) or returned from the Receive() function (see Receive) in the Result-Or-Argument result for a user abort indication.

This OM class is an abstract class with several defined concrete subclasses: GSM-Abort-Argument (see GSM-Abort-Argument) and ANSI-Abort-Argument.

An instance of this OM class has the OM attributes of its superclasses, Object, Error; it does not define any attributes of its own.

Because abort causes are Mobile Application package specific, this abstract OM class does not define any of the values for the problem or parameter attributes of the Error superclass.

See also Service Error.

5.2.4 Abort-Result

An instance of abstract OM class Abort-Result represents the base information passed as the Argument argument to the Abort-req() function (see Abort-req) or returned from the Receive() function (see Receive) in the Result-Or-Argument result for an association abort indication.

This OM class is an abstract class with several defined concrete subclasses: GSM-Abort-Result (see GSM-Abort-Result) and ANSI-Abort-Result.

An isntance of this OM class has the OM attributes of its superclasses, Object, Error; it does not define any attributes of its own.

Because abort result error codes are Mobile Application package specific, this abstract class does not define any of the problem values or parameter syntaxes of the Error superclass.

5.2.5 Accept-Result

An instance of abstract OM class Accept-Result represents the base information passed as the Response argument to the Accept() function (see Accept) or returned from the Receive() function (see Receive) in the Result-Or-Argument result for an accept indication.

This OM class is an abstract class with several defined concrete subclasses: GSM-Accept-Result (see GSM-Accept-Result) and ANSI-Accept-Result.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 51.

This OM class contains the following class-specific OM attributes:

session

Used to return to the user a fully formed dialog session object. This object may be used for all furture interface calls pertaining to this new dialog.

When this object is received as a Result-Or-Argument result in a call to Receive() (see Receive), the Get-Assoc-Info() function can be used to retrieve additional details concerning the association. See Get-Assoc-Info.

5.2.6 Acse-Args

An instance of OM class Acse-Args identifies ACSE specific arguments that will be used during association establishment to a remote peer entity. These can be specified in the Session object if AAM is enabled, or in the Assoc-Argument or Assoc-Result object if AAM is disabled.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed below:

This OM class contains the following class-specific OM attributes:

The Acse-Args object collects together all the information that is ACSE specific for association establishment.

responder-Address

Indicates the address of the responding program named by responder-Title.

responder-Title

Indicates the name of the program which will be used to service management service requests. It may be a distinguished name (instance of OM class Form1) or a registered name (instance of OM class Form2) which is used in name/network address resolution phase to get the application process title, the application entity qualifier and the presentation address. It may also be the Entity-Name of the responding program.

application-Context

The application context name proposed by the user to be used on the mobile application association. When automatic dialog handling is enabled on the session, the application context will be selected by the Mobile Application Service provider consistent with the Mobile Application Service request or indication. Mobile Application Service packages define a set of application contexts that are applicable to the service package.

security-Context

The security context name proposed by the user to be used on the mobile application association. By default the security context is not present. MObile Application Service packages define a set of security contexts that are applicable to the service package.

5.2.7 Address

An instance of OM class Address represents the address of a particular mobile application entity. It is used to define the sepcific location to contact a particular mobile application entity.

An instance of this OM class has all of the attributes of its superclasses, Object, and additionally the OM attributes listed in Table 30.

This OM class contains the following class-specific OM attributes:

sccp-Address

The address is respresented using an octet string that contains the encoding of an SCCP address in either ITU-T or ANSI format in accordance with the format specified for the SCCP Called Party Address in ANSI T1.112/2000 Section 3.4 and ITU-T Recommendation Q.713 Section 3.4 (see String(Sccp-Address)) with the following considerations:

• The encoded address shall have both a signalling point code and a subsystem number in the address.
• The encoded address shall not have a global title in the address (the global title indicated shall be coded ‘0000’).
• The encoded address will distinguish between ITU-T format and ANSI format using the network indicator bit as described in ANSI T1.112/2000 Section 3.4.

5.2.8 Application-Context-List

An instance of OM class Application-Context-List represent a list of application context names.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 47.

This OM class contains the following class-specific OM attributes:

application-Context-Name

This attribute is one or more instances of an application context name consisting of an integer syntax or an object-identifier syntax. The integer syntax is only applicable to some Mobile Application packages (e.g. the GSM ANSI service package).

5.2.9 Assoc-Argument

An instance of OM class Assoc-Argument is the information supplied as an argument of an ACSE Associate operation to be performed. This object is passed to Assoc-req() or returned from Receive().

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed below:

This OM class contains the following class-specific OM attributes:

presentation-Layer-Args

Indicates any presentaiton layer arguments needed during association establishment. If none are supplied, the Mobile Application Service provider will supply defaults if required.

acse-Args

Indicates ACSE related arguments that will be used during association establishment. If none are supplied, the Mobile Application Service provider will supply defaults if required.

map-Assoc-Args

Indicates MAP related arguments that will be used during association establishment. If none are supplied, the Mobile Application Service provider will supply defaults if required.

session

Used to return an associated Session object. This attribute must be empty when Assoc_req() is called, and is supplied as a Result parameter by the Mobile Application Service provider upon return from that call. When the object is returned from Receive(), this attribute is a partially associated Session object. Partially associated session objects can be aborted by calling Abort_req() using the new partially associated session object. Partially associated session objects can become fully associated by calling Assoc_rsp(). To accept or refuse the new association, call Assoc_rsp() using the new partially associated session object that was returned by Receive() for the association indication.

5.2.10 Assoc-Result

An instance of OM class Assoc-Result is the information supplied as a response of an ACSE Associate operation to be performed. This object is passed to Assoc-rsp() or returned from Receive().

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 61.

This OM class contains the following class-specific OM attributes:

presentation-Layer-Args

Indicates any presentation layer arguments needed during association establishment. If none are supplied, the Mobile Application Service provider will supply defaults if required.

acse-Args

Indicates ACSE relasted arguments that will be used during association establishment. If none are supplied, the Mobile Application Service provider will supply defaults if required.

map-Assoc-Args

Indicates MAP related arguments that will be used during association establishment. If none are supplied, the Mobile Application Service provider will supply defaults if required.

session

Used to return to the user an associated session object. This object may be used for all future interface calls pertaining to this new association.

5.2.11 Close-Argument

An instance of OM class Close-Argument represents the base information that is supplied as the Argument argument to the Clsoe() function (see Close) or is returned by the Receive() function (see Receive) in the Result-Or-Argument result for a close indication.

This OM class is an abstract class with several defined concrete subclasses: GSM-Close-Argument (see GSM-Close-Argument) and ANSI-Close-Argument.

An instance of this OM class has the OM attributes of its superclasses, Object, it does not define any OM attribtutes of its own.

5.2.12 Context

An instance of OM class Context comprises per operation arguments that are accepted by most of the interface functions.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attribtutes listed below:

This OM class contains the following class-specific OM attributes:

Common Arguments

extensions

Service Controls

mode

application-Context

responder-Address

responder-Title

Local Controls

asynchronous

reply-Limit

time-Limit

5.2.13 Extension

An instance of OM class Extension represent an extension to ASN.1 syntax. This object is coded using the any syntax. The particular syntax of the extension is dependent upon the object within which an instance of this extension object is contained.

An instance of this OM class has the OM attributes of is superclasses, Object, and additionally the OM attributes listed in Table 45.

This OM class contains the following class-specific OM attributes:

extension

This attribute is a syntax that represents the ASN.1 encoding of the extension complete with tags.

5.2.14 Generic-Service-Argument

An instance of OM class Generic-Service-Argument represents a generic service request independent of a defined Mobile Application Services package. This object is used to support service requests that have not been defined in a Mobile Application Services package, or for a Mobile Application Services package that is not supported by the implementation workspace.

An instance of this OM class has the attributes of it is superclasses, Service-Request, and additionally the OM attributes listed in Table 55.

This OM class contains the following class-specific OM attributes:

confirmation

This attribute is a boolean value that specifies whether the operation is performed in the confirmed or unconfirmed mode. When performed in a confirmed mode, a response is expected. When performed in the unconfirmed mode, no response is expected. This attribute determines which TCAP operations class will be used for the underlying invoke operation.

operation

This attribute specifies the ROSE/TCAP operation code associated with the service request as either an integer or an object identifier. Whether an integer or object identifier is used depends upon the underlying ROSE/TCAP provider and may differ depending on the Mobile Application Package in use (e.g. GSM MAP or ANSI MAP).

arguments

This attribute specifies the parameters of the operation invocation as one or more instances of OM class Encoding. This encoding class will be encapsulated in a Parameter Sequence by the underlying ROSE/TCAP provider.

5.2.15 Generic-Service-Result

An instance of OM class Generic-Service-Result represents a generic service response independent of a defined Mobile Application Services package. This object is used to support service responses that have not been defined in a Mobile Application Services package, or for a Mobile Application Services package that is not supported by the implementation workspace.

An instance of this OM class has the attributes of its superclasses, Service-Result, and additionally the OM attributes listed in Table 56.

This OM class contains the following class-specific OM attributes:

operation

This attribute specifies the ROSE/TCAP operation code associated with the service request as either an integer or an object identifier. Whether an integer or object identifier is used depends upon the underlying ROSE/TCAP provider and may differ depending on the Mobile Application Package in use (e.g. GSM MAP or ANSI MAP).

response

This attribute specifies the parameters of the operation invocation as one or more instances of OM class Encoding. This encoding class will be encapsulated in a Parameter Sequence by the underlying ROSE/TCAP provider.

5.2.16 Map-Assoc-Args

An instance of OM class Map-Assoc-Args represents the MAP association arguments that are optionally supplied by the Session, Assoc-Argument or Assoc-Result objects and can be interrogated with the Get-Assoc-Info() function.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 60.

This OM class contains the following class-specific OM attributes:

application-Context-List

version-List

5.2.17 Notice-Result

An instance of OM class Notice-Result represents the base information that is returned in the Result-Or-Argument result by the Receive() function (see Receive) for a notice indication.

This OM class is an abstract class with several defined concrete subclasses: GSM-Notice-Result (see GSM-Notice-Result) and ANSI-Notice-Result.

An instance of this OM class has the OM attributes of its superclasses, Object. It does not define any OM attributes of its own.

5.2.18 Open-Argument

An instance of OM class Open-Argument represents the base information that is supplied as an argument to the Open() function (see Open) or is returned by the Receive() function (see Receive) for an open indication.

This OM class is an abstract class with several defined concrete subclasses: GSM-Open-Argument (see GSM-Open-Argument) and ANSI-Open-Argument.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 32.

This OM class contains the following class-specific OM attributes:

responder-Address

Specifies the responder address (the address of the remote mobile application entity) for a bound session object with AAM enabled, this address takes precedence over any responder-Address contained in the Context or Session objects. For an associated session object, the precedence rules are different and the Open-Argument object cannot be used to override the responder-Address contained in the Session object.

responder-Title

Specifies the responder title. This title takes precedence over any responder-Title contained in the Context or Session objects. When not specified by any object, the MAS provider will not include a responder title in the open request.

requesting-Address

The requesting-Address contained in the Open-Argument cannot be used to override the any requesting address contained in the Session object.

requesting-Title

Specifies the requesting title. This title takes precedence over any requesting-Title contained in the Context or Session objects. When not specified by any object, the MAS provider will not include a requesting title.

session

Use to return a partially formed dialog Session object. This attribute must be empty when Open() is called, and is supplied as a Result parameter by the Mobile Application Service provider upon return from that call. The partially formed dialog session can either be aborted with a call to Abort(), or can become a fully formed dialog session with a call to Accept(). To abort the partially formed dialog session, call Abort() using the new partially formed dialog session object. To accept or refuse the new dialog, call Accept() or Refuse() using the session object that received the association indication.

5.2.19 Operation-Argument

5.2.20 Operation-Error

5.2.21 Operation-Reject

5.2.22 Operation-Result

5.2.23 P-Abort-Result

An instance of OM abstract class P-Abort-Result represents the base information returned in the Result-Or-Argument result from the Receive() function (see Receive) for a provider abort indication.

This OM class is an abstract class with several defined concrete subclasses: GSM-P-Abort-Result (see GSM-P-Abort-Result) and ANSI-P-Abort-Result.

An instance of this OM class has the OM attributes of its superclasses, Object, Error; it does not define any OM attributes of its own.

See also Service Error.

5.2.24 Presentation-Context

An instance of OM class Presentation-Context lists the presentation contexts for association establishment.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed below:

This OM class contains the following class-specific OM attributes:

presentation-Id

The integer user identification of the presentation context.

presentation-Abstract

Identifies the abstract syntax. If no value is supplied, by default the abstract syntax name is provided by the Mobile Application package. The GSM MAP package provides a default abstract syntax name of map-DialogueAs, specified by 3GPP TS 29.002, and is supplied by the Mobile Application Service provider. This Object-Identifier is { itu-t(0) identified-organization(4) etsi(0) mobile-domain(0) gsm-Network(1) as-Id(1) map-DialoguePDU(1) version1(1) } and is provided in the C binding as ‘MAP_GSM_DIALOGUE_AS’.

5.2.25 Presentation-Layer-Args

An instance of OM class Presentation-Layer-Args identifies the presentation layer arguments that will be used during association establishment. These can be specified in the session object if AAM is enabled, or in the Assoc-Argument or Assoc-Result object if AAM is disabled.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed below:

This OM class contains the following class-specific OM attributes:

presentation-Context-List

The list of presentation contexts.

5.2.26 Refuse-Result

An instance of OM class Refuse-Result represents the base information that is supplied as the Response argument to the Refuse() function (see Refuse) or is returned by the Receive function (see Receive) in the Result-Or-Argument result for a refuse indication.

This OM class is an abstract class with several defined concrete subclasses: GSM-Refuse-Result (see GSM-Refuse-Result) and ANSI-Refuse-Result.

An instance of this OM class has the OM attributes of its superclasses, Object, it does not define any OM attributes of its own.

5.2.27 Release-Argument

5.2.28 Release-Result

5.2.29 Service-Argument

An instance of OM class Service-Argument represents the base information that is supplied as an argument to the Service-req() function (see Service-req) or is returned by the Receive() function (see Receive) for a service indication.

This OM class is an abstract class containing several defined subclasses: GSM-Service-Argument (see GSM-Service-Argument) and ANSI-Service-Argument.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionaly the OM attributes listed in Table 64.

This OM class contains the following class-specific OM attributes:

responder-Address

responder-Title

requesting-Title

5.2.30 Service-Error

An instance of abstract OM class Service-Error represents the base information that is supplied in response to a service operation, supplied as the Argument argument to the Service-rsp() function (see Service-rsp) or is returned as a Result-Or-Argument result by the Receive() function (see Receive) for a service confirmation.

This OM class is an abstract class containing several defined subclasses: GSM-Service-Error (see GSM-Service-Error) and ANSI-Service-Error.

An instance of this OM class has the OM attributes of its superclasses, Object, Error. As the problem values and parameter syntaxes are Mobile Application package specific, this OM class defines no attributes or error values of its own.

See Service Error.

5.2.31 Service-Reject

An instance of abstract OM class Service-Reject represents the base information that is supplied in response to a service operation, supplied as the Argument argument to the Service-rsp() function (see Service-rsp) or is returned as Result-Or-Argument result by the Receive() function (see Receive) for a service confirmation.

This OM class is an abstract class containing several defined subclasses: GSM-Service-Reject (see GSM-Service-Reject) and ANSI-Service-Reject.

An instance of this OM class has the OM attribute of its superclasses, Object, Error. As the problem values and parameter syntaxes are Mobile Application package specific, this OM class defines no attributes or error values of its own.

Note that when Automatic Association Management or Automatic Dialog Handling are enabled on a sesion for which a concrete subclass of the Service-Reject is used as a response, the Service-Reject object also represents the errors that would otherwise be reported using a concrete subclass of Abort-Argument, P-Abort-Result (were ADH to be diabled) or Refuse-Result or Abort-Result (were AAM to be disabled).

Therefore, when ADH is enabled on a session, the problem and parameter attributes of the Error superclass may also contain any of the error values defined for the corresponding Abort-Argument or P-Abort-Result subclasses. When AAM is enabled on a session, the problem and parameter attributes of the Error superclass may also contain any of the error values defined for the corresponding Refuse-Result or Abort-Result subclasses.

See Service Error.

5.2.32 Service-Result

An instance of OM class Service-Result represents the base information that is supplied as an argument to the Service-rsp() function (see Service-rsp) or is returned as a receive result by the Receive() function (see Receive) for a service confirmation.

This OM class is an abstract class containing several defined subclasses: GSM-Service-Result (see GSM-Service-Result) and ANSI-Service-Result.

An instance of this OM class has the OM attributes of its superclasses, Object. As the error codes are Mobile Application package specific, this OM class defines no attributes of its own.

5.2.33 Session

An instance of OM class Session identifies a particular communications link from the application program to the Mobile Application Service provider or to a remote mobile application entity depending upon the state of the session object. Session objects can be created with Automatic Association Management enabled or disabled. If AAM is enabled, then all of the ACSE connection management, needed to deliver a mobile application service operation, is done by the Mobile Application Service provider. If AAM is disabled, the ACSE connection management is done by the user before issuing or receiving Mobile Application Service operations.

The use of and rules for the session object are different depending on whether AAM is enabled or disabled. AAM is specified as part of Negotiate().³⁹

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 24.

For a description of the three type of Session objects: AAM Enabled Session, AAM Disabled Session and Connected Session, see Session Description.

The OM atributes of a Session are:

requestor-Address

Indicates the address of the requesting program named by requestor-Title. If both the requestor-Address and requestor-Title are not specified, the service provider will supply a default requestor-Address.

requestor-Title

Indicates the name of the requesting program, user of this session. It may be a distinguished name (instance of OM class Form1) or a registerd name (instance of OM class Form2) which is used in name/network address resolution phase to get the application process title, the application entity qualifier and the presentation address. It my also be the entity-name of the requesting program.

role

Indicates the roles acted by the resquestor. The role value is specified by OR-ing none, one, or more of the following values:

performer-role

(‘MAP_T_PERFORMER_ROLE’) Responder and performer of mobile application services operations. Unless this role is set or implied, no indications will be returned by calls to Receive and the Mobile Application Service provider does not need to provide indications to the bound session user.

invoker-role

(‘MAP_T_INVOKER_ROLE’) Requester and Invoker of mobile application services operations. If performer-role is set and invoker-role is clear, the Mobile Application Service provider does not need to honor operation or service requests from the bound session user.

When both role flags are clear, or this attribute is not present in the session, the Mobile Application Service provider may still honor operation and service requests.

file-Descriptor

Indicates the file descriptor associated with the session. The file descriptor may be used by implementors of the Wait() function. The file descriptor may be used in subsequent calls to vendor-specific system facilities to suspend the process (for example, System V poll(2s) or BSD select(2)). Its use for any other purpose is unspecified.

If the implementation does not define any suitable supsension facilities, or if the session is not started, the value is No-Valid-File-Descriptor (‘-1’ or ‘MAP_NO_VALID_FILE_DESCRIPTOR’).

presentation-Layer-Args

Indicates any presentation layer arguments needed during association establishment. If none are supplied, the Mobile Application Service provider will supply defaults if required.

acse-Args

Indicates the ACSE related arguments that will be used during association establishment. If none are supplied, the Mobile Application Service Provider will supply defaults if required.

map-Assoc-Args

Indicates the MAP association related arguments that will be used during association establishment. If not are supplied, the Mobile Application Service Provider will supply defaults if required.

5.2.34 Title

An instance of OM class Title represents the title of a paticular mobile application service entity. It contains various subclass types used to define the specific mobile application process or system name responsible for a mobile application service entity.

An instance of this OM class has all of the attributes of its superclasses, Object, and additionally the OM attributes listed in Table 31.

This OM class contains the following class-specific OM attributes:

sccp-Title

The title is respresented using an octet string that contains the encoding of an SCCP address in either ITU-T or ANSI format in accordance with the format specified for the SCCP Called Party Address in ANSI T1.112/2000 Section 3.4 and ITU-T Recommendation Q.713 Section 3.4 (see String(Sccp-Address)) with the following considerations:

• The encoded address may have either a signalling point code or a subsystem number, or both, in the address.
• The encoded address shall have a global title in the address (the global title indicated shall not be coded ‘0000’).
• The encoded address will distinguish between ITU-T format and ANSI format using the network indicator bit as described in ANSI T1.112/2000 Section 3.4.

5.3 GSM MAP Package

The GSM MAP package provides specialization of the argument and result objects of the Common MAP package to provide for the services under the GSM MAP as described in 3GPP TS 29.002 Section 7.6. This package is organized as a separate OM package that can be negotiated using the Negotiate() function.⁴⁰

The Object-Identifier associated with the GSM MAP package is:

{ iso(1) org(3) dod(6) internet(1) private(4) enterprises(1) openss7(29591)
  xom-packages(1) xmap(1) gsm(2) }

This Object-Identifier is represented by the constant GSM-Package (‘MAP_GSM_PKG’). This constant can be used to negotiate support for the package using the Negotiate() function.

GSM MAP package introduces some additional OM syntaxes that are derivations of the String(Octet) syntax. These additional OM syntaxes are used to represent digit strings and telephony numbers. See String(Address).

The following outlines the OM Class Hierarchy for the GSM MAP package:

• Object (defined in the XOM Specification: see reference XOM)
  • Abort-Argument (defined in MAP-Common-Package)
    • GSM-Abort-Argument
  • Abort-Result (defined in MAP-Common-Package)
    • GSM-Abort-Result
  • Accept-Result (defined in MAP-Common-Package)
    • GSM-Accept-Result
  • Close-Argument (defined in MAP-Common-Package)
    • GSM-Close-Argument
  • Context (defined in MAP-Common-Package)
    • GSM-Context
  • Extension-Container
  • Map-Assoc-Args (defined in MAP-Common-Package)
    • GSM-Map-Assoc-Args
  • Notice-Result (defined in MAP-Common-Package)
    • GSM-Notice-Result
  • Open-Argument (defined in MAP-Common-Package)
    • GSM-Open-Argument
  • P-Abort-Argument (defined in MAP-Common-Package)
    • GSM-P-Abort-Argument
  • PCS-Extensions
  • Private-Extension
  • Private-Extension-List
  • Refuse-Result (defined in MAP-Common-Package)
    • GSM-Refuse-Result
  • Release-Argument (defined in MAP-Common-Package)
    • GSM-Release-Argument
  • Release-Result (defined in MAP-Common-Package)
    • GSM-Release-Result
  • Service-Argument (defined in MAP-Common-Package)
    • GSM-Service-Argument
  • Service-Result (defined in MAP-Common-Package)
    • GSM-Service-Result
  • Specific-Information
  • User-Abort-Choice

5.3.1 String(Address)

This OM syntax is indicated in OM Attribute tables as String(Address).

In the C binding, the OM Syntax name for String(Address) is ‘MAP_S_ADDRESS_STRING’.

This syntax is used to represent a number for addressing purposes. It is composed of a sequence of one or more octets, consisting of:

• one octet for nature of address and numbering plan indicator;
• digits of an address encoded as String(TBCD).

The first octet includes a one bit extension indicator, 3-bit nature of address indicator, and 4-bit numbering plan indicator coded as follows:

bit ‘8’:

This bit is an unused extension bit (no extension, coded as zero (‘0’)).

bits ‘765’:

These bits contain the Nature of Address Indicator:

‘000’	unknown
‘001’	international number
‘010’	national significant number
‘011’	network specific number
‘100’	subscriber number
‘101’	reserved
‘110’	abbreviated number
‘111’	reserved for extension

bits ‘4321’:

These bits contain the Numbering Plan:

‘0000’	unknown
‘0001’	ISDN/Telephony Number Plan (ITU-T Rec. E.164)
‘0010’	spare
‘0011’	data numbering plan (ITU-T Rec. X.121)
‘0100’	telex numbering plan (ITU-T Rec. F.69)
‘0101’	spare
‘0110’	land mobile numbering plan (ITU-T Rec. E.212)
‘0111’	spare
‘1000’	national numbering plan
‘1001’	private numbering plan
‘1010’	reserved
‘1011’	reserved
‘1100’	reserved
‘1101’	reserved
‘1110’	reserved
‘1111’	reserved for extension

The following octets representing digits of an address encoded as String(TBCD).

5.3.2 String(Subaddress)

This OM syntax is indicated in OM Attribute tables as String(Subaddress).

In the C binding, the OM Syntax name for String(Subaddress) is ‘MAP_S_SUBADDRESS_STRING’.

This syntax is used to represent a number for addressing purposes. It is used to represent ISDN subaddresses. It is composed of:

• one octet of type of subaddress and odd/even indicator;
• twenty octets of subaddress information.

The first octet includes a one bit extension indicator, a 3-bit type of subaddress, and a one bit odd/even indicator, encoded as follows:

bit ‘8’

‘1’	(no extension)

bits ‘765’

‘000’	NSAP (X.213/ISO 8348 AD2)
‘010’	User Specified
—	all other values reserved

bit ‘4’

‘0’	even number of address signals
‘1’	odd number of address signals

bits ‘321’

‘000’

(unused)

The following octets represent the address signals or subaddress information.

The NSAP X.213/ISO8348 AD2 address shall be formatted as specified by octet 4 which contains the Authority and Format Identifier (AFI). The encoding is made according to the “preferred binary encoding” as defined in X.213/ISO 8348 AD2. For the definition of this type of subaddress, see ITU-T Recommendation I.334.

For User-specific subaddress, this field is encoded according to the user specification, subject to a maximum length of 20 octets. When interworking with X.25 networks, BCD coding should be applied.

5.3.3 GSM-Abort-Argument

An instance of OM class GSM-Abort-Argument represents the information that can be supplied as the Argument argument to the Abort() function (see Abort) or is returned by the Receive() function (see Receive) in the Result-Or-Argument result of a user abort indication.

An instance of this OM class has the OM attributes of its superclass, Object, Error, Abort-Argument (see Abort-Argument), and additionally the OM attributes listed in Table 5.

This OM class contains the following class-specific OM attributes:

problem

user-specific-reason(0)⁴¹ (‘MAP_E_PROCEDURE_ERROR’)

Processing of the procedure is terminated due to procedural reasons. The remote MAP Service User has aborted the operation due to a user-specific reason. Indicates that the user abort reason is user specific and no additional information is provided. There is no error parameter associated with this problem code.

resource-limitation-congestion(1) (‘MAP_E_RESOURCE_LIMITATION_CONGESTION’)

The requested user resource is unavailable due to congestion. The remote MAP Service User has aborted the operation due to a resource limitation (such as congestion). Indicates that the user abort reason is related to a resource limitation (e.g. congestion) and no additional information is provided. There is no error parameter associated with this problem code.

resource-unavailable(2) (‘MAP_E_RESOURCE_UNAVAILABLE’)

The requested user resource is unavailable for reasons other than congestion. The remote MAP Serice User has aborted the operation due to the unavailability of a resource (such as system memory). This is either of a short term or long term nature. Indicates that the user abort reason is due to the unavailability of a resource. The reason is further qualified as to the duration of the resource limitation as follows:

short-term-resource-limitation

(‘MAP_E_SHORT_TERM_RESOURCE_LIMITATION’ ‘0’)

long-term-resource-limitation

(‘MAP_E_LONG_TERM_RESOURCE_LIMITATION’ ‘1’)

This further qualification is contained in the error parameter as an Integer value.

application-procedure-cancellation(3) (‘MAP_E_APPLICATION_PROCEDURE_CANCELLATION’)

The procedure is cancelled for reasons detailed in the diagnostic information parameter. The remote MAP Service User has aborted the operation due to application procedure cancellation. The cause of the cancellation is provided. Indicates that the user abort reason is due to the cancellation of a procedure. The reason is futher qualified as to the source of the cancellation as follows:

handover-cancellation

(‘MAP_E_HANDOVER_CANCELLATION’ ‘0’)

radio-channel-release

(‘MAP_E_RADIO_CHANNEL_RELEASE’ ‘1’)

network-path-release

(‘MAP_E_NETWORK_PATH_RELEASE’ ‘2’)

call-release

(‘MAP_E_CALL_RELEASE’ ‘3’)

associated-procedure-failure

(‘MAP_E_ASSOCIATED_PROCEDURE_FAILURE’ ‘4’)

tandem-dialogue-release

(‘MAP_E_TANDEM_DIALOGUE_RELEASE’ ‘5’)

remote-operations-failure

(‘MAP_E_REMOTE_OPERATIONS_FAILURE’ ‘6’)

This further qualification is contained in the error parameter as an Integer value.

parameter

This attribute is an instance of OM class Specific-Information.

specific-Information

This attribute is zero or more instances of OM class Specific-Information. See Specific-Information.

5.3.4 GSM-Abort-Result

5.3.5 GSM-Accept-Result

An instance of OM class GSM-Accept-Result represents the information that is supplied as the Response argument to the Accept() function (see Accept) or is returned in the Result-Or-Argument result by the Receive() function (see Receive) for an accept confirmation.

An instance of this OM class has the OM attributes of its superclass, Accept-Result (see Accept-Result), and additionally the OM attributes listed in Table 2.

This OM class contains the following class-specific OM attributes:

specific-Information

This attribute provides user-specific information that is passed transparently between peer mobile application service users as part of dialog establishment. This attribute is an instance of OM class Specific-Information. See Specific-Information.

5.3.6 GSM-Close-Argument

An instance of OM class GSM-Close-Argument represents the information that is supplied as the Argument argument to the Close() function (see Close) or is returned in the Result-Or-Argument result by the Receive() function (see Receive) for a close indication.

An instance of this OM class has the OM attributes of its superclass, Close-Argument (see Close-Argument), and additionally the OM attributes listed in Table 4.

This OM class contains the following class-specific OM attributes:

release-Method

Specifies the release method for closing the dialogue. When supplied as an argument to the Close() function, this value can be one of the following:

normal-release

(‘MAP_T_NORMAL_RELEASE’) The release is normal (and will result in issuing a MAP-CLOSE dialogue and a TCAP END message).

prearranged-end

(‘MAP_T_PREARRANGED_END’) The release is prearranged (and will not result in either issuing a MAP-CLOSE dialogue nor a TCAP END message).

Note:

When indicated by the Receive() function, this attribute will always contain normal-release.

specific-Information

This attribute provides user-specific information that is passed transparently to the remote peer moble application service user. This attribute is an instance of OM class Specific-Information. See Specific-Information.

5.3.7 GSM-Context

An instance of OM class GSM-Context comprises per operation arguments, including GSM specific arguments, that are accepted by most of the interface functions.

An instance of the OM class has the OM attributes of it superclasses, Context, and additionally the OM attributes listed in Table 65.

This OM class contains the following class-specific OM attributes:

application-Context

Specifies the application context for the calle to Open(), Refuse() (ADH disabled) or Service-req(), Service-rsp() (ADH enabled). When not specified, the MAS provider will select a default value as required.

destination-Reference

Specifies the destination reference for the call to Open() (ADH disabled) or Service-req() (ADH enabled). When not specified, the MAS provider will select a default value as required.

originating-Reference

Specifies the originating reference for the call to Open() (ADH disabled) or Service-req() (ADH enabled). When not specified, the MAS provider will select a default value as required.

specific-Information

Specifies the specific information as an instance of the OM class Specific-Information (see Specific-Information) to be passed with any dialog handling or service request or response.

5.3.8 GSM-Map-Assoc-Args

An instance of OM class GSM-Map-Assoc-Args represents the additional GSM specific MAP association arguments that are optionally supplied by the Session, Assoc-Argument or Assoc-Result objects and can be interrogated with the Get-Assoc-Info() function.

An instance of this OM class has the OM attributes of its superclasses, Map-Assoc-Args (see Map-Assoc-Args), and additionally the OM attributes listed in Table 62.

This OM class contains the following class-specific OM attributes:

destination-Reference

This attribute is a destination reference represented as an address string. The rules for supplying destination references is given in 3GPP TS 29.002. This attribute has syntax String(Address). See String(Address).

originating-Reference

This attribute is a originating reference represented as an address string. The rules for supplying originating references is given in 3GPP TS 29.002. This attribute has syntax String(Address). See String(Address).

specific-Information

This attribute is zero or more instances of OM class Specific-Information. See Specific-Information.

5.3.9 GSM-Notice-Result

An instance of OM class GSM-Notice-Result respresents the information that is returned in a Result-Or-Argument result by the Receive() function (see Receive) for a notice indication.

An instance of this OM class has the OM attributes of its superclasses, Notice-Result (see Notice-Result), and additionally the OM attributes listed in Table 7.

This OM class contains the following class-specific OM attributes:

Problem-Diagnostic

abnormal-event-detected-by-peer

(‘MAP_T_ABNORMAL_EVENT_DETECTED_BY_PEER’)

response-rejected-by-the-peer

(‘MAP_T_RESPONSE_REJECTED_BY_THE_PEER’)

abnormal-event-received-from-the-peer

(‘MAP_T_ABNORMAL_EVENT_RECEIVED_FROM_THE_PEER’)

message-cannot-be-delivered-to-the-peer

(‘MAP_T_MESSAGE_CANNOT_BE_DELIVERED_TO_THE_PEER’)

The following values of the problem code of the TC-R-REJECT and TC-U-REJECT primitive are mapped to the values of the diagnostic parameter of the MAP-NOTICE indication primitive as follows:

TC Problem Code	MAP Diagnostic
general-problem(0)
unrecognized-component(0)	abormal-event-detected-by-the-peer
mistyped-component(1)	abormal-event-detected-by-the-peer
badly-structured-component(2)	abormal-event-detected-by-the-peer
invoke-problem(1)
duplicate-invoke-id(0)
unrecognized-operation(1)
mistyped-parameter(2)
resource-limitiation(3)
initiating-release(4)
unrecognized-linked-id(5)	abormal-event-detected-by-the-peer
linked-response-unexpected(6)	response-rejected-by-the-peer
unexpected-linked-operation(7)	response-rejected-by-the-peer
return-result-problem(2)
unrecognized-invoke-id(0)	response-rejected-by-the-peer
return-result-unexpected(1)	response-rejected-by-the-peer
mistyped-parameter(2)	response-rejected-by-the-peer
return-error-problem(3)
unrecognized-invoke-id(0)	response-rejected-by-the-peer
return-error-unexpected(1)	response-rejected-by-the-peer
unrecognized-error(2)	response-rejected-by-the-peer
unexpected-error(3)	response-rejected-by-the-peer
mistyped-parameter(4)	response-rejected-by-the-peer

The following values of the problem code parameter of the TC-L-REJECT primitive are mapped to values of the diagnostic parameter of the MAP-NOTICE indication primitive as follows:

TC Problem Code	MAP Diagnostic
general-problem(0)	abormal-event-received-from-the-peer
invoke-problem(1)
unrecognized-linked-id(5)	abormal-event-received-from-the-peer
return-result-problem(2)
unrecognized-invoke-id(0)	abnormal-event-received-from-the-peer
return-error-problem(3)
unrecognized-invoke-id(0)	abnormal-event-received-from-the-peer

5.3.10 GSM-Open-Argument

An instance of OM class GSM-Open-Argument represents the information that is supplied as an argument to the Open() function (see Open) or is returned by the Receive() function (see Receive) for an open indication.

An instance of this OM class has the OM attributes of its superclasses, Open-Argument (see Open-Argument), and additionally the OM attributes listed in Table 1.

This OM class contains the following class-specific OM attributes:

application-Context

Specifies the application context for the dialog. When not specified, the MAS will provide a default application context when required.

destination-Reference

This attribute is a destination reference represented as an address string. The rules for supplying destination references is given in 3GPP TS 29.002. This attribute has syntax String(Address). See String(Address).

originating-Reference

This attribute is a originating reference represented as an address string. The rules for supplying originating references is given in 3GPP TS 29.002. This attribute has syntax String(Address). See String(Address).

specific-Information

This attribute is an instance of OM class Specific-Information. See Specific-Information.

5.3.11 GSM-P-Abort-Result

An instance of OM class GSM-P-Abort-Result represents the information that is returned in the Result-Or-Argument result by the Receive() function (see Receive) for a provider abort indication.

An instance of this OM class has the OM attributes of its superclasses, P-Abort-Result (see P-Abort-Result), and additionally the OM attributes listed in Table 6.

This OM class contains the following class-specific OM attributes:

This OM class corresponds to the MAP-P-ABORT indication primitive of 3GPP TS 29.002 which contains Provider reason and Source parameters. This indication can result from the receipt of the local MAS provider of a map-providerAbort dialogue PDU or as a result of the receipt of a TC-U-ABORT or TC-P-ABORT indication primitive from the underlying TC provider. A TC-P-ABORT can either be because of an error detected in the dialogue user, or due to receipt of a TR-P-ABORT indication primitive.

provider-Reason

provider-malfunction

(‘MAP_E_PROVIDER_MALFUNCTION’) When the source is MAP, this represents a malfunction at the MAP level at the peer entity. When the source is TC, this represents the TC-P-ABORT reasons: unrecognised-message-type, badly-formatted-transaction-portion, incorrect-transaction-portion or abnormal-dialogue. When the source is NSP, this represents a malfunction at the network service level at the peer entity.

supporting-dialogue-transaction-released

(‘MAP_E_SUPPORTING_DIALOGUE_TRANSACTION_RELEASED’) When the source is TC, this represents the TC-P-ABORT reason unrecognised-transaction-id.

resource-limitation

(‘MAP_E_RESOURCE_LIMITATION’) When the source is MAP, this represents congestion toward the MAP peer service-user. When the source is TC, this represents resource-limitation received in a TC-P-ABORT.

maintenance-activity

(‘MAP_E_MAINTENANCE_ACTIVITY’) When the source is MAP, this represents maintenance activity at the MAP peer service-user. When the source is NSP, this represents maintenance at the network peer service level.

version-incompatibility

(‘MAP_E_VERSION_INCOMPATIBILITY’) When the source is TC, this represents a TC-P-ABORT indicating no-common-dialogue-portion or incorrect-transaction-portion received in the dialogue initated state.

abnormal-map-dialogue

(‘MAP_E_ABNORMAL_MAP_DIALOGUE’) When the source is MAP, this represents a MAP dialogue that is not in accordance with the specified application context.

source

map-problem

(‘MAP_E_MAP_PROBLEM’)

tc-problem

(‘MAP_E_TC_PROBLEM’)

network-service-problem

(‘MAP_E_NETWORK_SERVICE_PROBLEM’)

p-Abort-Reason

This attribute reflects the MAP provider abort reason (this is the information passed by the remote MAP provider in the MAP-P-ABORT dialogue PDU in the AABT APDU) and has one of the following values:

‘0’ abnormal-dialogue(0)

(‘MAP_E_ABNORMAL_DIALOGUE’)

‘1’ invalid-pdu(1)

(‘MAP_E_INVALID_PDU’)

p-Abort-Cause

This attribute reflects the TC provider abort cause (this is the information passed by the remote TCAP provider in the TCAP P-ABORT PDU) and has one of the following values:

‘0’ unrecognized-message-type(0)

(‘MAP_E_UNRECOGNIZED_MESSAGE_TYPE’)

‘1’ unrecognized-transaction-id(1)

(‘MAP_E_UNRECOGNIZED_TRANSACTION_ID’)

‘2’ badly-formatted-transaction-portion(2)

(‘MAP_E_BADLY_FORMATTED_TRANSACTION_PORTION’)

‘3’ incorrect-transaction-portion(3)

(‘MAP_E_INCORRECT_TRANSACTION_PORTION’)

‘4’ resource-limitation(4)

(‘MAP_E_RESOURCE_LIMITATION’)

The component sublayer will decide to abort a dialogue and discard any components received if an incorrect dialogue portion (e.g. syntactically incorrect or inopportune) is received or if no common version of the dialogue portion control APDUs can be agreed to. It informs its TC-user via a TC-P-ABORT indication primitive with “P-Abort” in the primtiive set to respectively “abnormal dialogue” or “no common dialogue portion”.

‘5’ abnormal-dialogue(5)

(‘MAP_E_ABNORMAL_DIALOGUE’) This is a local value and the numeric value is arbitrarily assigned.

‘6’ no-common-dialogue-portion(6)

(‘MAP_E_NO_COMMON_DIALOGUE_PORTION’) This is a local value and the numeric value is arbitrarily assigned.

‘1281’ unrecognized-package-type

‘1282’ incorrect-trans-portion

‘1283’ badly-structured-trans-portion

‘1284’ unassigned-responding-trans-id

‘1285’ permission-to-release-problem

‘1286’ resource-unavailable

‘1’ unrecognized-package-type

‘2’ incorrect-transaction-portion

‘3’ badly-structured-transaction-portion

‘4’ unassigned-responding-transaction-id

‘5’ permission-to-release-problem

‘6’ resource-unavailable

‘7’ unrecognized-dialogue-portion-id

‘8’ badly-structured-dialogue-portion

‘9’ missing-dialogue-portion

‘10’ inconsistent-dialogue-portion

report-Cause

Specifies the SCCP return cause resulting in local provider abort. It has one of the following values:

‘00000000’ no-translations-for-address-of-such-nature(0)

‘00000001’ no-translation-for-this-specific-address(1)

‘00000010’ subsystem-congestion(2)

‘00000011’ subsystem-failure(3)

‘00000100’ unequipped-user(4)

‘00000101’ mtp-failuire(5)

‘00000110’ network-congestion(6)

‘00000111’ sccp-unqualified(7)

‘00001000’ error-in-message-transport(8)

‘00001001’ error-in-local-processing(9)

‘00001010’ destination-cannot-perform-reassembly(10)

‘00001011’ sccp-failure(11)

‘00001100’ hop-counter-violation(12)

‘00001101’ segmentation-not-supported(13)

‘00001110’ segmentation-failure(14)

In addition, if the local SCCP provider is an ANSI SCCP provider,⁴² the SCCP return cause can also contain one of the following values:

‘11110111’ message-change-failure(247)

‘11111000’ invalid-ins-routing-request(248)

‘11111001’ invalid-isni-routing-request(249)

‘11111010’ unauthorized-message(250)

‘11111011’ message-incompatibility(251)

‘11111100’ cannot-perform-isni-constrained-routing(252)

‘11111101’ redundant-isni-constrained-routing-information(253)

‘11111110’ unable-to-perform-isni-identification(254)

5.3.12 GSM-Refuse-Result

An instance of OM class GSM-Refuse-Result represents the information that is supplied as an argument to the Refuse() function (see Refuse) or is returned by the Receive() function (see Receive).

An instance of this OM class has the OM attributes of its superclasses, Refuse-Result, and additionally the OM attributes listed in Table 3.

This OM class contains the following class-specific OM attributes:

application-Context

Specifies the highest version alternate application context supported by the refusing mobile application entity when refusal is due to application-context-not-supported.

refuse-Reason

This attribute provides the reason for refusal. Its value can be one of the following:

no-reason-given

(‘MAP_T_NO_REASON_GIVEN’ ‘0’) This reason is transmitted and is provided directly in a received ‘map-refuse’ dialogue PDU.

invalid-destination-reference

(‘MAP_T_INVALID_DESTINATION_REFERENCE’ ‘1’) This reason is transmitted and is provided directly in a received ‘map-refuse’ dialogue PDU.

invalid-originating-reference

(‘MAP_T_INVALID_ORIGINATING_REFERENCE’ ‘2’) This reason is transmitted and is provided directly in a received ‘map-refuse’ dialogue PDU.

encapsulated-AC-not-supported

(‘MAP_T_ENCAPSULATED_AC_NOT_SUPPORTED’ ‘3’) This reason is transmitted and is provided directly in a received ‘map-refuse’ dialogue PDU. This reason is not used in dialogues with an application context different from secureTransportHandling.

transport-protection-not-adequate

(‘MAP_T_TRANSPORT_PROTECTION_NOT_ADEQUATE’ ‘4’) This reason is transmitted and is provided directly in a received ‘map-refuse’ dialogue PDU. This reason is not used in dialogues with an application context different from secureTransportHandling.

remote-node-not-reachable

(‘MAP_T_REMOTE_NODE_NOT_REACHABLE’) This reason is not transmitted and may not be specified as a refuse-Reason when calling Refuse().

application-context-not-supported

This refuse reason is given if a TC-U-ABORT is received by the local Mobile Application Service provider while an open request is pending and the Abort-Reason is “application context not supported”.

potential-version-incompatibility

(‘MAP_T_POTENTIAL_VERSION_INCOMPATIBILITY’) This refuse reason is given if a TC-P-ABORT is received by the local Mobile Application Service provider while an open request is pending and the P-Abort cause is “incorrect-transaction-portion” or “no-common-dialogue-portion”.

secured-transport-not-possible

(‘MAP_T_SECURED_TRANSPORT_NOT_POSSIBLE’) This reason is not transmitted.

specific-Information

This attribute provides user-specific information that is passed transparently between peer mobile application service users as part of dialog establishment. This attribute is an instance of OM class Specific-Information. See Specific-Information.

5.3.13 GSM-Release-Argument

5.3.14 GSM-Release-Result

5.3.15 GSM-Service-Argument

An instance of OM class GSM-Service-Argument represents the information that is supplied as an argument to the Service-req() function (see Service-req) or is returned by the Receive() function (see Receive).

An instance of this OM class has the OM attributes of its superclasses, Service-Argument, and additionally the OM attributes listed in Table 63.

This OM class contains the following class-specific OM attributes:

application-Context

destination-Reference

originating-Reference

specific-Information

This attribute provides user-specific information that is passed transparently between peer mobile application service users as part of dialog establishment. This attribute is an instance of OM class Specific-Information.

5.3.16 GSM-Service-Error

An instance of concrete OM class GSM-Service-Error represents error information that is supplied as a response to a service operation, supplied as the Argument argument to the Service-rsp() function (see Service-rsp) or is returned as a Result-Or-Argument result by the Receive() function (see Receive) for a GSM service confirmation.

An instance of this OM class has the OM attributes of it superclasses, Object, Error, Service-Error. It defines no attributes of its own.

problem

The superclass problem attribtue represents the GSM service user-Error. Values for the problem superclass attribute are defined as follows:

• Reject Errors

  Reject GSM-Service-Error problem values and parameter syntaxes are defined in this GSM MAP package and are described in Reject Errors.

• Generic Errors

  Generic GSM-Service-Error problem values and parameter syntaxes are defined in this GSM MAP package and are described in Generic Errors.

• Identification and Numbering Errors

  Identification and Numbering GSM-Service-Error problem values and parameter syntaxes are defined in a future GSM MAP services package and are described in Identification and Numbering Errors.

• Subscription Errors

  Subscription GSM-Service-Error problem values and parameter syntaxes are defined in a future GSM MAP services package and are described in Subscription Errors.

• Handover Errors

  Handover GSM-Service-Error problem values and parameter syntaxes are defined in a future GSM MAP services package and are described in Handover Errors.

• Operation and Maintenance Errors

  Operation and Maintenance GSM-Service-Error problem values and parameter syntaxes are defined in a future GSM MAP services package and are described in Operation and Maintenance Errors.

• Call Handling Errors

  Call Handling GSM-Service-Error problem values and parameter syntaxes are defined in a future GSM MAP services package and are described in Call Handling Errors.

• Any Time Interrogation Errors

  Any Time Interrogation GSM-Service-Error problem values and parameter syntaxes are defined in a future GSM MAP services package and are described in Any Time Interrogation Errors.

• Any Time Information Handling Errors

  Any Time Information Handling GSM-Service-Error problem values and parameter syntaxes are defined in a future GSM MAP services package and are described in Any Time Information Handling Errors.

• Supplementary Service Errors

  Supplementary Service GSM-Service-Error problem values and parameter syntaxes are defined in a future GSM MAP services package and are described in Supplementary Service Errors.

• Short Message Service Errors

  Short Message Service GSM-Service-Error problem values and parameter syntaxes are defined in the GSM MAP Short Message Service services package and are described in Short Message Service Errors.

• Group Call Errors

  Group Call GSM-Service-Error problem values and parameter syntaxes are defined in a future GSM MAP services package and are described in Group Call Errors.

• Location Service Errors

  Location Service GSM-Service-Error problem values and parameter syntaxes are defined in a future GSM MAP services package and are described in Location Service Errors.

• Mobility Management Errors

  Mobility Management GSM-Service-Error problem values and parameter syntaxes are defined in a future GSM MAP services package and are described in Mobility Management Errors.

• Secure Transport Errors

  Secure Transport GSM-Service-Error problem values and parameter syntaxes are defined in a future GSM MAP services package and are described in Secure Transport Errors.

parameter

The superclasss parameter attribute, which may or may not be present, indicates the additional information available with the service user error. This information is contained in as an Object(Encoding) or is defined by a Mobile Application Services package. See GSM MAP Errors.

5.3.17 GSM-Service-Reject

An instance of concrete OM class GSM-Service-Reject represents error information that is supplied as a response to a service operation, supplied as the Argument argument to the Service-rsp() function (see Service-rsp) or is returned as a Result-Or-Argument result by the Receive() function (see Receive) for a GSM service confirmation.

An instance of this OM class has the OM attributes of it superclasses, Object, Error, Service-Reject. It defines no attributes of its own.

problem

Values for the problem superclass attribute (see Error) represent provider errors and values are defined as follows:

duplicated-invoke-id

(‘MAP_E_DUPLICATED_INVOKE_ID’)

not-supported-service

(‘MAP_E_NOT_SUPPORTED_SERVICE’)

mistyped-parameter

(‘MAP_E_MISTYPED_PARAMETER’)

resource-limitation

(‘MAP_E_RESOURCE_LIMITATION’)

initiating-release

(‘MAP_E_INITIATING_RELEASE’) That is, the peer has already initiated release of the dialogue and the service has to be released.

unexpected-response-from-the-peer

(‘MAP_E_UNEXPECTED_RESPONSE_FROM_THE_PEER’)

service-completion-failure

(‘MAP_E_SERVICE_COMPLETION_FAILURE’)

no-response-from-the-peer

(‘MAP_E_NO_RESPONSE_FROM_THE_PEER’)

invalid-response-receceived

(‘MAP_E_INVALID_RESPONSE_RECEIVED’)

parameter

The superclasss parameter attribute, which may or may not be present, indicates the additional information available with the service provider error. This information is contained in as an Object(Encoding) or is defined by a Mobile Application Services package.

5.3.18 GSM-Service-Result

An intance of OM class GSM-Service-Result represents the information that is supplied as the Response argument to the Service-rsp() function (see Service-rsp) or is returned in the Result-Or-Argument result by the Receive() function (see Receive) for a service confirmation.

An instance of this OM class has the OM attributes of its superclasses, Service-Result, GSM-Close-Argument and GSM-Abort-Argument, and additionally the OM attributes listed in Table 59.

This OM class contains the following class-specific OM attributes:

specific-Information

This attribute provides user-specific information that is passed transparently between peer mobile application service users as part of dialog establishment. This attribute is an instance of OM class Specific-Information.

5.3.19 GSM Data Types

5.3.19.1 Access-Network-Signal-Info

An instance of OM class Access-Network-Signal-Info represents access network signalling information contained in an an-APDU.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionalyt the OM attributes listed in Table 415.

This OM class contains the following class-specific OM attributes:

access-Network-Protocol-Id

An enumeration containing one of the following values:

ts3g-48006

(‘MAP_T_TS3G_48006’ ‘1’)

ts3g-25413

(‘MAP_T_TS3G_25413’ ‘2’)

If the sequence contains this parameter with any other value than the ones listed, the receiver shall ignore the entire AccessNetworkSignalInfo sequence.

signal-Info

LongSignalInfo :;= OCTET STRING (SIZE(1..2560)) The value 2560 represents the maximum number of octets that is available to carry a signle instance of the LongSignalInfo data type using White Book SCCP with the maximum number of segments. It takes into account the octets used by the lower layers of the protocol, and other information elements that may be included in the same component.

extension-Container

This optional attribute is an instance of OM class Extension-Container. See Extension-Container.

extension

This optional attribute is an instance of OM class Extension. See Extension.

5.3.19.2 Basic-Service-Code

An instance of the OM class Basic-Service-Code provides the specification of a basic mobile service code as a single byte octet string. An instance of this class has all of the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 102.

The attributes of the OM class represent a choice and exactly one of the attributes must be present in an instance of this OM class.

This OM class contains the following class-specific OM attributes:

bearer-Service

BearerServiceCode ::= OCTET STRING (SIZE (1))

teleservice

TeleserviceCode ::= OCTET STRING (SIZE (1))

5.3.19.3 Cell-Global-Id-Or-Service-Area-Id-Or-LAI

An instance of OM class Cell-Global-Id-Or-Service-Area-Id-Or-LAI represents a global cell id, a service area id, or a local area id.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 422.

This OM class represents a choice and exactly one instance of one attribute shall be present in an instance of this OM class.

This OM class contains the following class-specific OM attributes:

cell-Global-Id-Or-Service-Area-Id-Fixed-Length

CellGlobalIdOrServiceAreaIdFixedLength ::= OCTET STRING (SIZE (7)) Refers to Cell Global Identification or Service Area Identification defined in 3GPP TS 23.003. The internal structure is defined as follows: octet 1, bits 4321, mobile country code 1st digit; bits 8765, mobile country code 2nd digit; octet 2, bits 4321, mobile country code 3rd digit; bits 8765, mobile network code 2rd digit or filler (1111) for 2 digit MNCs; octet 3, bits 4321, mobile network code 1st digit; bits 8765, mobile network code 2nd digit; octet 4 and 5, Location Area Code according to 3GPP TS 24.008; octet 6 and 7, Cell Identity (CI) value or Service Area Code (SAC) value according to 3GPP TS 23.003.

lai-Fixed-Length

LAIFixedLength ::= OCTET STRING (SIZE (5)) Refers to Location Area Identification in 3GPP TS 23.003. The internal structure is defined as follows: octet 1, bits 4321, mobile country code 1st digit; bits 8765, mobile country code 2nd digit; octet 2, bits 4321, mobile country code 3rd digit; bits 8765, mobile network code 3rd digit or filler (1111) for 2 digit MNCs; octet 3, bits 4321, mobile network code 1st digit; bits 8765, mobile network code 2nd digit; octets 4 and 5, Location Area Code according to 3GPP TS 24.008.

5.3.19.4 EMLPP-Info

An instance of OM class EMLPP-Info represents the priority of an EMLPP call.

An instances of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 418.

This OM class contains the following class-specific OM attributes:

maximum-Entitled-Priority

EMLPP-Priority ::= INTEGER(0..15). The mapping from the values, A, B, 0, 1, 2, 3, 4 to the integer value is specified as follows where A is the highest and 4 is the lowest priority level. The integer values 7-15 are speare and shall be mapped to value 4.

default-Priority

EMLPP-Priority ::= INTEGER(0..15). The mapping from the values, A, B, 0, 1, 2, 3, 4 to the integer value is specified as follows where A is the highest and 4 is the lowest priority level. The integer values 7-15 are speare and shall be mapped to value 4.

extension-Container

This optional attribute is an instance of OM class Extension-Container. See Extension-Container.

extension

This optional attribute is an instance of OM class Extension. See Extension.

5.3.19.5 Ext-Basic-Service-Code

An instance of the OM class Ext-Basic-Service-Code provides the specification of an extensible basic mobile service code. An instance of this class has all of the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 412.

The attributes of the OM class represent a choice and exactly one of the attributes must be present in an instance of this OM class.

This OM class contains the following class-specific OM attributes:

ext-Bearer-Service

Ext-BearerServiceCode ::= OCTET STRING (SIZE(1..5)) This type is used to represent the code identifying a single bearer service, a group of bearer services, or all bearer services. The services are defined in 3GPP TS 22.002. The internal structure is defined as follows: octet 1, plmn-specific bearer services, bits 87654321, defined by the HPLMN operator; rest of bearer services, bit 8, 0 (ununsed); bits 7654321, group (bits 7654), and rate, if applicable (bits 321); octets 2-5: reserved for future use. If received the Ext-BearerServiceCode shall be treated according to the exception handling defined for the operation that uses this type. Ext-BearerServiceCode includes all values defined for BearerServiceCode.

ext-Teleservice

Ext-TeleserviceCode ::= OCTET STRING (SIZE(1..5)) This type is used to represent the code identifying a single teleservice, group of teleservices, or all teleservices. The services are defined in GSM TS 22.003. The internal structure is defined as follows: octet 1, bits 87654321, group (bits 8765) and specific service (bits 4321); octets 2-5, reserved for future use. If received, Ext-TeleserviceCode shall be treated according to the exception handling defined for the operation that uses this type. Ext-TeleserviceCode includes all values defined for TeleserviceCode.

5.3.19.6 Extension-Container

An instance of OM class Extension-Container represents the corresonding ExtensionContainer of the GSM MAP. This object is used to contain extension parameters that are used by a number of GSM MAP mobile application services.

An instance of this OM class has the OM attributes of its superclass, Object, and additionally the OM attributes listed in Table 41.

This OM class contains the following class-specific OM attributes:

private-Extension-List

This attribute is an optional list of private extensions.

pcs-Extensions

This attribute is an optional sequence of PCS extensions.

5.3.19.7 External-Signal-Info

An instance of OM class External-Signal-Info represents external signal information.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 423.

This OM class contains the following class-specific OM attributes:

protocol-Id

An enumeration containing one of the following values:

gsm-0408

(‘MAP_T_GSM_0408’ ‘1’)

gsm-0806

(‘MAP_T_GSM_0806’ ‘2’)

gsm-bssmap

(‘MAP_T_GSM_BSSMAP’ ‘3’)

ets-300102-1

(‘MAP_T_ETS_300102_1’ ‘4’)

signal-Info

SignalInfo ::= OCTET STRING (SIZE (1..200)) The value 200 represents the theoretical maximum number of octets that is available to carry a single instance of the SignalInfo data type, without requiring segmentation to cope with the network layer service. However, the actual maximum size available for an instance of the data type may be lower, especially when other information elements have to be included in the same component. Information about the internal structure is given in 3GPP TS 29.002 section 7.6.9.

extension-Container

This optional attribute is an instance of OM class Extension-Container. See Extension-Container. This attribute must not be used in version 2 application contexts.

extension

This optional attribute is an instance of OM class Extension. See Extension.

5.3.19.8 Ext-External-Signal-Info

An instance of OM class Ext-External-Signal-Info represents extended external signal information.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 424.

This OM class contains the following class-specific OM attributes:

ext-Protocol-Id

An enumeration containing one of the following values:

ets-300356

(‘MAP_T_ETS_300356’ ‘1’)

For sequences containing this parameter with any other value than the ones listed, the receiver shall ignore the entire Ext-ExternalSignalInfo sequence.

signal-Info

SignalInfo ::= OCTET STRING (SIZE (1..200)) The value 200 represents the theoretical maximum number of octets that is available to carry a single instance of the SignalInfo data type, without requiring segmentation to cope with the network layer service. However, the actual maximum size available for an instance of the data type may be lower, especially when other information elements have to be included in the same component. Information about the internal structure is given in 3GPP TS 29.002 section 7.6.9.10.

extension-Container

This optional attribute is an instance of OM class Extension-Container. See Extension-Container.

extension

This optional attribute is an instance of OM class Extension. See Extension.

5.3.19.9 HLR-List

An instance of HLR-List represents a list of HLR identities.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 421.

This OM class contains the following class-specific OM attributes:

hlr-Id

One to fifty (maxNumOfHLR-Id) instances of an hlr-Id attributes which is coded as an IMSI, with the leading digits of IMSI, i.e. (MCC, MNC, leading digits of MSIN) forming HLR Id defined in 3GPP TS 23.003.

5.3.19.10 Identity

An instance of OM class Identity represents the corresponding GSM MAP information object.

An instance of this OM class has the OM attributes of it superclasses, Object, and additionally the OM attributes listed in Table 413.

This OM class represents a choice and exactly one instance of one attribute shall exist in an instance of this OM class.

This OM class contains the following class-specific OM attributes:

imsi

This attribute represents the International Mobile Subscriber Identity defined in 3GPP TS 23.003. The syntax of this attribute is an octet string containing a TBCD string (see String(TBCD)) between 3 and 8 octets (5 and 16 digits) in length, inclusive. Digits of MCC, MNC and MSIN are concatenated in the listed order.

ismi-With-LMSI

This choice attribute is an instance of OM class IMSI-With-LMSI. See IMSI-With-LMSI.

5.3.19.11 IMSI-With-LMSI

An instance of OM class IMSI-With-LMSI represents the corresponding GSM MAP information object.

An instance of this OM class has the OM attributes of it superclasses, Object, and additionally the OM attributes listed in Table 414.

This OM class contains the following class-specific OM attributes:

imsi

This attribute represents the International Mobile Subscriber Identity defined in 3GPP TS 23.003. The syntax of this attribute is an octet string containing a TBCD string (see String(TBCD)) between 3 and 8 octets (5 and 16 digits) in length, inclusive. Digits of MCC, MNC and MSIN are concatenated in the listed order.

lmsi

This attribute provides the local identity allocated by the VLR to a given subscriber for internal management of data in the VLR. The LMSI shall not be sent to an SGSN. This attribute is encoded as a 4 octet string. A special value of ‘00000000’ indicates that the LMSI is not in use.

extension

This optional attribute is an instance of OM class Extension. See Extension.

5.3.19.12 LCS-Client-External-ID

An instances of LCS-Client-External-ID represent the external identifier for an LCS client.

An instances of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 420.

This OM class contains the following class-specific OM attributes:

external-Address

An ISDN Address String.

extension-Container

This optional attribute is an instance of OM class Extension-Container. See Extension-Container.

extension

This optional attribute is an instance of OM class Extension. See Extension.

5.3.19.13 MC-SS-Info

An instance of OM class MC-SS-Info represents multicall bearer supplementary service information.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attribtues listed in Table 417.

This OM class contains the following class-specific OM attributes:

ss-Code

SS-Code ::= OCTET STRING (SIZE(1))

ss-Status

Ext-SS-Status ::= OCTET STRING(SIZE(1..5)) This parameter refers to the state information of individual supplementary services as defined in 3GPP TS 23.011. Octet 1, bits 8765, unused (0000); bits 4321, used to convey the “P bit”, “R bit”, “A bit” and “Q bit”, representing supplementary service state information as defined in 3GPP TS 23.011: bit 4, “Q bit”; bit 3, “P bit”; bit 2, “R bit”; bit 1, “A bit”; octets 2-5, reserved for future use. They shall be discarded if received and not understood.

nbr-SB

MaxMC-Bearers ::= INTEGER (2..7)

nbr-User

MC-Bearers ::= INTEGER(1..7)

extension-Container

This optional attribute is an instance of OM class Extension-Container. See Extension-Container.

extension

This optional attribute is an instance of OM class Extension. See Extension.

5.3.19.14 NAEA-Preferred-CI

An instance of OM class NAEA-Preferred-CI represents the North American Equal Access preferred Carrier Identification.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 416.

This OM class contains the following class-specific OM attributes:

naea-Preferred-CIC

NAEA-CIC ::= OCTET STRING (SIZE(3)) The internal structure is defined by the Carrier Identification parameter in ANSI T1.113.3. Carrier codes between ‘000’ and ‘999’ may be encoded as 3 digits using ‘000’ to ‘999’, or as 4 digits using ‘0000’ to ‘0999’. Carrier codes between ‘1000’ and ‘9999’ are encoded using 4 digits.

extension-Container

This optional attribute is an instance of OM class Extension-Container. See Extension-Container.

extension

This optional attribute is an instance of OM class Extension. See Extension.

5.3.19.15 PCS-Extensions

An instances of OM class PCS-Extensions represents a sequence of PCS extensions each with an ASN.1 encoding. It is an optional attribute of OM class Extension-Container.

An instance of this OM class has the OM attributes of its superclass, Object, and additionally the OM attributes listed in Table 42.

This OM class contains the following class-specific OM attributes:

pcs-Extension

The pcs-Extension attribute consists of one or more ASN.1 encoded strings. Each string encoding is an element in a sequence of PCS extensions.

5.3.19.16 Private-Extension

An instance of OM class Private-Extension represents a single instance of private extension as defined by the MAP-EXTENSION macro of GSM MAP. Each private extension consists of a object identifier that identifies the type of the extension and an optional encoding of the extension value.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 39.

This OM class contains the following class-specific OM attributes:

ext-Type

The ext-Type attribute is an ASN.1 encoding of the extension type.

ext-Id

The ext-Id attribute is an object identifier that cannot exceed 16 octets in length and cannot exceed 16 sub-identifiers.

5.3.19.17 Private-Extension-List

An instance of OM class Private-Extension-List represents a list of private extensions used as an optional attribute of the OM class Extension-Container. The list may contain between one and ten private extensions.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 40.

This OM class contains the following class-specific OM attributes:

private-Extension

This attribute represents an instance of the MAP-CONTAINTER macro from the GSM MAP. There may be one to ten private extensions in an extension list.

5.3.19.18 SLR-Arg-Extension-Container

An instance of OM class SLR-Arg-Extension-Container represents an extension container for use within the Subscriber-Location-Report-Arg argument. See Subscriber-Location-Report-Arg.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 426.

This OM class contains the following class-specific OM attributes:

private-Extension-List

This optional attribute is an instance of OM class Private-Extension-List. See Private-Extension-List.

slr-Arg-PCS-Extensions

This optional attribute is an instance of OM class SLR-Arg-PCS-Extensions. See SLR-Arg-PCS-Extensions.

extension

This optional attribute is an instance of OM class Extension. See Extension.

5.3.19.19 SLR-Arg-PCS-Extensions

An instance of OM class SLR-Arg-PCS-Extensions represents PCS extensions for use within the SLR-Arg-Extension-Container. See SLR-Arg-Extension-Container.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 427.

This OM class contains the following class-specific OM attributes:

extension

This optional attribute is an instance of OM class Extension. See Extension.

na-ESRK-Request

A Null value whose presence provides indication.

5.3.19.20 Specific-Information

An instance of OM class Specific-Information represents additional specific extensions or private extensions added to a GSM MAP dialogue.

An instance of this OM class has the OM attributes of its superclasses, Object, and additionally the OM attributes listed in Table 44.

This OM class contains the following class-specific OM attributes:

extensions

This optional attribute is zero or more instances of OM class Extension. See Extension.

extension-Container

This optional attribute is an instance of OM class Extension-Container. See Extension-Container. This attribute may only be used with GSM MAP version 3 dialogues and is not applicable to version 1 or 2 dialogues.

5.3.19.21 Subscriber-Identity

An instance of OM class Subscriber-Identity represents the corresponding GSM MAP information object.

An instance of this OM class has the OM attributes of it superclasses, Object, and additionally the OM attributes listed in Table 410. This OM class represents a choice and exactly one attributes shall be present in an instance of this object.

This OM class contains the following class-specific OM attributes:

imsi

This attribute represents the International Mobile Subscriber Identity defined in 3GPP TS 23.003. The syntax of this attribute is an octet string containing a TBCD string (see String(TBCD)) between 3 and 8 octets (5 and 16 digits) in length, inclusive. Digits of MCC, MNC and MSIN are concatenated in the listed order.

msisdn

This attribute refers to one of the ISDN numbers assigned to a mobile subscriber in accordance with ITU-T Recommendation E.213. This attribute has syntax String(Address). See String(Address).

5.4 GSM MAP Services Packages

5.4.1 GSM Mobile Service Package

OM Hierarchy

• Object
  • Service-Argument
    • GSM-Service-Argument
      • Any-Time-Interrogation-Arg
      • Any-Time-Modification-Arg
      • Any-Time-Subscription-Interrogation-Arg
      • Authentication-Failure-Report-Arg
      • Cancel-Location-Arg
      • Check-IMEI-Arg
      • Delete-Subscriber-Data-Arg
      • Failure-Report-Arg
      • Forward-Access-Signalling-Arg
      • Forward-Check-SS-Indication-Arg
      • Insert-Subscriber-Data-Arg
      • Note-MM-Event-Arg
      • Note-Ms-Present-For-Gprs-Arg
      • Note-Subscriber-Data-Modified-Arg
      • Prepare-HO-Arg
      • Prepare-Subsequent-HO-Arg
      • Process-Access-Signalling-Arg
      • Provide-Subscriber-Info-Arg
      • Purge-MS-Arg
      • Reset-Arg
      • Restore-Data-Arg
      • Send-Authentication-Info-Arg
      • Send-End-Signal-Arg
      • Send-Identification-Arg
      • Send-Routing-Info-For-Gprs-Arg
      • Update-Gprs-Location-Arg
      • Update-Location-Arg
  • Service-Result
    • GSM-Service-Result
      • Any-Time-Interrogation-Res
      • Any-Time-Modification-Res
      • Any-Time-Subscription-Interrogation-Res
      • Authentication-Failure-Report-Res
      • Cancel-Location-Res
      • Check-IMEI-Res
      • Delete-Subscriber-Data-Res
      • Failure-Report-Res
      • Insert-Subscriber-Data-Res
      • MNP-Info-Res
      • Note-MM-Event-Res
      • Note-Ms-Present-For-Gprs-Res
      • Note-Subscriber-Data-Modified-Res
      • Prepare-HO-Res
      • Prepare-Subsequent-HO-Res
      • Provide-Subscriber-Info-Res
      • Purge-MS-Res
      • Restore-Data-Res
      • Send-Authentication-Info-Res
      • Send-End-Signal-Res
      • Send-Identification-Res
      • Send-Routing-Info-For-Gprs-Res
      • Update-Gprs-Location-Res
      • Update-Location-Res

5.4.1.1 Add-Info

An instance of OM class Add-Info represents the corresponding GSM MAP information object.

An instance of this OM class has the OM attributes of it superclasses, Object, and additionally the OM attributes listed in Table 124.

This OM class contains the following class-specific OM attributes:

imeisv

IMEI ::= TBCD-STRING(SIZE(8)) Refers to International Mobile Station Equipment Identity and Software Version Number (SVN) defined in 3GPP TS 23.003. If the SVN is not present, the last octet shall contain digit 0 and a filler. If present, the SVN shall be included in the last octet.

skip-Subscriber-Data-Update

A Null value whose presence provides indication.

extension

This optional attribute is an instance of OM class Extension. See Extension.

5.4.1.2 Allowed-UMTS-Algorithms

An instance of OM class Allowed-UMTS-Algorithms represents the corresponding GSM MAP information object.

An instance of this OM class has the OM attributes of it superclasses, Object, and additionally the OM attributes listed in Table 148.

This OM class contains the following class-specific OM attributes:

integrity-Protection-Algorithm

PermittedIntegrityProtectionAlgorithms ::= OCTET STRING (SIZE(1..9)) Octets contain a complete PermittedIntegrityProtectionAlgorithms data type as defined in 3GPP TS 25.413, encoded according to the encoding scheme mandated by 3GPP TS 25.413. Padding bits are included, if needed, in the least significant bits of the last octet of the octet string.

encryption-Algorithm

PermittedEncryptionAlgorithm ::= OCTET STRING (SIZE(1..9)) Octets contain a complete PermittedEncryptionAlgorithms data type as defined in 3GPP TS 25.413, encoded according to the encoding scheme mandated by 3GPP TS 25.413. Padding bits are included, if needed, in the least significant bits of the last octet of the octet string.

extension-Container

This optional attribute is an instance of OM class Extension-Container. See Extension-Container.

extension

This optional attribute is an instance of OM class Extension. See Extension.

5.4.1.3 AMBR

An instance of OM class AMBR represents the corresponding GSM MAP information object.

An instance of this OM class has the OM attributes of it superclasses, Object, and additionally the OM attributes listed in Table 183.

This OM class contains the following class-specific OM attributes:

max-Requested-Bandwidth-UL

Bandwidth ::= INTEGER Bits per second.

max-Requested-Bandwidth-DL

Bandwidth ::= INTEGER Bits per second.

extension-Container

This optional attribute is an instance of OM class Extension-Container. See Extension-Container.

extension

This optional attribute is an instance of OM class Extension. See Extension.

5.4.1.4 Any-Time-Interrogation-Arg

An instance of OM class Any-Time-Interrogation-Arg represents the information of a mobile application service operation request supplied as an argument to the Service-req() function (see Service-req) or is returned by the Receive() function (see Receive) for a mobile application service operation indication.

An instance of this OM class has the OM attributes of it superclasses, Object, Service-Argument, GSM-Service-Argument, and additionally the OM attributes listed in Table 288.

This OM class contains the following class-specific OM attributes:

subscriber-Identity

This attribute is an instance of OM class Subscriber-Identity. See Subscriber-Identity.

requested-Info

This attribute is an instance of OM class Requested-Info. See Requested-Info.

gsmSCF-Address

An ISDN Address String.

extension-Container

This optional attribute is an instance of OM class Extension-Container. See Extension-Container.

extension

This optional attribute is an instance of OM class Extension. See Extension.

5.4.1.5 Any-Time-Interrogation-Res

An instance of OM class Any-Time-Interrogation-Res represents the information of a mobile application service operation response supplied as the Response argument to the Service-rsp() function (see Service-rsp) or is returned in the Result-Or-Argument result by the Receive() function (see Receive) for a mobile application service operation confirmation.

An instance of this OM class has the OM attributes of it superclasses, Object, Service-Result, GSM-Service-Result, and additionally the OM attributes listed in Table 289.

This OM class contains the following class-specific OM attributes:

subscriber-Info

This attribute is an instance of OM class Subscriber-Info. See Subscriber-Info.

extension-Container

This optional attribute is an instance of OM class Extension-Container. See Extension-Container.

extension

This optional attribute is an instance of OM class Extension. See Extension.

5.4.1.6 Any-Time-Modification-Arg

An instance of OM class Any-Time-Modification-Arg represents the information of a mobile application service operation request supplied as an argument to the Service-req() function (see Service-req) or is returned by the Receive() function (see Receive) for a mobile application service operation indication.

An instance of this OM class has the OM attributes of it superclasses, Object, Service-Argument, GSM-Service-Argument, and additionally the OM attributes listed in Table 299.

This OM class contains the following class-specific OM attributes:

subscriber-Identity

This attribute is an instance of OM class Subscriber-Identity. See Subscriber-Identity.

gsmSCF-Address

An ISDN Address String.

modification-Request-For-CF-Info

This optional attribute is an instance of OM class Modification-Request-For-CF-Info. See Modification-Request-For-CF-Info.

modification-Request-For-CB-Info

This optional attribute is an instance of OM class Modification-Request-For-CB-Info. See Modification-Request-For-CB-Info.

modification-Request-For-CSI

This optional attribute is an instance of OM class Modification-Request-For-CSI. See Modification-Request-For-CSI.

extension-Container

This optional attribute is an instance of OM class Extension-Container. See Extension-Container.

long-FTN-Supported

A Null value whose presence provides indication.

extension

This optional attribute is an instance of OM class Extension. See Extension.

modification-Request-For-ODB-Data

This optional attribute is an instance of OM class Modification-Request-For-ODB-Data. See Modification-Request-For-ODB-Data.

modification-Request-For-IP-SM-GW-Data

This optional attribute is an instance of OM class Modification-Request-For-IP-SM-GW-Data. See Modification-Request-For-IP-SM-GW-Data.