Links

GitHub

Open HUB

Quick Links

Download

STREAMS

SIGTRAN

SS7

Hardware

SCTP

Related

Package

Manual

FAQ

Library

SDLI Tech Spec

SDTI Tech Spec

SLI Tech Spec

MTPI Tech Spec

TRI Tech Spec

TCI Tech Spec

ISUPI Tech Spec

BICCI Tech Spec

MAPI Tech Spec

CDI Tech Spec

DLPI Tech Spec

NPI Tech Spec

TPI Tech Spec

WAN Tech Spec

LLI Tech Spec

NLI Tech Spec

CHI Tech Spec

MXI Tech Spec

MGI Tech Spec

XCC Tech Spec

XGCP Tech Spec

XMAP Tech Spec

Resources

Packages

Sys Req

Repositories

Download

Mailing Lists

Browse Source

CVS Archive

Bug Reports

Library

Hardware

Vendor Links

Home

Overview

Status

Documentation

Resources

About

News

XGCP Technical Specification

Description: OpenSS7 Project Library XGCP

A PDF version of this document is available here.

XOM Gateway Control Protocol (XGCP)

XOM Gateway Control Protocol (XGCP) Specification

About This Manual

This is Edition 7.20141001, last updated 2014-10-25, of The XOM Gateway Control Protocol (XGCP) Specification, for Version 1.1 release 7.20141001 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 Gateway Control Protocol (XGCP) for OpenSS7. It contains recommendations on software architecture as well as platform and system applicability of the XOM Gateway Control Protocol (XGCP).

This document specifies a XOM Gateway Control Protocol (XGCP) Specification in support of the OpenSS7 Gateway Control Protocol (GCP) protocol stacks. It provides abstraction of the Gateway Control Protocol interface to these components as well as providing a basis for Gateway Control Protocol control for other Gateway Control Protocol protocols.

Purpose

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

Audience

The audience for this document is software developers, maintainers and users and integrators of the XOM Gateway Control Protocol (XGCP). 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.7.20141001.1

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: xgcp.texi,v $
Revision 1.1.2.2  2011-07-27 07:52:18  brian
- work to support Mageia/Mandriva compressed kernel modules and URPMI repo

Revision 1.1.2.1  2011-07-18 19:42:12  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:

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 Gateway Control Protocol Programming Interface (abbreviated XGCP) defines an Application Program Interface (API) to gateway control 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 Telcordia, Level 3 and Cisco RFC 2705 MGCP Version 1.0, the IETF MEGACO Version 2.0, the ITU-T Recommendation H.248 GCP Version 2.0, and the ITU-T Recommendation H.248 GCP Version 3.0 standards. These standards have been published starting in 1999 and have been stable for many years. The ITU-T Recommendation H.248 GCP Version 3.0 was last updated in 2005.

The interface is also designed to offer services that are consistent with various packages provided by MGCP, MEGACO and H.248.

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

Access to other gateway control 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 Gateway Control Services is given in Introductory Concepts. Following this is an overview of the 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 MGCP, reference MEGACO, reference H.248), or to the XOM Specifications (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 described a programming language-independent interface to the Gateway Control 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 GCP Protocols

The interaction between gateway control programs acting in a gateway control entity role are realized through the exchange of gateway control service information. The general communications service for gateway control is the Gateway Control Protocol. GCP defines the following operations:

ServiceType

This communication may be accomplished using the MGCP, MEGACO or H.248 protocol.


1.3.2 XGCP and the GCP Provider

The XGCP interface provides access to the GCP service provider, which offers all of the facilities defined in the Standards. It also provides facilities such as Automatic Association Management, Automatic Message Handling and Automatic Dialog Handling. The interface is designed not to restrict the services offered to those of specific service packages of the H.248 protocol or any given profile of packages.

The interface defined in this specification is “symmetrical” in the sense that it can be used to implement gateway control programs acting in any of the GCP producer or consumer roles (e.g. MGC, MG, CA, S-SBG, D-SBG). The interface supports:

  • a gateway control program acting as a consumer of gateway control services. This is done by submitting service operation requests and receiving service operation responses.
  • a gateway control program acting as a producer of gateway control services. This is done be 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 gateway control 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 MGCP and MEGACO/H.248 GCP

The API is essentially based on the abstract services of MGCP and MEGACO/H.248, bit is independent of the underlying communications stack. The API allows the manipulation of ITU-T and pre-standard gateway control protocol service information. Thus this API does not preclude and does not force the use of either the MGCP pre-standard protocol or the MEGACO/H.248 standard protocol (of any version).

The XGCP API offers three abstract gateway control service views: that of MGCP Version 1.0, MEGACO Version 2.0, and H.248 GCP Version 3.0.

The contents of the MGCP messages are described in RFC 2705. These messages implicitly define MGCP GCP services. The mapping between MGCP GCP services and various service primitives and parameters of the XGCP API are described below.

The services offered by the XGCP API are a superset of those defined by MGCP, MEGACO and H.248 GCP. The general communications protocol for each is the User Datagram Protocol (UDP) or the Stream Control Transmission Protocol (SCTP) defined by the IETF.

The three abstract gateway control view of XGCP (MGCP, MEGACO and H.248) are independent of the underlying protocol.


1.5 Relationship to Data Abstraction Services

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

The definitions below introduce various concepts that are used by Gateway Control data abstraction service.

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 Gateway Control 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 XGCP 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 Gateway Control 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 Gateway Control Services itself actually makes use of UDP or SCTP or other parts of the model, just so long as it provides the defined service. Also, the scope of the Gateway Control Services to which an application has access is not determined; it is not restricted to H.248 GCP 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 Gateway Control 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 Gateway Control 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, Automatic Message Handling and Automatic Dialog Handling by the GCP provider.

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

1.6.1 Packages

The specification defines several Gateway Control packages (Common GCP package, MGCP package, MEGACO package, and H.248 package), Interface Packages. These packages define the OM classes required by the interface functions to perform GCP services. The common GCP package, which also includes the errors defined (see Errors), is mandatory. The MGCP, MEGACO and H.248 packages are optional, but at least one of them must be supported by the implementation. The different service views assume the support of the corresponding GCP package by the implementation.

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

1.6.2 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.6.3 Abbreviations

APIApplication Program Interface
ASN.1Abstract Syntax Notation One
ANSIAmerican National Standards Institute
BERBasic Encoding Rules
GSMGlobal Services Mobile
ISOInternational Organisation for Standardisation
ITU-TInternational Telecommunications Union - Telecom Sector
MAPMobile Application Part
OMOSI-Abstract-Data Manipulation
OSIOpen Systems Interconnect
ROSERemote Operations Service Element
TCAPTransaction Capabilities Application Part
XMAPXOM Mobile Application Part API
XOMX/Open: OSI-Abstract-Data Manipulation API

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 Gateway Control 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.

<xgcp.h>

This header file contains common definitions for the access to the Gateway Control Protocol service (see Interface Functions, and Common GCP Package).

<xmap_mgcp.h>

This header file contains specific definitions that reflect the Abstract Services of the MGCP Gateway Control Services along with the ASN.1 productions of the related protocol (MGCP), See MGCP Package.

<xmap_megaco.h>

This header file contains specific definitions that reflect the Abstract Services of the MEGACO Gateway Control Services along with the ASN.1 productions of the related protocol (MEGACO), See MEGACO Package.

<xmap_h248.h>

This header file contains specific definitions that reflect the Abstract Services of the H.248 Gateway Control Services along with the ASN.1 productions of the related protocol (H.248), See H.248 Package.

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


2.1 C Naming Conventions

The interfaces uses part of the ‘C’ public namespace for its facilities. All identifiers start with the letters gcp, GCP or OGCP, and more detail of the conventions used are given in the following table. Note that the interface reserves all identifiers starting with the letters gcpP for private (i.e. internal) use by implementations of the interface. It also reserves all identifiers starting with the letters gcpX or GCPX 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.

reserved for implementorsgcpP
reserved for interface extensionsgcpX
reserved for interface extensionsGCPX
reserved for implementorsOGCP
functionsgcp_
error problem valuesGCP_E_
enumeration tags (except errors)GCP_T_
OM class namesGCP_C_
OM value length limitsGCP_VL_
OM value number limitsGCP_VN_
other constantsGCP_

A complete list of all identifiers used (except those beginning gcpP, gcpX, GCPX or OGCP) 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 gcp_. Thus Service-Req() becomes gcp_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 GCP_C_. Thus Service-Argument becomes GCP_C_SERVICE_ARGUMENT. Note that the symbolic OM class names are strictly those used in the abstract syntax ASN.1 of the TCAP and GCP 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 GCP_. The case of letters is left unchanged. Thus Enum(User-reason) befomes GCP_User_reason.
  • Enumeration constants, except erros, are made entirely upper-case and prefixed by GCP_T_. Thus resource-limitation becomes GCP_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 GCP_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 GCP 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 GCP_E_. Thus invalid-session becomes GCP_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 GCP_VL_ for value length, or GCP_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 GCP_status, which is an error indication. If and only if the function succeeds, its value will be success, expressed in C by the constant GCP_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 <xgcp.h> headers in that order, and at least one of the <xgcp_mgcp.h>, <xgcp_megaco.h> and <xgcp_h248.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 MGCP, MEGACO and H.248).

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

All interactions between a Consumer and a Producer belong to a session, that 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 Abstract Services maps to a single function call with the same name. The services are Service-req and Service-rsp.

There are three functions called Receive(), Wait(), and Abandon() that 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()2 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 GCP package, See Interface Class Definitions.

The workspace can be extended to support one of the MGCP, MEGACO or H.248 packages, or any combination of them (see Interface Class Definitions, and any combination of the optional Gateway Control 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 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 gateway control sessions using Bind().3 All the sessions on a given workspace share the same features.

Eventually, when it has completed its tasks, terminated all its gateway control 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 arise 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 gateway control 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 systems responsible for producing gateway control 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 gateway services. For example, the UDP-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 system name responsible for producing gateway control 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.4

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 take precedence over the “session” Title or 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 take 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 gateway control 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.5 It is created, and appropriate parameter values may be set, using the OSI-Abstract-Data Manipulation functions. A gateway control session is then started with Bind() (see Bind) and later is terminated with Unbind() (see Unbind). A session with default parameters can be started by passing the constant Default-Session (‘(OM_object)GCP_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 using the same session object.

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

Detailed specifications of the OM class Session are given in Session.

A session can be used either acting as a consumer of gateway control services, or acting as a producer of gateway control 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 gateway control 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 aspects of session objects, as follows:

  1. A session can have Automatic Association Management enabled or disabled.
  2. A session can have Automatic Dialog Handling enabled or disabled.
  3. A session can have Automatic Message Handling enabled or disabled.

These aspects are described in sub-sections below.


3.2.1 Association Management


3.2.1.1 AAM Enabled Session

The Session collects together all the information that described a particular gateway control 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().6 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 gateway control information with another program designated (the responder) or by default to all programs.

An AAM enabled session thus allows a gateway control entity to access either a portion of the gateway control services (that is, that are accessible via the designated responder) or all gateway control services. In the later case, the producer gateway control entity resolution is performed by the Gateway Control Service provider, according to the gateway control 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.1.2 AAM Disabled Session

A session object can has Automatic Association Management (AAM) disabled when it belongs to a workspace that has had AAM disabled with Negotiate(). Disabling AAM allows the user to explicitly send and receive underlying transport operations to build and tear down associations. It gives explicit control over associations to the user. The Gateway Control Service provider does not automatically perform any underlying transport 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:

  • requester-Address — the address (IP address) used by the local gateway control entity to communicate with remote gateway control entities. When not specified for MGC entities, the requester-Title must resolve to an address (i.e. using DNS).
  • requester-Title — the title (host name) used by the local gateway control entity to communicate with remote gateway control entities. When not specified for MGC entities, the requester-Address must be specified.
  • role – the role of the local gateway control entity to be taken in communications with associated entities. This can either identify the MGC role or the MG role.

The session object is then passed as an argument to the Bind() function (see Bind) that binds the session. This bound session can only used to send underlying transport related operations and to receive underlying transport related primitives. The following can be sent/received using this type of bound session.

  • Receive() (gcp_receive()/‘GCP_TRANSPORT_IND’)
  • Receive() (gcp_receive()/‘GCP_TRANSPORT_CNF’)
  • Assoc-req() (gcp_assoc_req())
  • Assoc-rsp() (gcp_assoc_rsp())

The other attributes that relate to the underlying transport 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.1.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 an receiving gateway control transaction 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 gateway control 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.2 Message Handling


3.2.2.1 AMH Enabled Session

The AMH enabled session allows a gateway control entity to invoke and respond to gateway control services requests and indications without regard for message handling. The Gateway Control Services provider provides all message handling.

This type of session cannot be used to send messages explicitly. To dispatch messages explicitly, see AMH Disabled Session.


3.2.2.2 AMH Disabled Session

A session object can have Automatic Message Handling disabled when it belongs to a workspace that has Automatic Message Handling disabled using the Negotiate() function. This allows the user to explicitly send and receive message handling operations to establish, group and dispatch messages. it gives explicit control over messages to the user. The Gateway Control Service provider does no message handling operations on behalf of the user.

Oncee the session object is bound (AAM enabled) or associated (AAM disabled) and has AMH disabled, the session must explicitly issue message handling operations for each gateway control services transaction. This bound or associated session can only be used to send message handling primitives. The following can be sent/received using this type of bound or associated session:

  • Receive() (gcp_receive()/‘GCP_MESSAGE_IND’)
  • Send() (gcp_send()/‘GCP_MESSAGE_REQ’)

The other attributes that relate to message handling are specified within the Send-Argument or Message-Result objects that are passed to, or returned from, Send() or Receive().


3.2.2.3 Message Session

Once a user has created a bound or associated session that has AMH disabled, a message can be created. A message is represented by a fully formed, or partially formed message, session obejct. A message session is returned as the result of building a new message. The message session is used, like a bound or associated session, by sending and receiving gateway control service operations. The major difference is that a message session object can only be used to send and receive operations within a single message with a single remote gateway control entity. After a session forms a message, the user can close or abort the message, 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 message session objects. Once a session has formed a message, the message related argument, application-Context-Name, cannot be overridden by the context object.

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


3.2.3 Dialog Handling

MGCP only permits one service request or response per message. For MGCP dialog handling is trivial and can be handled automatically by the Gateway Control Service provider.

MEGACO and H.248, on the other hand, permit multiple commands within multiple communications contexts per transaction (where each transaction is essentially a dialogue). Actions or commands that are send within a transaction are executed in sequential order, where the first action or command must be completed before the next action or command is initiated. There is no guarantee of synchronization or timing between actions or commands that are placed in separate transactions. Therefore, for actions or commands that must be executed in order, there are two approaches from an API perspective:

  1. Issue the commands or actions in separate transactions; however, do not issue a subsequent action or command until the response to the preceding action or command has been received. Actions or commands can be issued synchronously or asynchronously, without affecting the sequence of events, just allowing the calling process to proceed and do other things awaiting message receipt.
  2. Collect the commands or actions into a single transaction.

Note that the first method is the only method applicable to MGCP because MGCP does not permit actions or commands to be grouped into transactions: there is imply one action per message. This does not cause any logical difficulties for MGCP with the minor exception that if a message is lost, a noticeable delay might occur between actions or commands.7

In general, the Gateway Control Services provider acting on behalf of a service invoker can select the mosts appropriate approach from those outlined above and made possible by the Standards; however, the XGCP interface requires a mechanism for communicating which actions or commands depend upon which others, and whether the remainder of the sequence be encountered should an error be encountered for one of the actions or commands in the sequence.

To distinguish groupings of actions or commands, actions or commands can be grouped into dialogues. Dialogues are a sequence of operations the form a unit. They are directly related to ‘transactions’ in ITU-T Recommendation H.248.1 (09/2005).


3.2.3.1 ADH Enabled Session

A session object has Automatic Dialog Handling (ADH) enabled by default, or when it belongs to a workspace that has had ADH disabled using the Negotiate() function. The ADH enabled session allows a gateway control entity to invoke and respond to gateway control services requests and indications without regards for dialog handling. The Gateway Control Services 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.3.2 ADH Disabled Session

A session object has Automatic Dialog Handling (ADH) disabled when it belongs to a workspace that has had ADH disabled using the Negotiate() function.

This allows the user to explicitly send and receive transaction handling operations to establish, group and dispatch transactions. It gives explicit control over transactions to the user. The Gateway Control Service provider does no transaction 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 transaction handling operations for each gateway control services request or response. This bound or associated session can only be used to send transaction handling primitives. The following can be sent/received using this type of bound or associated session:

  • Receive() (gcp_receive()/‘GCP_OPEN_IND’)
  • Receive() (gcp_receive()/‘GCP_ACCEPT_CNF’)
  • Receive() (gcp_receive()/‘GCP_REFUSE_CNF’)
  • Open() (gcp_open()) See Open.
  • Accept() (gcp_accept()) See Accept.
  • Refuse() (gcp_refuse()) See Refuse.

The other attributes that relate to transaction 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.3.3 Dialog Session

Once a user has created a bound or associated session that has ADH disabled, a transaction can be created. A transaction is represented by a fully formed, or partially formed transaction, session object. A transaction session is returned as the result of building a new transaction. The transaction session is used, like a bound or associated session, by sending and receiving gateway control service operations. The major difference is that a transaction session object can only be used to send and receive operations within a single transaction with a single remote gateway control entity. After a session forms a transaction, the user can close or abort the transaction, 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 transaction session objects. Once a session has formed a transaction, the transaction related argument, application-Context-Name, cannot be overridden by the context object.

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


3.3 Context

The context defines the characteristics of the gateway control interaction that are specific to a particular gateway control 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 gateway control interaction, these arguments are collected into an OM object of OM class Context, which is supplied as the second argument of each gateway control 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 affects the processing of each gateway control 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, 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 administered. The constant Default-Context (‘GCP_DEFAULT_CONTEXT’) can be passed 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 H.248 package is concerned, OM classes are defined with a one-to-one mapping to the ASN.1 Abstract Syntax of H.248. 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

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

  1. The encoding and decoding functionality can be provided internally with the XGCP 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 gateway control services package. The XGCP 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 XGCP API does not specify the use of OM-Encode or OM-Decode for the OM classes defined in this specification, or in gateway control 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 MGCP, MEGACO and H.248 packages defined by this specification are ASN.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 Gateway Control 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 Gateway Control 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 (MGCP, MEGACO or H.248) of the current operation.

The argument for a Service-req() function is represented by an instance of the OM Class MGCP-Service-Req-Argument for an MGCP operation, or an instance of the OM Class MEGACO-Service-Req-Argument for a MEGACO operation, or H248-Service-Req-Argument for an H.248 operation.

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


3.5 Function Results

All functions return a Status (which is the C function result). Most return an Dialog-ID which identifies the particular invocation. The confirmed operations each return a Result. (The Dialog-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 Dialog-ID

All interface functions that invoke a gateway control service operation return an Dialog-ID; an integer that identifies the particular invocation of an operation. The Dialog-ID is only relevant for asynchronous confirmed operations and may be used later to receive the Status and Result, or to abandon them. The Dialog-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 Dialog-ID returned from a call that successfully invoke an asynchronous confirmed operation is guaranteed to be unique amongst all outstanding operations in given session. Dialog IDs used by XGCP are not necessarily those that are actually sent via an underlying protocol such as H.248. Dialog IDs may be mapped or altered by the Gateway Control 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 gateway control 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 gateway control 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 gateway control 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 gateway control 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, that is either the constant success (‘(GCP_status)0’ or ‘GCP_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 GCP_ABSENT_OBJECT means no replies were received.

In most cases other results of functions are initialized to Null (GCP_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 GCP_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 Gateway Control 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 gateway control 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 a Dialog-ID of the operation to the application. The same Dialog-ID will be returned by Receive() on the corresponding result.

A Dialog-ID is also returned by Receive() on an indication of an invoked gateway control service operation. The same Dialog-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 Gateway Control 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 (‘GCP_MAX_OUTSTANDING_OPERATIONS’) and is at least 10 for conforming XGCP 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 Gateway Control 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 Gateway Control 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 Gateway Control Service provider.

The Gateway Control Protocols are not restricted to those defined by H.248.

All the features listed below are for the most part necessary for ease of use in a gateway control 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 Gateway Control Services provider makes use of association oriented communication services, such as TCP or SCTP, the Gateway Control Service provider implementations are assumed to provide automatic handling of the association between gateway control 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 Message Handling

When the Gateway Control Services provider makes use of message oriented communication services, such as that provided by H.248, the Gateway Control Service provider implementations are assume to provide automatic handling of messages between gateway control entities, grouping transactions into messages at its discretion. Such handling is intended to bring benefits such as reduced communication overheads. To allow this flexibility to the implementation, the interface does not specify which transactions are packed into which messages. Automatic Message Handling (AMH) may be enabled or disabled on a per-workspace basis using the Negotiate() function.8


3.7.3 Automatic Dialog Handling

When the Gateway Control Services provider makes use of transaction oriented communication services, such as that provided by H.248, the Gateway Control Service provider implementations are assumed to provide automatic handling of transactions between gateway control entities, establishing and releasing transactions at its discretion. Such handling 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.9

Under MEGACO and H.248, transactions are used to provide for sequencing of a set of commands. Commands that are contained within separate transactions provide no guarantees whatsoever of ordering. When ordering of commands is required, either the commands must be placed into the same transaction, or the result of each command must be awaited before issuing the subsequent command. Due to the possibility of message loss and the delays associated with retransmission of the lost messages, the later approach (awaiting the result of the previous command before issuing the current command) can introduce inter-command delays that may or may not be acceptable. On the other hand, preparing the full sequence of commands in advance may not be possible, as the next command chosen may depend on the results of a previous command. In general; however, grouping multiple commands into a transaction can serve to provide a limited set of compound commands from short sequences of simple commands.


3.7.4 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 Gateway Control Service provider may be assumed to provide automatic gateway control service and application context to consumer resolution: to find out the consumer that is in charge of the selected gateway control service specified in the gateway control service operation.


3.7.5 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 Gateway Control Service provider or not requested. This applies if the underlying Gateway Control Service provider is connection-less.


3.7.6 Automatic Name to Address Resolution

Gateway Control Service provider implementation may provide automatic resolution between program name and address to find the network address of a gateway control entity from its name using directory or translation services.


3.7.7 Automatic Dispatching to Appropriate Stack

The Gateway Control 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 gateway control services operation to the proper underlying communications stack according to the implied gateway control service and the destination (for example over UDP or SCTP).


3.8 Function Sequencing

A minimum set of sequencing rules applies when using the interface to exchange gateway control service information between gateway control programs acting as a gateway control entity. These rules need to be respected by gateway control 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.10

The general rules to follow are:

  1. Initialize a workspace (‘gcp_initialize()’)
  2. Negotiate features of the interface (‘gcp_negotiate()’)
  3. Open one or several sessions (‘gcp_bind()’)
  4. Perform gateway control service interactions (operations) using the offered interface functions. An interaction is identified by its Dialog-Id.
  5. Close the opened sessions (‘gcp_unbind()’)
  6. Discard the workspace (‘gcp_shutdown()’)

Seven states are defined in the interface to cover both interface service operations and gateway control service interactions:

UNINIT

Workspace uninitialized.

INIT

Workspace initialized.

UNBND

Session closed.

BND

Session opened.

IDLE
OUTOP

Outstanding operation requested in a gateway control service interaction.

OPIND

Operation indication received in a gateway control service interaction.


4 Interface Packages


4.1 Feature Packages


4.1.1 Common GCP Package

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

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

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


4.1.2 MGCP Package

The Object-Identifier associated with the MGCP package is:

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

This Object-Identifier is represented by the constant MGCP-Package (‘GCP_MGCP_PKG’).


4.1.3 MEGACO Package

The Object-Identifier associated with the MEGACO package is:

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

This Object-Identifier is represented by the constant MEGACO-Package (‘GCP_MEGACO_PKG’).

The Object-Identifiers associated with the MEGACO package for various versions of the protocol are:

  { iso(1) org(3) dod(6) internet(1) private(4) enterprises(1) openss7(29591)
    xom-packages(1) xgcp(2) megaco(3) v1(1) }
  { iso(1) org(3) dod(6) internet(1) private(4) enterprises(1) openss7(29591)
    xom-packages(1) xgcp(2) megaco(3) v2(2) }
  { iso(1) org(3) dod(6) internet(1) private(4) enterprises(1) openss7(29591)
    xom-packages(1) xgcp(2) megaco(3) v3(3) }

This Object-Identifiers are represented by the constants MEGACO-V1-Package (‘GCP_MEGACO_V1_PKG’), MEGACO-V1-Package (‘GCP_MEGACO_V2_PKG’) and MEGACO-V1-Package (‘GCP_MEGACO_V3_PKG’), respectively.


4.1.4 H.248 Package

The Object-Identifier associated with the H.248 package is:

  { itu-t(0) recommendation(0) h(8) h248(248) part1(1) }

This Object-Identifier is represented by the constant H248-Package (‘GCP_H248_PKG’).

The Object-Identifiers associated with the H.248.1 package for various versions of the protocol are:

  { itu-t(0) recommendation(0) h(8) h248(248) part1(1) version1(1) }
  { itu-t(0) recommendation(0) h(8) h248(248) part1(1) version1(2) }
  { itu-t(0) recommendation(0) h(8) h248(248) part1(1) version1(3) }

This Object-Identifiers are represented by the constants MEGACO-V1-Package (‘GCP_H248_V1_PKG’), MEGACO-V2-Package (‘GCP_H248_V2_PKG’) and MEGACO-V3-Package (‘GCP_H248_V3_PKG’), respectively.


4.1.5 H.248 Extension Packages


4.1.5.1 H.248.x Sub-series Extension Packages

ITU-T Recommendation H.248.1 (09/2005) provides for its own extension package concept. Each extension package is in a part of the H.248 suite of specifications. There are over 50 of these extension packages defined and the list is too long to repeat here and the list would contain too much redundant information (see ITU-T Recommendations Series H Supplement 2 (07/2010) for a guide to the ITU-T H.248.x sub-series packages). Therefore, these recommendations and extension packages are identified by an Object-Identifier of the general form: { itu-t(0) recommendation(0) h(8) h248(248) partX(X) versionY(Y) }, where, ‘X’ is the part number in the H.248 suite (for example, for H.248.12, ‘X’ is ‘12’); and, ‘Y’ is the GCP protocol version (for example, for GCP Version 3, ‘Y’ is ‘3’). The ‘C’ language binding of these Object-Identifiers are H248-X-VY-Package (‘GCP_H248_X_VY_PKG’). To refer to the extension package without specifying the version, use { itu-t(0) recommendation(0) h(8) h248(248) partX(X) } only. The ‘C’ language binding of these Object-Identifiers are H248-X-Package (‘GCP_H248_X_PKG’).

The ITU-T Recommendation H.248.x sub-series extension packages are itemized in Table 4.1, Table 4.2, Table 4.3 and Table 4.4.

ITU-T H.248.1 Annex EBasic packages.
ITU-T H.248.2Facsimile, text, conversation and call discrimination packages.
ITU-T H.248.3User interface elements and actions package.
ITU-T H.248.6Dynamic tone definition package.
ITU-T H.248.7Generic announcement package.
ITU-T H.248.9Advanced media server packages.
ITU-T H.248.10Media gateway resource congestion handling package.
ITU-T H.248.11Media gateway overload control package.
ITU-T H.248.12H.248.1 packages for H.323 and H.324 interworking.
ITU-T H.248.12 Annex AExtended H.324, H.245 command and H.245 indication packages.
ITU-T H.248.13Quality alert ceasing package.
ITU-T H.248.14Inactivity timer package.
ITU-T H.248.15SDP H.248 package attribute.
ITU-T H.248.16Enhanced digit collection packages and procedures.
ITU-T H.248.17Line test packages.
ITU-T H.248.18Package for support of multiple profiles.
ITU-T H.248.19Decomposed MCU, audio, video and data conferencing packages.

Table 4.1: ITU-T Rec. H.248.x Packages (1–19)

ITU-T H.248.20Local and remote descriptors with H.221/H.223 multiplexing.
ITU-T H.248.21Semi-permanent connection handling package.
ITU-T H.248.22Shared risk group package.
ITU-T H.248.23Enhanced alerting packages.
ITU-T H.248.24MF tone generation and detection packages.
ITU-T H.248.25Basic CAS packages.
ITU-T H.248.26Enhanced analogue lines package.
ITU-T H.248.27Supplemental tones packages.
ITU-T H.248.28International CAS packages.
ITU-T H.248.29International CAS compelled register signalling packages.
ITU-T H.248.30RTCP extended performance metrics package.
ITU-T H.248.31Adaptive jitter buffer package.
ITU-T H.248.32Detailed congestion reporting package.
ITU-T H.248.33PCM frame spare bit package.
ITU-T H.248.34Stimulus analogue line package.
ITU-T H.248.35Coin-operated phone control package.
ITU-T H.248.36Hanging termination detection package.
ITU-T H.248.37IP NAPT traversal package.
ITU-T H.248.38Base context package.
ITU-T H.248.39SDP parameter identification and wildcarding.

Table 4.2: ITU-T Rec. H.248.x Packages (20–39)

ITU-T H.248.40Application data inactivity detection package.
ITU-T H.248.41IP domain connection package.
ITU-T H.248.42DCME interworking package.
ITU-T H.248.43Gate management packages.
ITU-T H.248.44Multi-level precedence and pre-emption package.
ITU-T H.248.45MGC information package.
ITU-T H.248.46Connection capability control package.
ITU-T H.248.47Statistic conditional reporting package.
ITU-T H.248.48RTCP XR block reporting package.
ITU-T H.248.49SDP RFC packages.
ITU-T H.248.50NAT traversal toolkit packages.
ITU-T H.248.51Termination connection model package.
ITU-T H.248.52Quality of service packages.
ITU-T H.248.53Traffic management packages.
ITU-T H.248.54MPLS support package.
ITU-T H.248.55Generic pull mode package.
ITU-T H.248.56Virtual private network packages.
ITU-T H.248.57RTP control protocol package.
ITU-T H.248.58Package for application of level H.248 statistics.
ITU-T H.248.59Event timestamp notification package.

Table 4.3: ITU-T Rec. H.248.x Packages (40–59)

ITU-T H.248.60Identification of content of communication package.
ITU-T H.248.61Packages for network level H.248 statistics.
ITU-T H.248.62Re-answer package.
ITU-T H.248.63Resource management package.
ITU-T H.248.64IP router packages.
ITU-T H.248.65Support of the resource reservation protocol.
ITU-T H.248.66Packages for RTSP and H.248 interworking.
ITU-T H.248.67GCP transport mode indication package.
ITU-T H.248.68Package for removal of digits and tones.
ITU-T H.248.69Packages for interworking between MSRP and H.248.
ITU-T H.248.70Dialling method information packages.
ITU-T H.248.71RTCP support packages.
ITU-T H.248.72ITU-T H.248 support for MONA.
ITU-T H.248.73MSCML and ITU-T H.248 interworking.
ITU-T H.248.74Media resource control enhancement package.
ITU-T H.248.75Package identifier publishing and application package.
ITU-T H.248.76Filter group package and guidelines.
ITU-T H.248.77SRTP package and procedures.
ITU-T H.248.78Bearer-level application level gateway.
ITU-T H.248.80Usage of the revised SDP offer/answer model with H.248.

Table 4.4: ITU-T Rec. H.248.x Packages (60–80)


4.1.5.2 Q.1950 Annex A Extension Packages

ITU-T Recommendation Q.1950 (12/2002) and ITU-T Recommendation Q.1950 Amendment 1 (01/2006) provide for additional H.248 extension packages that are numbered separately from H.248.x sub-series packages. These recommendations and extension packages are identified by an Object-Identifier of the general form: { itu-t(0) recommendation(0) q(17) q1950(1950) AnnexY(Y) PartX(X) }, where, ‘Y’ is the annex number (for example, for Q.1950 Annex A, ‘Y’ is ‘1’); ‘X’ is the part number in the Q.1950 suite (for example, for Q.1950 Annex A.6, ‘X’ is ‘6’), but is only specified when there is a part of the Annex. The ‘C’ language binding of these Object-Identifiers is CBC-AnnexY-X-Package (‘GCP_CBC_ANNEXY_X_PKG’). To refer to the complete set of CBC extensions without reference to a specific part, use { itu-t(0) recommendation(0) q(17) q1950(1950) } only. The ‘C‘ language binding of these Object-Identifiers are CBC-Package (‘GCP_CBC_PKG’).

The ITU-T Recommendation Q.1950 extension packages are itemized in Table 4.5.

ITU-T Q.1950/A.3Bearer characteristics package.
ITU-T Q.1950/A.4Bearer network connection cut through package.
ITU-T Q.1950/A.5Reuse idle package.
ITU-T Q.1950/A.6Generic bearer connection package.
ITU-T Q.1950/A.7Bearer control tunnelling package.
ITU-T Q.1950/A.8Basic call progress tones generator with directionality.
ITU-T Q.1950/A.9Expanded call progress tones generator package.
ITU-T Q.1950/A.10Basic services tones generation package.
ITU-T Q.1950/A.11Expanded services tones generation package.
ITU-T Q.1950/A.12Intrusion tones generation package.
ITU-T Q.1950/A.13Business tones generation package.
ITU-T Q.1950/BCBC continuity test. NOTE 1.
ITU-T Q.1950/CCBC BIWF congestion handling. NOTE 2.
ITU-T Q.1950/DCBC N x 64k package.
ITU-T Q.1950/ECBC extensions for access networks that support BICC.
ITU-T Q.1950/FCBC emergency call indication.
ITU-T Q.1950/GCBC international emergency preference scheme.

NOTES:

  1. This package requires the H.248.1 Basic continuity test control package.
  2. This package requires the H.248.10 Media Gateway resource congestion handling package.

Table 4.5: ITU-T Rec. Q.1950 (12/2002) Packages


4.2 Feature Profiles

The Standards provide for a wide range of ITU-T Recommendation H.248 extension packages. Many standards bodies have defined profiles of extension packages that define the activation of sets of feature packages. These profiles are defined here. Activation of a given H.248 profile results in the activation deactivation of corresponding feature packages.


5 Interface Functions


5.1 Send()

NAME

Send – send a gateway control message.

SYNOPSIS
#include <xom..h>
#include <xgcp.h>

GCP_status gcp_send(
        OM_private_object   session,
        OM_private_object   context,
        OM_object           argument,
        OM_private_object   *result_return,
        OM_sint32           *message_id-return
);
DESCRIPTION

This function is used to send a gateway control message when Automatic Message Handling is disabled on a session.

ARGUMENTS
Session (Object(Session))

The gateway control session on which to send the message. This must be a private object previously returned from Bind() or Open().

Context (Object(Context))

The gateway control context to be used for this operation. This argument must be a private object or the constant Default-Context (‘GCP_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(Message))

The information supplied as the argument of a gateway control message is an instance of a subclass of the OM class Message. Normally, concrete subclasses of this class are defined in Gateway Control Services packages. For example, the H248-Message subclass of Message is defined in the H.248 Services package is defined in the H.248 Services package (see H.248 Package) and may be used as an argument to this function.

RESULTS
Status (Status)

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

Result (Object(*))

Upon successful completion of a syncrhonous call, 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 (‘GCP_ABSENT_OBJECT’) is returned as the result.
  • When a confirmed mode service is requested, this is indicated by an instance of the OM class Message-Result or Message-Error, or when multiple replies are provided, an instance of OM class Multiple-Reply, which contains a set of instances of the OM class Message-Linked-Reply. Each Message-Linked-Reply contains exactly one of the following OM attributes:
    • — message-Result
    • — message-Error
    • — processing-Failure
Message-ID (Integer)

The Message-Id of the initiated gateway control message 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, [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION], [GCP_INSUFFICIENT_RESOURCES].

SEE ALSO

Abandon(),11 Response().

CORESPONDENCE

This function corresponds to the H248Message of ITU-T Recommendation H.248.1.


5.2 Abandon()

NAME

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

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_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 Gateway Control 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 gateway control service operations that may or may not be abandoned.

This function can only be called in synchronous mode.

ARGUMENTS
Session (Object(Session))

The gateway control session in which the confirmed operation was requested. This must be a private object previously returned from Bind().12

Dialog-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 Dialog-ID must be that which was returned by the function call that initiated the asynchronous gateway control 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 [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] and [GCP_INSUFFICIENT_RESOURCE].


5.3 Abort()

NAME

Abort – Abort Association.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_abort(
        OM_private_object  session,
        OM_private_object  context,
        OM_object          argument
);
DESCRIPTION

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

This function is used to abort a gateway control 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 gateway control 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 [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] and [GCP_INSUFFICIENT_RESOURCES].

CORRESPONDENCE

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


5.4 Abort-req()

NAME

Abort-req — abort a gateway control association.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_abort_req(
        OM_private_object   session,
        OM_private_object   context,
        OM_object           response
);
DESCRIPTION

This function is used to abort a gateway control 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 gateway control 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].


5.5 Accept()

NAME

Accept — accept an indicated gateway control open operation.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_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 dialog handling functions: Open(), Accept(), Refuse(), Issue(), Close(), Abort(), Receive(), used to manage the MAP dialog when AAM is disabled on a session. When AAM is enabled on a session, this dialog 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 gateway control session against which this operation is to be performed. This must be a private object previously returned from Bind().13

Context (Object(Context))

The gateway control context to be used for this operation. This argument must be a private object or the constant Default-Context (‘GCP_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 Gateway Control Service provider at the time that this function returns. The underlying Gateway Control 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 [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] and [GCP_INSUFFICIENT_RESOURCES].

CORRESPONDENCE

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


5.6 Assoc-req()

NAME

Assoc-req — establish gateway control association.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_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 immediate establishment of a gateway control association when Automatic Association Management is not used. Note that association establishment performs end-to-end communication for all underlying transports, regardless of whether they are connection-oriented or connectionless. When the underlying transport is connectionless (such as UDP), the association establishment operation still includes the exchange of ServiceChange messages intended on initiating the association.

The service is defined as a confirmed service. A reply is expected.

This operation may be called in synchronous or asynchronous modes.

When Automatic Association Management is used for a gateway control session, this function is not used. See Open.

ARGUMENTS
Session (Object(Session))

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

Context (Object(Context))

The gateway control 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 Gateway Control 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 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 [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] or [GCP_INSUFFICIENT_RESOURCES].

SEE ALSO

Assoc-rsp().15


5.7 Assoc-rsp()

NAME

Assoc-rsp — reply to a requested association operation.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_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 synchronous mode.

ARGUMENTS
Session (Object(Session))

The gateway control session against which this operation is performed. This must be a private object previously returned from Bind().16

Context (Object(Context))

The gateway control context to be used for this operation. This must be a private object or the constant Default-Context (‘GCP_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().17


5.8 Bind()

NAME

Bind — open a gateway control session.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_bind(
        OM_object           session,
        OM_workspace        workspace,
        OM_private_object  *bound_session_return
);
DESCRIPTION

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

If the OM attribute requester-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 requester-Title.

To allow for the implementation of Automatic Association Management, it is undefined as to whether Bind() causes any communication with the remote gateway control 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 (‘GCP_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)

Specifies the workspace (obtained from a call to Initialize()) which is to be associated with the session. All function results from gateway control 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.

Whether the resulting session uses Automatic Association Management (AAM) or not depends upon the negotiation of this feature (using the Netogiate() interface function) for the workspace supplied as an argument.

RESULTS
Status (Status)

Indicates whether or not the function completed successfully.

Bound-Session (Object(Session))

Upon successful completion, contains an instance of a gateway control 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 (‘GCP_NO_VALID_FILE_DESCRIPTOR’) if the functionality is not supported).

When Automatic Association Management (AAM) is disabled for the Workspace 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 Gateway Control 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 [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] and [GCP_INSUFFICIENT_RESOURCES].

SEE ALSO

Unbind(),18 Negotiate().19


5.9 Close()

NAME

Close — terminate a gateway control association.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_close(
        OM_private_object       session,
        OM_private_object       context,
        OM_object               argument
);
DESCRIPTION

This function is used to request the termination of a gateway control 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 Automatic Association Management (AAM) disabled, and it must be in a connected state.

Context (Object(Context))

The gateway control 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 [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] and [GCP_INSUFFICIENT_RESOURCES].

SEE ALSO

Abort().20

CORRESPONDENCE

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


5.10 Error-Message()

NAME

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

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

OM_sint gcp_error_message(
        GCP_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).


5.11 Get-Assoc-Info()

NAME

Get-Assoc-Info — retrieve negotiated association values.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_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        *gcp_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 Message Handling enabled or disabled. In any case, the values returned are those associated with the underlying association within which the incoming Result-Or-Argument arrived. In connectionless environments, the values returned are those associated with the incoming Result-Or-Argument object (for example, Responder-Address).

Certain requested 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:

  • GCP_T_PRESENTATION_CONTEXT_LIST

Otherwise, [GCP_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:

  • GCP_T_RESPONDER_ADDRESS
  • GCP_T_RESPONDER_TITLE
  • GCP_T_APPLICATION_CONTEXT

Otherwise, [GCP_ABSENT_OBJECT] is returned for this object.

Gcp-Assoc-Args (Object(Gcp-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:

  • GCP_T_APPLICATION_CONTEXT_LIST
  • GCP_T_VERSION_LIST

otherwise, [GCP_ABSENT_OBJECT] is returned for this object.

ERRORS

This function can return error constants [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] or [GCP_INSUFFICIENT_RESOURCES].


5.12 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 <xgcp.h>

GCP_status gcp_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:

  • [GCP_E_COMMUNICATIONS_PROBLEM]
  • [GCP_E_BROKEN_SESSION]
  • [GCP_E_INVALID_CONNECTION_ID]
  • [GCP_E_SYSTEM]

The returned integer value is implementation dependent.

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

For most XGCP 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 [GCP_NO_WORKSPACE] or [GCP_INVALID_SESSION].


5.13 Initialize()

NAME

Initialize — initialize the interface.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

OM_workspace gcp_initialize(
        void
);
DESCRIPTION

This function performs any necessary initialization of the interface and allocates a workspace. It must be called before any other gateway control 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 gateway control interface functions. This function returns NULL if it fails.

ERRORS

None.

SEE ALSO

Shutdown().21

EXAMPLE

OM_workspace workspace;

if ((workspace = gcp_initialize()) == NULL) {
	exit(1);
}

5.14 Issue()

NAME

Issue — issue pending service requests and responses.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_issue(
        OM_private_object       session,
        OM_private_object       context,
        OM_sint32               dialog_id
);
DESCRIPTION

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

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

When an Open(), Accept() or Refuse() function is called, the underlying Gateway Control Service provider might not issue the corresponding MGCP, MEGACO or H.248 transactions immediately, but may wait for the accumulation of gateway control service requests or responses to combine with the dialog. The Issue() function tells the underlying Gateway Control Service provider to release pending dialog handling primitives with the service requests and responses currently accumulated.

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

  1. Bind() — bind the session.
  2. Open() — open the dialog.
  3. Service-req() — generate one or more service requests.
  4. Issue() – issue pending dialog handing and accumulated service requests or responses.
  5. Service-req() — generate one or more service requests.
  6. Close() — close the dialog (also issuing any pending dialog handling and accumulated service requests or responses).

Note that MGCP only permits one transaction (and, therefore, one service request or response) per message. MEGACO and H.248 support multiple transactions per message, and multiple service requests or responses per transaction.

ARGUMENTS
Session (Object(Session))

The gateway control session against which this operation is to be performed. This must be a private object previously returned from Bind().22

Context (Object(Context))

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

Dialog-ID (Integer)

The Dialog-ID of the requested dialog on which to issue accumulated service requests and responses. This Dialog-ID must have been returned from a call to Open()23 or Receive()24 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 [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] and [GCP_INSUFFICIENT_RESOURCES].

CORRESPONDENCE

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


5.15 Negotiate()

NAME

Negotiate — negotiate features of the interface and service.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_negotiate(
        GCP_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 gateway control 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 GCP_feature, which is defined as:

#define GCP_ACTIVATE            0
#define GCP_DEACTIVATE          1
#define GCP_QUERY_STATE         2
#define GCP_QUERY_SUPPORTED     3

typedef struct {
        OM_object_identifier    feature;
        OM_sint                 request;
        OM_boolean              response;
} GCP_feature;

The following Features are defined and registered by this specification:

  • Gateway Control Packages
    The GSM Gateway Control package and the ANSI Gateway Control package are specified in Interface Class Definitions. Additional Gateway Control packages may be specified in the future. Note that multiple Gateway Control Packages can be activated within the same workspace.
  • Automatic Association Management
    This feature provides for automatic establishment and release of the underlying protocol associations.25 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) xgcp(2) common(1) automatic-association-management(1) }’. This Object-Identifier is represented by the constant
    GCP_AUTOMATIC_ASSOCIATION_MANAGEMENT’.

    Automatic Association Management is enabled by default.

  • Automatic Message Handling
    This feature provides for automatic establishment and release of the underlying protocol messages.26 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) xgcp(2) common(1) automatic-message-handling(2) }’. This Object-Identifier is represented by the constant
    GCP_AUTOMATIC_DIALOG_HANDLING’.
  • Automatic Dialog Handling
    This feature provides for automatic establishment and release of the underlying protocol transaction.27 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) xgcp(2) common(1) automatic-transaction-handling(3) }’. This Object-Identifier is represented by the constant
    GCP_AUTOMATIC_TRANSACTION_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.28 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) xgcp(2) common(1) automatic-decoding(4) }’. This Object-Identifier is represented by the constant
    GCP_AUTOMATIC_DECODING’.

    Automatic ASN.1 BER Encoding and Decoding is enabled by default.

Gateway Control Services packages are also negotiated as part of the Feature-List. Gateway Control 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:

RequestResponseMeaning
ActivateTrueActivated
FalseCannot activate feature (or the feature is not supported).
DeactivateTrueDeactivated
FalseCannot deactivte feature (or the feature is not supported).
Query-stateTrueActivated
FalseDeactivated (or the feature is not supported).
Query-supportedTrueSupported
FalseNot supported
InvalidTrueCannot be returned
FalseInvalid argument

In the C binding, this result is combined with the Feature-List argument as a single array of structures of type GCP_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 gateway control errors.

The function can also return the error constants [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] and [GCP_INSUFFICIENT_RESOURCE].

EXAMPLE

GCP_status status;
OM_workspace workspace;
int i;

workspace = gcp_initialize();

GCP_feature feature_list[] = {
	{GCP_COMMON_PKG, GCP_ACTIVATE, 0}
	, {GCP_GSM_PKG, GCP_ACTIVATE, 0}
	, {GCP_GSM_SM_PKG, GCP_ACTIVATE, 0}
	, {GCP_GSM_LS_PKG, GCP_ACTIVATE, 0}
	, {GCP_GSM_IN_PKG, GCP_ACTIVATE, 0}
	, {GCP_GSM_CH_PKG, GCP_ACTIVATE, 0}
	, {NULL, 0, 0}
};

if ((status = gcp_negotiate(feature_list, workspace)) != GCP_SUCCESS)
	exit(1);

for (i = 0; i < 6; i++)
	if (!feature_list[i].response)
		exit(1);

5.16 Open()

NAME

Open – Request establishment of a Gateway Control Services dialog.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_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 gateway control entity association dialog. 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 other asynchronous calls.

ARGUMENTS
Session (Object(Session))

The gateway control session against which this operation is performed. This must be a private object previously returned from Bind().29 This session must also have ADH30 disabled.

Context (Object(Context))

The gateway control 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 synchronously, 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 transaction has been fully formed. The Accept-Result object also contains the final negotiated transaction parameters for the new transaction.
  • 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 transaction was refused. No session attribute is present in this result and no transaction 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 transaction session is formed.

Upon successful completion of an asynchronous call, a partially formed transaction 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 gateway control 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 [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] and [GCP_INSUFFICIENT_RESOURCES].

SEE ALSO

Abort(),31 Assoc-rsp(), Accept(),32 Refuse().33

CORRESPONDENCE

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


5.17 Receive()

NAME

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

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_receive(
        OM_private_object   session,
        OM_sint            *mode_return,
        OM_sint            *primitive_return,
        OM_sint            *completion_flag_return,
        GCP_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 gateway control operation is performed. This must be a private object previously returned from Bind(),34 or a connected or partially connected session object returned from Open(),35 Accept(),36 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 (‘GCP_SUCCESS’) if this function returned successfuly.

Primitive (Integer)

The gateway control service primitives (‘GCP_SERVICE_IND’, ‘GCP_SERVICE_CNF’).

The GCP association service primitives (‘GCP_OPEN_IND’, ‘GCP_ACCEPT_CNF’, ‘GCP_REFUSE_CNF’, ‘GCP_DELIM_IND’, ‘GCP_CLOSE_IND’, ‘GCP_ABORT_IND’, ‘GCP_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 (‘GCP_T_CONFIRMED’) the invoked operation has to be confirmed, a reply is expected. When non-confirmed (‘GCP_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

(‘GCP_COMPLETED’)
This flag indicates that a final response has been received. For gateway control 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

(‘GCP_INCOMING’)
An indication has been received.

nothing

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

outstanding

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

parial

(‘GCP_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:

Completedyes(1)noyesyes(1)yes
Incomingyesyesnoyesyes
Nothingnonononono
Outstandingnonononono
Partial(3)yes(1)noyesyes(1)yes
Operation-Status (Status)

Takes an error value if a communications error occurred during the execution of the asynchronous operation, and success (‘GCP_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-ResultGCP_SERVICE_CNF
Service-ErrorGCP_SERVICE_CNF
Service-RejectGCP_SERVICE_CNF
Accept-ResultGCP_ACCEPT_CNF
Refuse-ResultGCP_REFUSE_CNF
Absent-ObjectAll 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-ArgumentGCP_SERVICE_IND
Open-ArgumentGCP_OPEN_IND
Close-ArgumentGCP_CLOSE_IND
Abort-ArgumentGCP_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 Dialog-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 [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] and [GCP_INSUFFICIENT_RESOURCES].


5.18 Refuse()

NAME

Refuse – refuse an indicated association operation.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_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 dialog handling functions: Open(), Accept(), Refuse(), Issue(), Close(), Abort(), Receive(), used to manage the GCP dialog when AAM is disabled on a session. When AAM is enabled on a session, this dialog 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 gateway control session against which this operation is to be performed. This must be a private object previously returned from Bind().37

Context (Object(Context))

The gateway control context to be used for this operation. This argument must be a private object or the constant Default-Context (‘GCP_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 [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] and [GCP_INSUFFICIENT_RESOURCES].

CORRESPONDENCE

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


5.19 Release-req()

NAME

Release-req

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_release_req(
);
DESCRIPTION
ARGUMENTS
RESULTS
ERRORS

5.20 Release-rsp()

NAME

Release-rsp

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_release_rsp(
);
DESCRIPTION
ARGUMENTS
RESULTS
ERRORS

5.21 Service-req()

NAME

Service-req — request gateway control service.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_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 gateway control service.

ARGUMENTS
Session (Object(Session))

The gateway control session against which this operation is performed. This must be a private object previously returned from Bind().

Context (Object(Context))

The gateway control context to be used for this operation. This argument must be a private object or the constant Default-Context (‘GCP_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 gateway control service request is an instance of a subclass of the OM class Service-Argument. Normally, concrete subclasses of this class are defined in Gateway Control Services packages.

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 synchronous call, 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 (‘GCP_ABSENT_OBJECT’) is returned as the result.
  • When a confirmed mode services is requested, this is indicated by an 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
Dialog-ID (Integer)

The Dialog-ID of the initiated gateway control 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 [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] or [GCP_INSUFFICIENT_RESOURCES].

SEE ALSO

Abandon(),38 Service-rsp().39

CORRESPONDENCE

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


5.22 Service-rsp()

NAME

Service-rsp — reply to a requested gateway control service operation.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_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 gateway control service operation. This function can only be called in synchronous mode.

ARGUMENTS
Session (Object(Session))

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

Context (Object(Context))

The gateway control context to be used for this operation. This argument must be a private object or the constant Default-Context (‘GCP_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 (‘GCP_ABSENT_OBJECT’).

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

Dialog-ID (Integer)

The Dialog-ID of the requested operation to which the reply applies. This is the Dialog-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 [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] or [GCP_INSUFFICIENT_RESOURCES].

SEE ALSO

Receive(),40 Service-req().41

CORRESPONDENCE

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


5.23 Service-parameter()

NAME

Service-parameter

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_xxx(
);
DESCRIPTION
ARGUMENTS
RESULTS
ERRORS
CORRESPONDENCE

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


5.24 Shutdown()

NAME

Shutdown — delete a workspace and the associated resources.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_shutdown(
        OM_workspace    workspace
);
DESCRIPTION

This function deletes a workspace established by Initialize()42 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 [GCP_NO_WORKSPACE] or [GCP_INSUFFICIENT_RESOURCES].

SEE ALSO

Initialize().43

EXAMPLE

OM_workspace workspace;
GCP_status status;

if ((workspace = gcp_initialize()) == NULL)
	exit(1);

/* perform functions within the workspace */

if ((status = gcp_shutdown(workspace)) != GCP_SUCCESS)
	exit(1);
exit(0);

5.25 Transaction-pnd()

NAME

Transaction-pnd — notify of a pending requested gateway control transaction.

SYNOPSIS
DESCRIPTION
ARGUMENTS
RESULTS
ERRORS

5.26 Transaction-req()

NAME

Transaction-req — request a gateway control transaction.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_transaction_req(
        OM_private_object   session,
        OM_private_object   context,
        OM_object           argument,
        OM_private_object   *result_return,
        OM_sint32           *transaction_id-return
);
DESCRIPTION

This function is sued to request a gateway control transaction.

ARGUMENTS
Session (Object(Session))

The gateway control session against which this transaction is issued. This must be a private object previously returned from Bind().

Context (Object(Context))

The gateway control context to be used for this transaction (not to be confused with a “Context” in the MEGACO/H.248 protocol). This argument must be a private object or the constant Default-Context (‘GCP_DEFAULT_CONTEXT’).

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

Argument (Object(Transaction-Request))

The information supplied as the argument of a gateway control transaction request is an instance of a subclass of the OM class Transaction-Request. Normally, concrete subclasses of this class are defined in Gateway Control packages. For example, the H248-Transaction-Request subclass of Transaction-Request is defined in the H.248 package (see H248-Transaction-Request) 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 synchronous call, when the transaction was requested in a confirmed mode, the result is one of the following:

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

5.27 Transaction-rsp()

NAME

Transaction-rsp — reply to a requested gateway control transaction.

SYNOPSIS
DESCRIPTION
ARGUMENTS
RESULTS
ERRORS

5.28 Unbind()

NAME

Unbind — unbind from a gateway control session.

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_unbind(
        OM_private_object   session
);
DESCRIPTION

This function terminates the given gateway control 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 initiated using 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() possibly 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 a terminated session.

ARGUMENTS
Session (Object(Session))

The gateway control 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 (‘GCP_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 gateway control errors.

This function can return the error constants [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] or [GCP_INSUFFICIENT_RESOURCES].

SEE ALSO

Bind().44


5.29 Validate-object()

NAME

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

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_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 XGCP function calls. It may also be used after XGCP function calls that return [GCP_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 [GCP_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 [GCP_E_BAD_ARGUMENT] indicates a validation failure and problem details are in the Bad-Argument parameter.

Bad-Argument (Object(Bad-Argument))

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

ERRORS

This function can return the error constants [GCP_NO_WORKSPACE], [GCP_INSUFFICIENT_RESOURCES], [GCP_E_SYSTEM] or [GCP_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, GCP_C_MO_FORWARD_SM_ARG)
    , {GCP_SM_RP_DA, OM_S_OBJECT, {
        OM_OID_DESC(OM_CLASS, GCP_C_SM_RP_DA)
        , {GCP_IMSI, GCP_S_TBCD_STRING, OM_STRING("\x21\x43\x65\x87")}
        , OM_NULL_DESCRIPTOR
      } }
    , {GCP_SM_RP_OA, OM_S_OBJECT, {
        OM_OID_DESC(OM_CLASS, GCP_C_SM_RP_OA)
        , {GCP_NO_SM_RP_OA, OM_S_NULL, NULL}
        , OM_NULL_DESCRIPTOR
      } }
    , {GCP_SM_RP_UI, OM_S_OCTET_STRING, (OM_string) {data_length, data_pointer} }
    , {GCP_IMSI, GCP_S_TBCD_STRING, OM_STRING("\x21\x43\x65\x87")}
    , OM_NULL_DESCRIPTOR
};
GCP_status status;
OM_private_object bad_argument;

status = gcp_validate_object(workspace, argument, &bad_argument);

if (status == GCP_E_BAD_ARGUMENT)
    exit(1);

5.30 Wait()

NAME

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

SYNOPSIS
#include <xom.h>
#include <xgcp.h>

GCP_status gcp_wait(
        GCP_waiting_sessions    bound_session_list[],
        OM_workspace            workspace,
        OM_uint32               timeout
);
DESCRIPTION

This function is used to suspend the caller until a gateway control 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 gateway control 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 GCP_status object will be created if the return status is other than [GCP_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 GCP_waiting_sessions, which is defined as:

typedef struct {
        OM_private_object   bound_session;
        OM_boolean          activated;
} GCP_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 [GCP_NO_WORKSPACE], [GCP_INVALID_SESSION] and [GCP_INSUFFICIENT_RESOURCE].

SEE ALSO

Initialize(),45 Receive(),46 Bind().47

EXAMPLE

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


GCP_waiting_sessions bound_session_list[] =
    { {session, OM_FALSE} , {NULL,} };

for (;;) {
    if ((status = gcp_wait(bound_session_list, workspace, 0)) != GCP_SUCCESS)
        exit(1);
    if (bound_session_list[0].activated) {
        OM_sint mode;
        OM_sint primitive;
        OM_sint completion_flag;
        GCP_status operation_status;
        OM_private_object result;
        OM_sint32 received_invoke_id;

        if ((status = gcp_receive(session, &mode, &primitive, &operation_status,
                            &result, &received_invoke_id)) != GCP_SUCCESS)
                exit(1);
        /* process received result */
        om_delete(result);
    }
}

6 Interface Class Definitions

This chapter defines, in alphabetical order, the OM classes that constitute the Common GCP package (COMMON), the MGCP package (MGCP), the MEGACO package (MEGACO), and the H.248 package (H248). The common errors are defined in the Common GCP package, while the variant specific errors are defined in the MGCP, MEGACO and H.248 packages.

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

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

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

The Object-Identifier associated with the MGCP package is:

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

This Object-Identifier is represented by the constant MGCP-Package (‘GCP_MGCP_PKG’).

The Object-Identifier associated with the MEGACO package is:

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

This Object-Identifier is represented by the constant MEGACO-Package (‘GCP_MEGACO_PKG’).

The Object-Identifier associated with the H.248 package is:

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

This Object-Identifier is represented by the constant H248-Package (‘GCP_H248_PKG’).

The XGCP API may also make use of Gateway Control Services packages. These optional packages define OM classes that are additional to those in the Gateway Control 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.


6.1 Global Call 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 SCTP-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).

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

6.1.1 Interface Common Objects

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

6.1.2 Interface Common Error Definitions

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

6.1.3 MGCP Package Objects

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

6.1.4 MEGACO Package Objects

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

6.1.5 H248 Package Objects

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

6.2 Common GCP Package

The Common GCP 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.


6.2.1 Basic GCP Types


6.2.1.1 Auth-Data

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

auth-Data

A String(Octet) of 12 to 32 octets in length.


6.2.1.2 Authentication-Header

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

sec-Parm-Index

A Security-Parm-Index object.

seg-Num

A Sequence-Num object.

ad

A Auth-Data object.


6.2.1.3 Context-ID

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

context-ID

An integer value between 0 and 4294967295 (inclusive). The following values are significant:

0

The NULL context value.

0xFFFFFFFE

The CHOOSE context value.

0xFFFFFFFF

The ALL context value.


6.2.1.4 Domain-Name

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

name

An IA5 string containing a properly formated domain name.

port-Number

A optional Port-Number object.


6.2.1.5 Error-Code

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

error-Code

An integer value between 0 and 65535 inclusive.


6.2.1.6 Error-Text

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

error-Text

An IA5 string containing the human readable error text.


6.2.1.7 IP4-Address

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

address

A 4-octet octet string containing the IP version 4 address.

port-Number

An optional Port-Number object.


6.2.1.8 IP6-Address

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

address

A 16-octet octet string containing the IP version 6 address.

port-Number

An optional Port-Number object.


6.2.1.9 Message-ID

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


6.2.1.10 MTP-Address

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


6.2.1.11 Path-Name

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

path-Name

An IA5 string between 1 and 64 octets long (inclusive).


6.2.1.12 Port-Number

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

port-Number

An integer between 0 and 65535, inclusive. The value zero (0) has special meaning.


6.2.1.13 Security-Parm-Index

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

security-Parm-Index

A 4-octet octet string.


6.2.1.14 Sequence-Num

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

sequence-Num

A 4-octet octet string.


6.2.2 Abort-Argument

An instance of abstract OM 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: MGCP-Abort-Argument, MEGACO-Abort-Argument and H248-Abort-Argument. An instance of this OM class has the OM attributes of its super-classes, Object and Error. It does not define any attributes of its own. Because abort causes are Gateway Control package specific, this abstract OM class does not define any of the values for the problem or parameter attributes of the Error super-class.


6.2.3 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: MGCP-Abort-Result, MEGACO-Abort-Result and H248-Abort-Result. An instance of this OM class has the OM attributes of its super-classes: Object and Error. It does not define any attributes of its own. Because abort result error codes are Gateway Control package specific, this abstract class does not define any of the problem or parameter syntaxes of the Error super-class.


6.2.4 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: MGCP-Accept-Result, MEGAGO-Accept-Result and H248-Accept-Result.

An instance of this OM class has the OM attributes of it super-classes, Object, and additionally the OM attributes listed in Table 39.

xgcp_tab039

Table 39. OM Attributes of OM class Accept-Result

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 future 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() interface function can be used to retrieve additional details concerning the association. See Get-Assoc-Info.


6.2.5 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 Automatic Association Management (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 super-classes, Object, and additionally the OM attributes listed in Table 31.

xgcp_tab031

Table 31. OM Attributes of OM class Acse-Args

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

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 gateway control 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 phased 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 gateway control association. When automatic dialog handling is enabled on the session, the application context will be selected by the Gateway Control Service provider consistent with the Gateway Control Service request or indication. Gateway Control Service packages define a set of security contexts that are applicable to the service package.

security-Context

The security context name proposed by the user to be used on the gateway control association. By default the security context is not present. Gateway Control Service packages define a set of security contexts that are applicable to the service package, defined as integers (Form 1 local values) or Object-Identifiers (Form 2 global values), for use as the value of this object. For example, for H.248 Version 3 there are four possibilities:

  • ESP header in accordance with Section 5 of RFC 2406, for IP version 6.
  • AH header in accordance with Section 5 of RFC 2402, for IP version 6.
  • ESP or AH header as above, but tunnelling IP version 6 over IP version 4, or vise verse.
  • The interim AH scheme described in ITU-T Recommendation H.248.1 (09/2005) Clause 10.2.
authentication-Information

Provides authentication information for use with the security context (if any).

Note that, although this OM attribute is named after ACSE (Association Control Service Execution), which is an OSI layer, none of MGCP, MEGACO nor H.248 provide an ACSE layer. Nevertheless, MGCP, MEGACO and ACSE support the concept of an association and requires equivalent arguments as would the OSI or SS7 ACSE layer.


6.2.6 Action

An instance of OM class Action represents an action, that is a sequence of commands, pending notifications or responses that are applied to a gateway control context. This OM class is an abstract class containing several defined subclasses: Action-Request and Action-Reply. An instance of this OM class has the OM attributes of its super-classes, Object, and additionally the OM attributes listed in Table 23.

xgcp_tab023

Table 23. OM Attributes of OM class Action

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

context

Provides the Gateway Control Service context, which is the context as defined by the Standards, rather than the Context supplied as an argument to most XGCP interface functions.


6.2.7 Action-Request

An instance of OM class Action-Request represents an action that is a sequence of commands that are applied to a gateway control context. This OM class is an abstract class containing several defined classes: MGCP-Action-Request, MEGACO-Action-Request and H248-Action-Request. An instance of this OM class has the OM attributes of its super-classes, Object and Action, and additionally the OM attributes listed in Table 24.

xgcp_tab024

Table 24. OM Attributes of OM class Action-Request

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

context-Id

A Context-ID object providing the MEGACO context identifier to which the commands in this action apply.

context-Request

An optional Context-Request object specifying some of the attributes requested to be assigned to a context or set of contexts.

context-Attr-Audit-Req

An optional Context-Attr-Audit-Req object that, when present, requests the audit of some of the characteristics associated with the context or a selected set of contexts.

command-Requests

One or more commands of OM class Command-Request or derived classes, that are applicable to the context of the action.


6.2.8 Context-Request

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

priority

An optional call priority.

emergency

An optional boolean value indicating an emergency call.

topology-Req

Zero or more Topology-Request objects describing the topology of the context.

ieps-Call-Ind

An optional boolean value indicating an IEPS call.

context-Prop

Zero or more Property-Parm object providing property parameters for the context.

context-List

Zero or more Context-ID objects representing a list of contexts.


6.2.9 Context-Attr-Audit-Request

An instance of OM class Context-Attr-Audit-Request represents a request to audit attributes of a context or set of contexts. This OM class contains the attributes of its super-classes, Object, plus the additional OM attributes listed in Table 67.

xgcp_tab067

Table 67. OM Attributes of OM class Context-Attr-Audit-Request

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

topology

An boolean value that, when TRUE, specifies that the topology of the context is requested.

emergency

An boolean value that, when TRUE, specifies that the emergency status of the context is requested.

priority

An boolean value that, when TRUE, specifies that the priority of the context is requested.

ieps-Call-Ind

An boolean value that, when TRUE, specifies that the IEPS call indicator of the context is requested.

context-Prop-Aud

Zero or more Ind-Aud-Property-Parm objects, each specifying that the context property is requested.

select-Priority

An optional Priority object that specifies which value of priority to audit.

select-Emergency

An optional Emergency object that specifies which emergency settings to audit.

select-Ieps-Call-Ind

An optional Ieps-Call-Ind object that specifies which IEPS call indicators to audit.

select-Logic

An enumerated value specifying what logical operation to perform across selections. The value can be one of the following:

and-audit-select

The audit selection items must all be met for the context to be selected for audit.

or-audit-select

Only one audit selection item must be met for the context to be selected for audit.

When not specified, the default is and-audit-select.


6.2.10 Action-Reply

An instance of OM class Action-Reply represents the response to an action that is a sequence of responses that result from commands applied to a gateway control context. This OM class is an abstract class containing several defined classes: MGCP-Action-Reply, MEGACO-Action-Reply and H248-Action-Reply. An instance of this OM class has the OM attributes of its super-classes, Object and Action, and additionally the OM attributes listed in Table 25.

xgcp_tab025

Table 25. OM Attributes of OM class Action-Reply

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

context-Id

An object of OM class Context-ID that specifies the primary context to which this action reply corresponds.

error-Descriptor

An optional object of OM class Error-Descriptor that is used to describe an error situation.

context-Reply

An optional object of OM class Context-Request that is used to return requested audit properties of the context.

command-Reply

One or more command replies of OM class Command-Reply or derived classes, that are applicable to the context of the action.


6.2.11 Address

An instance of OM class Address represents the address of a particular gateway control entity. It is used to define the specific location to contact a particular gateway control entity. An instance of this OM class has all of the attributes of its super-classes, Object, and additionally the OM attributes listed in Table 32.

xgcp_tab032

Table 32. OM Attributed of OM class Address

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

internet-Address

The address is represented using an octet string that contains the encoding of an IP version 4 or IP version 6 address with the following considerations:

  • The encoded address shall have both an IP address and port number.
  • The encoded address shall not have a host name in the address.
  • The encoded address will distinguish between IP version 4 format and IP version 6 format using the address family indicator.

6.2.12 Application-Context-List

An instance of OM class Application-Context-List represents a list of application context names. An instance of this OM class has the OM attributes of its super-classes, Object, and additionally the OM attributes listed in Table 35.

xgcp_tab035

Table 35. OM Attributes of OM class Application-Context-List

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 Gateway Control packages (e.g. the H.248 service package).


6.2.13 Assoc-Argument

An instance of OM class Assoc-Argument is the information supplied as an argument of an ACSE Association 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 super-classes, Object, and additionally the OM attributes listed in Table 27.

xgcp_tab027

Table 27. OM Attributes of OM class Assoc-Argument

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 Gateway Control Service provider will supply defaults if required. Presentation layer arguments are not required for MGCP. For MEGACO and H.248; however, the presentation layer arguments specify whether the ASN.1 BER binary encoding of ITU-T Recommendation H.248.1 (09/2005) Annex A or the text encoding of Annex B is used on the association.

acse-Args

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

gcp-Assoc-Args

Indicates GCP related arguments that will be used during association establishment. If none are supplied, the Gateway Control 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 Gateway Control 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.


6.2.14 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 super-classes, Object, and additionally the OM attributes listed in Table 28.

xgcp_tab028

Table 28. OM Attributes of OM class Assoc-Result

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 Gateway Control Service provider will supply defaults when required. Presentation layer arguments are not required for MGCP. For MEGACO and H.248; however, the presentation layer arguments specify whether the ASN.1 BER binary encoding of Annex B or the text encoding of Annex C is used on the association.

acse-Args

Indicates ACSE related arguments that will be used during association establishment. If none are supplied, the Gateway Control Service provider will supply defaults when required.

gcp-Assoc-Args

Indicates GCP related arguments that will be used during association establishment. If none are supplied, the Gateway Control Service provider will supply defaults when 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.


6.2.15 Close-Argument

An instance of abstract OM class Close-Argument represents the base information that is supplied as the Argument argument to the Close() interface 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: MGCP-Close-Argument, MEGACO-Close-Argument and H248-Close-Argument. An instance of this abstract OM class has the OM attributes of its super-classes, Object. It does not define any OM attributes of its own.


6.2.16 Command-Request

An instance of OM class Command-Request represents a command issued for gateway control. This OM class is an abstract class containing a number of defined classes: MGCP-Command-Request, MEGACO-Command-Request and H248-Command-Request. An instance of this OM class has the OM attributes of its super-classes, Object. This OM class does not have any defined class-specific attributes.

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

command
optional
wildcard-Return

6.2.17 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 super-classes, Object, and additionally the OM attributes listed in Table 37.

xgcp_tab037

Table 37. OM Attributes of OM class Context

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

6.2.18 Extension

An instance of OM class Extension represents 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 its super-classes, Object, and additionally the OM attributes listed in Table 38.

xgcp_tab038

Table 38. OM Attributes of OM class Extension

This OM class contains the following class-specific attributes:

extension

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


6.2.19 Generic-Service-Argument

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

An instance of this OM class has the attributes of its super-classes, Service-Request, and additionally the OM attributes listed in Table 41.

xgcp_tab041

Table 41. OM Attributes of OM class Generic-Service-Argument

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 an unconfirmed mode, no response is expected. This attribute determines which 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 object identifier. Whether an integer or object identifier is used depends upon the underlying ROSE/TCAP provider and may differ depending on the Gateway Control package in use.

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.


6.2.20 Generic-Service-Result

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

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

xgcp_tab042

Table 42. OM Attributes of OM class Generic-Service-Result

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 Gateway Control package in use.

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.


6.2.21 Gcp-Assoc-Args

An instance of OM class Gcp-Assoc-Args represents the GCP 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 super-classes, Object, and additionally the OM attributes listed in Table 34.

xgcp_tab034

Table 34. OM Attributes of OM class Gcp-Assoc-Args

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

application-Context-List
version-List

6.2.22 Notice-Result

An instance of abstract 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: MGCP-Notice-Result, MEGACO-Notice-Result and H248-Notice-Result. An instance of this OM class has the OM attributes of its super-classes, Object. It does not define any OM attributes of its own.


6.2.23 Message

An instance of OM class Message represents the base information that is supplied as an argument to the Send() function (see Send) or is returned by the Receive function (see Receive) when Automatic Message Handling is disabled on a Session.

This OM class is an abstract class containing several defined subclasses: MGCP-Message, MEGACO-Message and H248-Message.

An instance of this OM class has the OM attributes of its super-classes, Object, and additionally the OM attributes listed in Table 21.

xgcp_tab021

Table 21. OM Attributes of OM class Message

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

message-ID
transactions

One ore more transactions of OM class Transaction or derived classes.


6.2.24 Open-Argument

An instance of abstract 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: MGCP-Open-Argument, MEGACO-Open-Argument and H248-Open-Argument. An instance of this OM class has the OM attributes of its super-classes, Object, and additionally the OM attributes listed in Table 40.

xgcp_tab040

Table 40. OM Attributes of OM abstract class Open-Argument

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

responder-Address

Specifies the responder address (the address of the remote gateway control entity) for a bound session object with Automatic Association Management (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 Gateway Control Service 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 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 Gateway Control Service provider will not include a requesting title.

session

Used 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 Gateway Control Service provider upon return from that call. The partially formed dialog session can either be aborted with a call to Abort() (see Abort), or can become a fully formed dialog session with a call to Accept() (see 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.


6.2.25 Operation-Argument


6.2.26 Operation-Error


6.2.27 Operation-Reject


6.2.28 Operation-Result


6.2.29 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: MGCP-P-Abort-Result, MEGACO-P-Abort-Result and H248-Abort-Result. An instance of this OM class has the OM attributes of its super-classes, Object and Error. It does not defined any OM attributes of its own.


6.2.30 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 super-classes, Object, and additionally the OM attributes listed in Table 30.

xgcp_tab030

Table 30. OM Attributes of OM class Presentation-Context

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 Gateway Control package.

MGCP only supports a single presentation context: text encoding, and in the case of MGCP, no presentation-Abstract need be specified. The MGCP services package does, however, define an Object-Identifier used to specify the default text encoding. MEGACO/H.248 (all versions), on the other hand, supports both ITU-T Recommendation H.248.1 (09/2005) Annex A binary encoding (ASN.1 BER), as well as text encoding. The MEGACO/H.248 services packages specify the Object-Identifiers to use with the presentation-Abstract OM attribute.


6.2.31 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 super-classes, Object, and additionally the OM attributes listed in Table 29.

xgcp_tab029

Table 29. OM Attributes of OM class Presentation-Layer-Args

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

presentation-Context-List

The list of presentation contexts.

MGCP only supports a single presentation context: text encoding, and in the case of MGCP, no presentation-Layer-Args need be specified. On the other hand, MEGACO and H.248 (all versions) may support ITU-T Recommendation H.248.1 (09/2005) Annex A binary encoding (ASN.1 BER), or Annex B text encoding, or both.

When used on an “invoker-role” session (MGC) and the transport address port number is not specified in the requester-Address or requester-Title, the presentation-Context-List specifies which well-known ports on which the invoker will listen for remote Gateway Control Service indications. There are two well-known ports defined: one for binary encoding and another for text encoding.


6.2.32 Refuse-Result

An instance of abstract 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: MGCP-Refuse-Result, MEGACO-Refuse-Result and H248-Refuse-Result. An instance of this OM class has the OM attributes of its super-classes, Object. It does not define any OM attributes of its own.


6.2.33 Release-Argument


6.2.34 Release-Result


6.2.35 Command-Reply

An instance of OM class Command-Reply represents the response to a gateway control command. This OM class is an abstract class containing a number of defined classes: MGCP-Command-Reply, MEGACO-Command-Reply and H248-Command-Reply. An instance of this OM class has the OM attribuges of its super-classes, Object. This OM class does not have any defined class-specific attributes.


6.2.36 Service-Argument

An instance of abstract 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: MGCP-Service-Argument, MEGACO-Service-Argument and H248-Service-Argument. An instance of this OM class has the OM attributes of its super-classes, Object, and additionally the OM attributes listed in Table 43.

xgcp_tab043

Table 43. OM Attributes of OM Class Service-Argument

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

responder-Address
responder-Title
requesting-Address
requesting-Title

6.2.37 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: MGCP-Service-Error, MEGACO-Service-Error and H248-Service-Error. An instance of this OM class has the OM attributes of its super-classes, Object and Error. As the problem values and parameter syntaxes are Gateway Control package specific, this OM class defines no attributes or error values of its own.


6.2.38 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: MGCP-Service-Reject, MEGACO-Service-Reject and H248-Service-Reject. An instance of this OM class has the OM attributes of its super-classes, Object and Error. As the problem values and parameter syntaxes are Gateway Control package specific, this OM class defines no attributes or error values of its own.

Note that when Automatic Association Management (AAM) or Automatic Dialog Handling (ADH) are enabled on a session 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 disabled) 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 super-class 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 super-class may also contain any of the error values defined for the corresponding Refuse-Result or Abort-Result subclasses.


6.2.39 Service-Result

An instance of abstract 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 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: MGCP-Service-Result, MEGACO-Service-Result and H248-Service-Result. An instance of this OM class has the OM attributes of its super-classes, Object. As the error codes are Gateway Control package specific, this OM class defines not attributes of its own.


6.2.40 Session

An instance of OM class Session identifies a particular communications link from the application program to the Gateway Control Service provider or to a remote gateway control entity depending upon the state of the session object. Session objects can be created with Automatic Association Management (AAM) enabled or disabled. If AAM is enabled, then all of the ACSE connection management, needed to deliver a gateway control service operation, is done by the Gateway Control Service provider. If AAM is disabled, the ACSE connection management is done by the user before issuing or receiving Gateway Control Service operations. The use and rules for the session object are different depending upon whether AAM is enabled or disabled. AAM is specified as part of Negotiate().48 An instance of this OM class has the OM attributes of its super-classes, Object, and additionally the OM attributes listed in Table 36.

xgcp_tab036

Table 36. OM Attributes of OM class Session

For a description of the three types of Session object: AAM Enabled Session, AAM Disabled Session, and Connected Session, see Session. The OM attributes of a Session are:

requester-Address

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

requester-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 registered name (instance of OM class Form2) which is used in the 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 requesting program.

role

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

performer-role

(‘GCP_T_PERFORMER_ROLE’) Responder and performer of gateway control service operations. Unless this role is set or implied, no indications will be returned by calls to Receive() (only confirmations and notifications) and the Gateway Control Service provider does not need to provide indications to the bound session user. In the terms of the Standards, the performer role is that of the Media Gateway (MG).

invoker-role

(‘GCP_T_INVOKER_ROLE’) Requester and invoker of gateway control service operations. If performer-role is set and invoker-role is clear, the Gateway Control Service provider does not need to honor operation or service requests (other than Notify-Request) from the bound session user. In terms of the Standards, the invoker role is that of the Media Gateway Controller (MGC).

When both role flags are clear, or this attribute is not present in the session, the Gateway Control Service provider will still honor operation and service requests. Implementations of this interface are not required to permit the performer and invoker roles simultaneously.

file-Descriptor

Indicates the file descriptor associated with the session. The file descriptor may be used by implementations 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 suspension facilities, or if the session is not started, the value is No-Valid-File-Descriptor (‘-1’ or ‘GCP_NO_VALID_FILE_DESCRIPTOR’).

presentation-Layer-Args

Indicates any presentation layer arguments needed during association establishment. If none are supplied, the Gateway Control Service providers will supply defaults when required.

When the session supports the invoker-role, the presentation-Layer-Args specifies which encodings the invoker supports, and determines which well-known port numbers upon which the invoker will listen for association indications.

acse-Args

Indicates the ACSE related arguments that will be used during association establishment. If none are supplied, the Gateway Control Service provider will supply defaults when required.

gcp-Assoc-Args

Indicates the GCP association related arguments that will be used during association establishment. If none are supplied, the Gateway Control Services provider will supply defaults when required.


6.2.41 Title

An instance of OM class Title represents the title of a particular gateway control service entity. It contains various subclass types used to define the specific gateway control process or system name responsible for a gateway control service entity. An instances of this OM class has all of the attributes of its super-classes, Object, and additionally the OM attributes listed in Table 33.

xgcp_tab033

Table 33. OM Attributes of OM class Title

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

internet-Address

The title is represented using an octet string that contains the encoding of an internet address, either IP version 4 or IP version 6 address with the following considerations:

  • The encoded address may have either an IP address or a port number, or both, in the address.
  • The encoded address shall have a host name in the address (the host name indicated shall not be null).
  • The encoded address will distinguish between IP version 4 format and IP version 6 format using the address family indicator.

6.2.42 Transaction

An instance of OM class Transaction represents the base information that is supplied as an argument to the Request(), Pending() or Response() functions, or is returned by the Receive() function (see ‘Receive()’) when Automatic Message Handling is enabled on a Session.

This OM class is an abstract class containing several defined subclasses: Transaction-Request, Transaction-Pending and Transaction-Response.

An instance of this OM class has the OM attributes of its super-classes, Object, and additionally the OM attributes listed in Table 22.

xgcp_tab022

Table 22. OM Attributes of OM class Transaction

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

transaction-Id
context-ID

6.2.43 Transaction-Request

An instance of OM class Transaction-Request represents the base information that is supplied as an argument to the Request() function (see ‘Request’) or is returned by the Receive() function (see Receive) for a transaction indication. This OM class is an abstract class containing several defined subclasses: MGCP-Transaction-Request, MEGACO-Transaction-Request and H248-Transaction-Request. An instance of this OM class has the OM attributes of its super-classes, Object and Transaction, and additionally the OM attributes listed in Table 20.

xgcp_tab020

Table 20. OM Attributes of OM class Transaction-Request

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

requests

One or more requests of OM class Action-Request or derived classes.


6.2.44 Transaction-Response

An instance of OM class Transaction-Response represents the base information that is supplied as an argument to the Response() function (see ‘Response’) or is returned by the Receive() function (see Receive) for a transaction confirmation. This OM class is an abstract class containing several defined subclasses: MGCP-Transaction-Response, MEGACO-Transaction-Response and H248-Transaction-Response. An instance of this OM class has the OM attributes of its super-classes, Object and Transaction, and additionally the OM attributes listed in Table 26.

xgcp_tab026

Table 26. OM Attributes of OM class Transaction-Response

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

responses

One or more responses of OM class Action-Reply or derived classes.


6.2.45 Transaction-Pending

An instance of OM class Transaction-Pending represents the base information that is supplied as an argument to the Pending() function (see ‘Pending()’) or is returned by the Receive() function (see ‘Receive()’) for a transaction indication. This OM class is an abstract class containing several defined subclasses: MGCP-Transaction-Pending, MEGACO-Transaction-Pending and H248-Transaction-Pending. An instance of this OM class has the OM attributes of its super-classes, Object and Transaction. This OM class does not have any defined class-specific OM attributes.


6.2.46 Version-List


6.2.47 Common GCP Data Objects


6.2.47.1 Audit-Descriptor


6.2.47.2 Digit-Map-Descriptor


6.2.47.3 Error-Descriptor


6.2.47.4 Event-Buffer-Descriptor


6.2.47.5 Events-Descriptor


6.2.47.6 Media-Descriptor


6.2.47.7 Modem-Descriptor


6.2.47.8 Mux-Descriptor


6.2.47.9 Observed-Events-Descriptor


6.2.47.10 Packages-Descriptor


6.2.47.11 Service-Change-Descriptor


6.2.47.12 Signals-Descriptor


6.2.47.13 Statistics-Descriptor


6.2.47.14 Transaction-ID-Or-List


6.3 MGCP Package


6.3.1 MGCP-Action-Request


6.3.2 MGCP-Action-Reply


6.3.3 MGCP-Audit-Connection-Request


6.3.4 MGCP-Audit-Connection-Response


6.3.5 MGCP-Audit-Endpoint-Request


6.3.6 MGCP-Audit-Endpoint-Response


6.3.7 MGCP-Command-Request

mgcp-command-Verb
mgcp-transaction-Id
mgcp-endpoint-Name
mgcp-version

6.3.8 MGCP-Create-Connection-Request


6.3.9 MGCP-Create-Connection-Response


6.3.10 MGCP-Delete-Connection-Request


6.3.11 MGCP-Delete-Connection-Response


6.3.12 MGCP-Endpoint-Configuration-Request


6.3.13 MGCP-Endpoint-Configuration-Response


6.3.14 MGCP-Message


6.3.15 MGCP-Modify-Connection-Request


6.3.16 MGCP-Modify-Connection-Response


6.3.17 MGCP-Notification-Request


6.3.18 MGCP-Notification-Response


6.3.19 MGCP-Notify-Request


6.3.20 MGCP-Notify-Reply


6.3.21 MGCP-Command-Reply

mgcp-response-Code
mgcp-transaction-Id
mgcp-response-String

6.3.22 MGCP-Restart-In-Progress-Request


6.3.23 MGCP-Restart-In-Progress-Response


6.3.24 MGCP-Transaction-Request


6.3.25 MGCP-Transaction-Response


6.4 MGCP Extension Packages


6.5 MEGACO Package


6.5.1 MEGACO-Action-Request


6.5.2 MEGACO-Action-Reply


6.5.3 MEGACO-Add-Request

An instance of OM class MEGACO-Add-Request represents the Add Request command of MEGACO (RFC 3705). This OM class contains the attributes of its super-classes: MEGACO-Amm-Request. It does not define any OM attributes of its own.


6.5.4 MEGACO-Add-Reply

This OM class has the attributes of its super-classes: MEGACO-Service-Result; plus the additional OM attributes listed in Table 1.

xgcp_tab001

Table 1. OM Attributes of OM class MEGACO-Add-Reply

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


6.5.5 MEGACO-Audit-Request

An instance of a subclass of this abstract OM class represents either an Audit Capability command request or an Audit Value command request. This is an abstract class that defines several derived subclasses: MEGACO-Audit-Capability-Request and MEGACO-Audit-Value-Request. This OM class contains the OM attributes of its super-classes: MEGACO-Command-Request; plus the additional OM attributes listed in Table 72.

xgcp_tab072

Table 72. OM Attributes of OM class MEGACO-Audit-Request

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

audit-Descriptor

A single instance of OM class Audit-Descriptor.


6.5.6 MEGACO-Audit-Reply


6.5.7 MEGACO-Audit-Capability-Request

This OM class has the attributes of its super-classes: MEGACO-Service-Request; plus the additional OM attributes listed in Table 12.

xgcp_tab012

Table 12. OM Attributes of OM class MEGACO-Audit-Capabilities-Command

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


6.5.8 MEGACO-Audit-Capability-Reply

This OM class has the attributes of its super-classes: MEGACO-Service-Result; plus the additional OM attributes listed in Table 11.

xgcp_tab011

Table 11. OM Attributes of OM class MEGACO-Audit-Capabilities-Response

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


6.5.9 MEGACO-Audit-Value-Request

This OM class has the attributes of its super-classes: MEGACO-Service-Request; plus the additional OM attributes listed in Table 10.

xgcp_tab010

Table 10. OM Attributes of OM class MEGACO-Audit-Value-Request

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


6.5.10 MEGACO-Audit-Value-Reply

This OM class has the attributes of its super-classes: MEGACO-Service-Result; plus the additional OM attributes listed in Table 9.

xgcp_tab009

Table 9. OM Attributes of OM class MEGACO-Audit-Value-Reply

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


6.5.11 MEGACO-Command-Request


6.5.12 MEGACO-Message


6.5.13 MEGACO-Modify-Request

An instance of OM class MEGACO-Modify-Request represents the Modify Request command of MEGACO (RFC 3705). This OM class contains the attributes of its super-classes: MEGACO-Amm-Request. It does not define any OM attributes of its own.


6.5.14 MEGACO-Modify-Reply

This OM class has the attributes of its super-classes: MEGACO-Service-Result; plus the additional OM attributes listed in Table 3.

xgcp_tab003

Table 3. OM Attributes of OM class MEGACO-Modify-Reply

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


6.5.15 MEGACO-Move-Request

An instance of OM class MEGACO-Move-Request represents the Move Request command of MEGACO (RFC 3705). This OM class contains the attributes of its super-classes: MEGACO-Amm-Request. It does not define any OM attributes of its own.


6.5.16 MEGACO-Move-Reply

This OM class has the attributes of its super-classes: MEGACO-Service-Result; plus the additional OM attributes listed in Table 7.

xgcp_tab007

Table 7. OM Attributes of OM class MEGACO-Move-Reply

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


6.5.17 MEGACO-Notify-Request

This OM class has the attributes of its super-classes: MEGACO-Command-Request; plus the additional OM attributes listed in Table 14.

xgcp_tab014

Table 14. OM Attributes of OM class MEGACO-Notify-Request

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

observed-Events-Descriptor

One instance of OM class Observed-Events-Descriptor.

error-Descriptor

An optional instance of OM class Error-Descriptor.


6.5.18 MEGACO-Notify-Reply

This OM class has the attributes of its super-classes: MEGACO-Service-Result; plus the additional OM attributes listed in Table 13.

xgcp_tab013

Table 13. OM Attributes of OM class MEGACO-Notify-Reply

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


6.5.19 MEGACO-Command-Reply


6.5.20 MEGACO-Service-Change-Request

This OM class has the attributes of its super-classes: MEGACO-Service-Request; plus the additional OM attributes listed in Table 16.

xgcp_tab016

Table 16. OM Attributes of OM class MEGACO-Service-Change-Request

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


6.5.21 MEGACO-Service-Change-Reply

This OM class has the attributes of its super-classes: MEGACO-Service-Result; plus the additional OM attributes listed in Table 15.

xgcp_tab015

Table 15. OM Attributes of OM class MEGACO-Service-Change-Reply

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


6.5.22 MEGACO-Subtract-Request

This OM class has the attributes of its super-classes: MEGACO-Command-Request; plus the additional OM attributes listed in Table 6.

xgcp_tab006

Table 6. OM Attributes of OM class MEGACO-Subtract-Request

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


6.5.23 MEGACO-Subtract-Reply

This OM class has the attributes of its super-classes: MEGACO-Service-Result; plus the additional OM attributes listed in Table 5.

xgcp_tab005

Table 5. OM Attributes of OM class MEGACO-Subtract-Reply

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


6.5.24 MEGACO-Transaction-Pending


6.5.25 MEGACO-Transaction-Request


6.5.26 MEGACO-Transaction-Response


6.6 MEGACO Extension Packages


6.7 H.248 Package

The H.248 package provides specialization of the argument and result objects of the Common GCP package to provide for the services under the H.248 GCP as described in ITU-T Recommendation H.248.1. This package is organized as a separate OM package that can be negotiated using the Negotiate() function.49

The Object-Identifier associated with the H.248 package is:

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

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

The H.248 GCP 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.

The following outlines the OM Class Hierarchy for the H.248 package:

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

6.7.1 H248-Amm-Request

This OM class contains the OM attributes of its super-classes, H248-Command-Request, plus the additional OM attributes listed in Table 68.

xgcp_tab068

Table 68. OM Attributes of OM class H248-Amm-Request

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

descriptors

An object of OM class Amm-Descriptors.


6.7.2 H248-Amm-Descriptors

An instance of the abstract Amm-Descriptors OM class represents the descriptors that can be included with an Add, Move or Modify command. This OM class contains the attributes of its super-classes, Object, plus the additional attributes listed in Table 69.

xgcp_tab069

Table 69. OM Attributes of OM class Amm-Descriptors

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

media-Descriptor

An optional instance of OM class Media-Descriptor.

modem-Descriptor

An optional instance of OM class Modem-Descriptor.

mux-Descriptor

An optional instance of OM class Mux-Descriptor.

events-Descriptor

An optional instance of OM class Events-Descriptor.

signals-Descriptor

An optional instance of OM class Signals-Descriptor.

digit-Map-Descriptor

An optional instance of OM class Digits-Descriptor.

audit-Descriptor

An optional instance of OM class Audit-Descriptor.

statistics-Descriptor

An optional instance of OM class Statistics-Descriptor.


6.7.3 H248-Amm-Reply

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


6.7.4 H248-Action-Request

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


6.7.5 H248-Action-Reply

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


6.7.6 H248-Add-Request

An instance of the OM clss H248-Add-Request represents the Add Request command of ITU-T Recommendation H.248.1 (09/2005). This OM class has the attributes of its super-classes: H248-Amm-Request. It does not define any OM attributes of its own. See H248-Amm-Request.


6.7.7 H248-Add-Reply

This OM class has the attributes of its super-classes: H248-Service-Result; plus the additional OM attributes listed in Table 51.

xgcp_tab051

Table 51. OM Attributes of OM class H248-Add-Reply

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

media-Descriptor
modem-Descriptor
mux-Descriptor
events-Descriptor
signals-Descriptor
digit-Map-Descriptor
observed-Events-Descriptor
event-Buffer-Descriptor
statistics-Descriptor
packages-Descriptor

6.7.8 H248-Audit-Request

An instance of a subclass of this abstract OM class represents either an Audit Capability Request command or an Audit Value Request command. This is an abstract class that defines several derived subclasses: H248-Audit-Capability-Request and H248-Audit-Value-Request. This OM class contains the OM attributes of its super-classes: H248-Command-Request; plus the additional OM attributes listed in Table 71.

xgcp_tab071

Table 71. OM Attributes of OM class H248-Audit-Request

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

audit-Descriptor

A single instance of OM class Audit-Descriptor.


6.7.9 H248-Audit-Reply

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


6.7.10 H248-Audit-Capability-Request

An instance of OM class H248-Audit-Capability-Request represents an Audit Capability command request of ITU-T Recommendation H.248.1 (09/2005). This OM class contains the attributes of its super-classes: H248-Audit-Request; it does not define any OM attributes of its own.


6.7.11 H248-Audit-Capability-Reply

This OM class has the attributes of its super-classes: H248-Service-Result; plus the additional OM attributes listed in Table 61.

xgcp_tab061

Table 61. OM Attributes of OM class H248-Audit-Capabilities-Response

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

media-Descriptor
modem-Descriptor
mux-Descriptor
events-Descriptor
signals-Descriptor
observed-Events-Descriptor
event-Buffer-Descriptor
statistics-Descriptor

6.7.12 H248-Audit-Value-Request

An instance of OM class H248-Audit-Value-Request represents an Audit Value command request of ITU-T Recommendation H.248.1 (09/2005). This OM class contains the attributes of its super-classes: H248-Audit-Request; it does not define any OM attributes of its own.


6.7.13 H248-Audit-Value-Reply

This OM class has the attributes of its super-classes: H248-Service-Result; plus the additional OM attributes listed in Table 59.

xgcp_tab059

Table 59. OM Attributes of OM class H248-Audit-Value-Reply

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

media-Descriptor
modem-Descriptor
mux-Descriptor
events-Descriptor
signals-Descriptor
digit-Map-Descriptor
observed-Events-Descriptor
event-Buffer-Descriptor
statistics-Descriptor
packages-Descriptor

6.7.14 H248-Command-Request

An instance of a concrete subclass of this abstract OM class represents an ITU-T Recommendation H.248.1 (09/2005) CommandRequest. This abstract OM class defines several abstract and concrete subclasses: H248-Amm-Request, H248-Subtract-Request, H248-Audit-Request, H248-Notify-Request and H248-Service-Change-Request.

This abstract OM class has the attributes of its super-classes, Command-Request, plus the additional OM attributes listed in Table 70.

xgcp_tab070

Table 70. OM Attributes of OM class H248-Command-Request

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

termination-Id

An instance of OM class Termination-ID that specifies the termination to which the command request applies.


6.7.15 H248-Command-Reply

An instance of a concrete subclass of this abstract OM class represents an ITU-T Recommendation H.248.1 (09/2005) CommandReply. This abstract OM class defines several abstract and concrete subclasses: H248-Amm-Reply, H248-Audit-Reply, H248-Notify-Reply and H248-Service-Change-Reply.

This abstract OM class has the attributes of its super-classes, Command-Reply, plus the additional OM attributes listed in Table 73.

xgcp_tab073

Table 73. OM Attributes of OM class H248-Command-Reply

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

termination-Id

An instance of OM class Termination-ID that specifies the termination to which the command reply applies.


6.7.16 H248-Message


6.7.17 H248-Modify-Request