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

MGI Technical Specification

Description: OpenSS7 Project Library MGI

A PDF version of this document is available here.

Media Gateway Interface (MGI)

Media Gateway Interface (MGI) Specification

About This Manual

This is Edition 7.20141001, last updated 2014-10-25, of The Media Gateway Interface (MGI) 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 Media Gateway Interface (MGI) for OpenSS7. It contains recommendations on software architecture as well as platform and system applicability of the Media Gateway Interface (MGI).

This document specifies a Media Gateway Interface (MGI) Specification in support of the OpenSS7 Media Gateway (MG) protocol stacks. It provides abstraction of the Media Gateway interface to these components as well as providing a basis for Media Gateway control for other Media Gateway protocols.

Purpose

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

Audience

The audience for this document is software developers, maintainers and users and integrators of the Media Gateway Interface (MGI). 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: mgi.texi,v $
Revision 1.1.2.3  2011-02-07 02:21:40  brian
- updated manuals

Revision 1.1.2.2  2010-03-10 08:42:18  brian
- added Optranex files

Revision 1.1.2.1  2010-02-22 14:25:53  brian
- added new documentation files

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

This document specifies a STREAMS-based kernel-level instantiation of the Media Gateway Interface (MGI) definition. The Media Gateway Interface (MGI) enables the user of a media gateway service to access and use any of a variety of conforming media gateway providers without specific knowledge of the provider’s protocol. The service interface is designed to support any network media gateway protocol. This interface only specifies access to media gateway service providers, and does not address issues concerning media gateway management, protocol performance, and performance analysis tools.

This specification assumes that the reader is familiar with ITU-T state machines and media gateway interface (e.g. H.248) and STREAMS.

1.1 Related Documentation

  • ITU-T Recommendation H.248
  • System V Interface Definition, Issue 2 - Volume 3

1.1.1 Role

This document specifies an interface that supports the services provided by the Media Gateway for ITU-T, ANSI and ETSI applications as described in ITU-T Recommendation H.248. These specifications are targeted for use by developers and testers of protocol modules that require media gateway service.

1.2 Definitions, Acronyms, Abbreviations

LM

Local Management.

LMS

Local Management Service.

LMS User

A user of Local Management Services.

LMS Provider

A provider of Local Management Services.

ISO

International Organization for Standardization

OSI

Open Systems Interconnection

QOS

Quality of Service

STREAMS

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


2 The Media Gateway Layer

The Media Gateway Layer provides the means to manage the association of MG-User connections. It is responsible for the routing and management of data to and from media gateway connections between MG-user entities.


2.1 Model of the MGI

The MGI defines the services provided by the media gateway layer to the media gateway user at the boundary between the media gateway provider (MG) and the media gateway user (MGC) entity. The interface consists of a set of primitives defined as STREAMS messages that provide access to the media gateway layer services, and are transferred between the MGS user entity (MGC) and the MGS provider (MG). These primitives are of two types; ones that originate from the MGS user, and others that originate from the MGS provider. The primitives that originate from the MGS user make requests to the MGS provider, or respond to an indication of an event of the MGS provider. The primitives that originate from the MGS provider are either confirmations of a request or are indications to the MGS user that an event has occurred. Figure 1 show the model of the MGI.

Model of the MGI

Figure 1. Model of the MGI

The MGI allows the MGS provider to be configured with any media gateway layer user (such as a swtiching application) that also conforms to the MGI. A media gateway layer user can also be a user program that conforms to the MGI and accesses the MGS provider via putmsg(2s) and getmsg(2s) system calls. A typical configuration, however, is to have a switching user-space application using the media gateway layer. Nevertheless, another typical configuration is to have an H.248 multiplexing driver connected to the MG provider Streams.


2.2 MGI Services

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

The MGI Services are broken into two groups: local management services and protocol services. Local management services are responsible for the local management of Streams, assignment of Streams to physical points of attachment, enabling and disabling of Streams, management of options associated with a Stream, and general acknowledgement and event reporting for the Stream. Protocol services consist of connecting a Stream to a medium, exchanging bits with the medium, and disconnecting the Stream from the medium.

2.2.1 Local Management

Local management services are listed in Table 1.

mgit01

Table 1. Local Management Services

The local management services interface is described in Local Management Services, and the primitives are detailed in Local Management Service Primitives. The local management services interface is defined by the sys/mgi.h header file (see MGI Header Files).

2.2.2 Protocol

Protocol services are listed in Table 2.

mgit02

Table 2. Protocol Services

The protocol services interface is described in Protocol Services, and the primitives are detailed in Protocol Service Primitives. The protocol services interface is defined by the sys/mgi.h header file (see MGI Header Files).


2.3 Purpose of the MGI

The MGI is typically implemented as a device driver connecting and controlling a TDM (Time Division Mutliplexing) device that provides access to multiplexed media streams, and a network device that provides packet-based media streams. This is a high level control interface that can be used in conjunction with a media gateway control protocol or an integrated media gateway controller to provide media gateway or integrated softswitch functions.

This allows MGCP and MATRIX modules to be verified independently for correct operation and then simply used for all manner of new device drivers that can implement the MGI interface.


2.4 Media Gateway Addressing

Each use of MGI must establish an identity to communicate with other media gateway users. The MGS user must identify the physical media over which communication will occur. This is particularly evident on a system that is attached to multiple physical media. Figure 17 illustrates the identification approach, which is explained below.

Media Gateway Addressing Components

Figure 17. Media Gateway Addressing Components

2.4.1 Physical Attachment Identification

The physical point of attachment (PPA in Figure 17) is the point at which a system interface attaches itself to a physical communications medium (a channel, facility or network interface). All communication on that physical medium funnels through the PPA associated with that physical medium. On systems where a MGS provider supports more than one physical medium, the MGS user must identify the medium through which it will communicate. A PPA is identified by a unique PPA identifier.

For media that supports physical layer multiplexing of multiple channels over a single physical medium (such as the B and D channels of ISDN), the PPA identifier must identify the specific channel(s) over which communication will occur. See also Multiplex Media.

Unlike the Data Link Provider Interface (DLPI), which also uses the concept of a PPA, MGI does not define a SAP for a MGS user.

Once a Stream has been associated with a PPA, all messages received on that medium are controlled by the attached MGS user. Only one major/minor device number combination (Stream head) can be associated with a given PPA and active for a range of channels at any point in time.

2.4.2 MGS Provider Styles

Two styles of MGS provider are defined by MGI, distinguished by the way they enable a MGS user to choose a particular PPA.

2.4.2.1 Style 1 MGS Provider

The Style 1 provider assigns a PPA based on the major/minor device the MGS user opened. One possible implementation of a Style 1 driver would reserve a major device for each PPA the media gateway device driver would support. This would allow the STREAMS clone open feature to be used for each PPA configured. This style of provider is appropriate when few PPAs will be supported.

For example, a PCIe card that supports four SONET/SDH ports could assign a major device number to the card diver and a minor device number to each of the ports on each card in the system. To establish a Stream to a MGS provider for a given port, the minor device number ‘1’ or ‘2’ could be opened for port ‘1’ or ‘2’ on card ‘1’, minor device number ‘3’ or ‘4’ could be opened for port ‘1’ or ‘2’ on card ‘2’, and so on. One major device number for the driver could easily support 127 cards in a system, which is not possible for typical PCIe systems and, therefore, is ample.

Style 1 providers do not user the MG_ATTACH_REQ and MG_DETACH_REQ primitives and when freshly opened are in the MGS_ATTACHED state. That is, as illustrated in Figure 17, the Style 1 MGS provider associates the Stream with the PPA during the open(2s) system call.

2.4.2.2 Style 2 MGS Provider

If the number of PPAs as MGS provider will support is large, a Style 2 provider implementation is more suitable. The Style 2 provider requires a MGS user to explicitly identify the desired PPA using a special attach service primitive. For a Style 2 driver, the open(2s) system call creates a Stream between the MGS user and MGS provider, and the attach primitive then associated a particular PPA with that Stream. The format of the PPA identifier is specific to the MGS provider, and should be described in the provider-specific addendum documentation.

The MGS user uses the support primitvies(MG_ATTACH_REQ, MG_ENABLE_REQ) to associate a Stream with a given Physical Point of Appearance. Style 2 MGS providers, when freshly opened, are in the MGS_DETACHED state. That is, the Style 2 MGS provider does not associate the Stream with the PPA during the open(2s) call, but only later when the MG_ATTACH_REQ primitive is issued by the MGS user.

2.4.3 Multiplex Media

To accommodate multiplexed media and multi-media channels, there are three kinds of PPA address:

  1. A discrete PPA that specifies a non-multiplexed medium.

    This is the normal case of a Style 1 or Style 2 MGS provider supporting access to a non-multiplexed medium. An example is a MGS provider supporting access to a FXO/FXS interface.

  2. A specific PPA that specifies a single channel to a multiplexed medium.

    This is again the normal case of a Style 1 or Style 2 MGS provider supporting access to a specific channel in a multiplexed medium. An example is a MGS provider supporting access to channel 16 of an E1 interface.

  3. A general PPA that specifies a channel group for a multiplexed medium.

    This is th case of a Style 1 or Style 2 MGS provider supporting access to multiple channels in a multiplexed medium. An example is a MGS provider supporting statistically multiplexed channel access to a full or fractional T1 facilitiy. Another example is access to the left and right channels of a stereo program.

In the case of a general PPA, as enumerated in 3 above, some additional information is required to identify which slots in the group of channle forming the multiplex are associatedw the the MGS user Stream. This additional information is provided using the mg_slot parameter to the MG_CONN_REQ, MG_CONN_CON, MG_DATA_REQ, MG_DATA_IND, MG_EVENT_IND, MG_DISCON_REQ, MG_DISCON_CON and MG_DISCON_IND primitives.2


2.5 Media Gateway Parameters


3 MGI Services Definition


3.1 Local Management Services


3.1.1 Acknowledgement Service

The acknowledgement service provides the MGS user with the ability to receive positive and negative acknowledgements regarding the successful or unsuccessful completion of services.

  • MG_OK_ACK: The MG_OK_ACK message is used by the MGS provider to indicate successful receipt and completion of a service primitive request that requires positive acknowledgement.
  • MG_ERROR_ACK: The MG_ERROR_ACK message is used by the MGS provider to indicate successful receipt and failure to complete a service primitive request that requires negative acknowledgement.

A successful invocation of the acknowledgement service is illustrated in Figure 15.

Message Flow: Successful Acknowledgement Service

Figure 15. Message Flow: Successful Acknowledgement Service

As illustrated in Figure 15, the service primitives for which a positive acknowledgement may be returned are the MG_ATTACH_REQ and MG_DETACH_REQ.

An unsuccessful invocation of the acknowledgement service is illustrated in Figure 16.

Message Flow: Unsuccessful Acknowledgement Service

Figure 16. Message Flow: Unsuccessful Acknowledgement Service

As illustrated in Figure 16, the service primitives for which a negative acknowledgement may be returned are the MG_INFO_REQ, MG_ATTACH_REQ, MG_DETACH_REQ, MG_ENABLE_REQ, MG_DISABLE_REQ and MG_OPTMGMT_REQ messages.


3.1.2 Information Reporting Service

The information reporting service provides the MGS user with the ability to elicit information from the MGS provider.

  • MG_INFO_REQ: The MG_INFO_REQ message is used by the MGS user to request information about the MGS provider.
  • MG_INFO_ACK: The MG_INFO_ACK message is issued by the MGS provider to provide requested information about the MGS provider.

A successful invocation of the information reporting service is illustrated in Figure 2.

Message Flow: Successful Information Reporting Service

Figure 2. Message Flow: Successful Information Reporting Service


3.1.3 Physical Point of Attachment Service

The local management interface provides the MGS user with the ability to associate a Stream to a physical point of appearance (PPA) or to disassociate a Stream from a PPA. The local management interface provides for two styles of MGS provider:3

Style 1 MGS Provider

A Style 1 MGS provider is a provider that associates a Stream with a PPA at the time of the first open(2s) call for the device, and disassociates a Stream from a PPA at the time of the last close(2s) call for the device.

Physical points of attachment (PPA) are assigned to major and minor device number combinations. When the major and minor device number combination is opened, the opened Stream is automatically associated with the PPA for the major and minor device number combination. The last close of the device disassociates the PPA from the Stream.

Freshly opened Style 1 MGS provider Streams start life in the MG_DISABLED state.

This approach is suitable for MGS providers implemented as real or pseudo-device drivers and is applicable when the number of minor devices is small and static.

Style 2 MGS Provider

A Style 2 MGS provider is a provider that associates a Stream with a PPA at the time that the MGS user issues the MG_ATTACH_REQ message. Freshly opened Streams are not associated with any PPA. The Style 2 MGS provider Stream is disassociated from a PPA when the Stream is closed or when the MGS user issues the MG_DETACH_REQ message.

Freshly opened Style 2 MGS provider Streams start life in the MG_UNATTACHED state.

This approach is suitable for MGS providers implemented as clone real or pseudo-device drivers and is applicable when the number of minor devices is large or dynamic.


3.1.3.1 PPA Attachment Service

The PPA attachment service provides the MGS user with the ability to attach a Style 2 MGS provider Stream to a physical point of appearance (PPA).

  • MG_ATTACH_REQ: The MG_ATTACH_REQ message is issued by the MGS user to request that a Style 2 MGS provider Stream be attached to a specified physical point of appearance (PPA).
  • MG_OK_ACK: Upon successful receipt and processing of the MG_ATTACH_REQ message, the MGS provider acknowledges the success of the service completion with a MG_OK_ACK message.
  • MG_ERROR_ACK: Upon successful receipt but failure to process the MG_ATTACH_REQ message, the MGS provider acknowledges the failure of the service completion with a MG_ERROR_ACK message.

A successful invocation of the attachment service is illustrated in Figure 3.

Message Flow: Successful Attachment Service

Figure 3. Message Flow: Successful Attachment Service


3.1.3.2 PPA Detachment Service

The PPA detachment service provides the MGS user with the ability to detach a Style 2 MGS provider Stream from a physical point of attachment (PPA).

  • MG_DETACH_REQ: The MG_DETACH_REQ message is issued by the MGS user to request that a Style 2 MGS provider Stream be detached from the attached physical point of appearance (PPA).
  • MG_OK_ACK: Upon successful receipt and processing of the MG_DETACH_REQ message, the MGS provider acknowledges the success of the service completion with a MG_OK_ACK message.
  • MG_ERROR_ACK: Upon successful receipt but failure to process the MG_DETACH_REQ message, the MGS provider acknowledges the failure of the service completion with a MG_ERROR_ACK message.

A successful invocation of the detachment service is illustrated in Figure 4.

Message Flow: Successful Detachment Service

Figure 4. Message Flow: Successful Detachment Service


3.1.4 Initialization Service

The initialization service provides the MGS user with the abilty to enable and disable the Stream for the associated PPA.


3.1.4.1 Interface Enable Service

The interface enable service provides the MGS user with the ability to enable an MGS provider Stream that is associated with a PPA. Enabling the interface permits the MGS user to exchange protocol service interface messages with the MGS provider.

  • MG_ENABLE_REQ: The MG_ENABLE_REQ message is issued by the MGS user to request that the protocol service interface be enabled.
  • MG_ENABLE_CON: Upon successful enabling of the protocol service interface, the MGS provider acknowledges successful completion of the service by issuing a MG_ENABLE_CON message to the MGS user.
  • MG_ERRORK_ACK: Upon unsuccessful enabling of the protocol service interface, the MGS provider acknowledges the failure to complete the service by issuing an MG_ERROR_ACK message to the MGS user.

A successful invocation of the enable service is illustrated in Figure 5.

Message Flow: Successful Enable Service

Figure 5. Message Flow: Successful Enable Service


3.1.4.2 Interface Disable Service

The interface disable service provides the MGS user with the ability to disable an MGS provider Stream that is associated with a PPA. Disabling the interface withdraws the MGS user’s ability to exchange protocol service interface messages with the MGS provider.

  • MG_DISABLE_REQ: The MG_DISABLE_REQ message is issued by the MGS user to request that the protocol service interface be disabled.
  • MG_DISABLE_CON: Upon successful disabling of the protocol service interface, the MGS provider acknowledges successful completion of the service by issuing a MG_DISABLE_CON message to the MGS user.
  • MG_ERRORK_ACK: Upon unsuccessful disabling of the protocol service interface, the MGS provider acknowledges the failure to complete the service by issuing an MG_ERROR_ACK message to the MGS user.
  • MG_DISABLE_IND: The MG_DISABLE_IND message is used by the MGS provider to indicate to the MGS user that the Stream has been autonomously disabled and the cause of the autonomous disabling.

A successful invocation of the disable service is illustrated in Figure 6.

Message Flow: Successful Disable Service

Figure 6. Message Flow: Successful Disable Service


3.1.5 Options Management Service

The options management service provides the MGS user with the ability to control and affect various generic and provider-specific options associated with the MGS provider.

  • MG_OPTMGMT_REQ: The MGS user issues a MG_OPTMGMT_REQ message when it wishes to interrogate or affect the setting of various generic or provider-specific options associated with the MGS provider for the Stream upon which the message is issued.
  • MG_OPTMGMT_ACK: Upon successful receipt of the MG_OPTMGMT_REQ message, and successful options processing, the MGS provider acknowledges the successful completion of the service with an MG_OPTMGMT_ACK message.
  • MG_ERROR_ACK: Upon successful receipt of the MG_OPTMGMT_REQ message, and unsuccessful options processing, the MGS provider acknowledges the failure to complete the service by issuing an MG_ERROR_ACK message to the MGS user.

A successful invocation of the options management service is illustrated in Figure 7.

Message Flow: Successful Options Management Service

Figure 7. Message Flow: Successful Options Management Service


3.1.6 Error Reporting Service

The error reporting service provides the MGS provider with the ability to indicate asynchronous errors to the MGS user.

  • MG_ERROR_IND: The MGS provider issues the MG_ERROR_IND message to the MGS user when it needs to indicate an asynchronous error (such as the unusability of the communications medium).

A successful invocation of the error reporting service is illustrated in Figure 8.

Message Flow: Successful Error Reporting Service

Figure 8. Message Flow: Successful Error Reporting Service


3.1.7 Statistics Reporting Service

  • MG_STATS_IND:

A successful invocation of the statistics reporting service is illustrated in Figure 9.

Message Flow: Successful Statistics Reporting Service

Figure 9. Message Flow: Successful Statistics Reporting Service


3.1.8 Event Reporting Service

The event reporting service provides the MGS provider with the ability to indicate specific asynchronous management events to the MGS user.

  • MG_EVENT_IND: The MGS provider issues the MG_EVENT_IND message to the MGS user when it wishes to indicate an asynchronous (management) event to the MGS user.

A successful invocation of the event reporting service is illustrated in Figure 10.

Message Flow: Successful Event Reporting Service

Figure 10. Message Flow: Successful Event Reporting Service


3.2 Protocol Services

Protocol services are specific to the Media Gateway interface. These services consist of connection services that permit the transmit and receive directions to be connected to or disconnected from the medium, and data transfer services that permit the exchange of bits between MGS users.

The service primitives that implement the protocol services are described in detail in Protocol Service Primitives.


3.2.1 Create Service

The create service provides the ability for the MGS user to create a session context. A session context so created does not have any termination points associated with it. Session contexts created with the Create Service can be destroyed with the Destroy Service. Session contexts provide a mechanism whereby termination points can be enjoined into a communications session.

  • MG_CREATE_REQ: The MG_CREATE_REQ primitive is used by the MGS user to create a session context. The newly created session context has no terminations associated with it.
  • MG_CREATE_ACK: The MG_CREATE_REQ primitive is issued by the MGS provider to acknowledge creation of a session context.

Session contexts can be long-lived or short-lived depending on the needs of the MGS user. For example, it is possible for the Media Gateway to allocated all of the session contexts that it might need to perform its functions in advance of the need for communications within any given session context. Sessions may alternately be created on demand using the Join Service.


3.2.2 Join Service

The join service provides the ability for the MGS user to associate a termination point with a session. It is equivalent to the Add service for a single termination point in H.248. The join service may also be used to create a session context, on demand, by specifying a null session context identifier.

  • MG_JOIN_REQ: The MG_JOIN_REQ primitive is used by the MGS user to associate a termination point with a session context. The primitive only affects a single termination point within a single session. The primitive may also be used to create a session context.
  • MG_JOIN_CON: The MG_JOIN_CON primitive is issued by the MGS provider to confirm that a termination point has been associated with a session context. The primitive only confirms the association of a single termination point within a session. The primitive may also be used to confirm the creation of a session.

A successful invocation of the join service is illustrated in Figure 18.

Message Flow: Successful Join Service by MGS Provider

Figure 18. Message Flow: Successful Join Service by MGS Provider

The lifespan of a termination point within a session context can be long-lived or short-lived depending on the needs of the MGS user. For example, a Media Gateway can establish all of the session contexts that it might need and enjoin termination points into the session contexts in advance of any need for communication amoung the termination points within the sessions. This permits a pre-assigned association of termination points to session contexts.


3.2.3 Enable Service

The enable service provides the ability for the MGS user to reserve resources or set parameters associated with a termination point. It is equivalent in part to the Add service for a single termination point in ITU-T Recommendation H.248.

The MGS user can choose the point at which termination points are to be enabled. An enabled termination point is not necessarily connected into a session context. Where the nature of the termination point does not require a procedure to be enabled, the Connection Service can be used to both enable the termination point and establish communications within the session in a single operation.

Note that a termination point does not need to be joined to a session context to be enabled.

  • MG_ENABLE_REQ: The MG_ENABLE_REQ primitive is used by the MGS user to request that resources be allocated or parameters be set for a termination point. This may include, for example, the activation of an RTP session, or the seizure of a TDM trunk. Parameters that might be included when enabling a termination point might include, for an RTP stream, whether RTCP is used, the maximum jitter buffer size, the codec, and the IP address and port number of the remote end of the RTP stream.
  • MG_ENABLE_CON: The MG_ENABLE_CON primitive is issued by the MGS provider to confirm that resources have been allocated and parameters negotiated for a termination point. This may include, for example, the activation of an RTP session, or the seizure of a TDM trunk.

A successful invocation of the enable service is illustrated in Figure 19.

Message Flow: Successful Enable Service by MGS Provider

Figure 19. Message Flow: Successful Enable Service by MGS Provider


3.2.4 Connection Service

The connection service provides the ability for the MGS user to specify that a termination point be connected within a session context. Termination points can be connected for transmission (samples sent to the termination point) or for reception (samples received from the termination point) or both. Connecting a termination point within a session context causes transmission to be taken from the session context and receiption to be provided to the session context.

  • MG_CONN_REQ: The MG_CONN_REQ message is used by the MGS user to request that the termination point be connected to the session context. Connection to the context might require some switching or other mechanism to prepare the termination point for data transmission and reception. Connections can be formed for the receive direction or the transmit direction independently.
  • MG_CONN_CON: The MG_CONN_CON message is used by the MGS provider to confirm that the termination point has been connected to the session context. Connection to the session context may have required some switching or other mechanism to prepare the termination point for data transmission and receptoin. Connection can be confirmed for the receive or transmit directions independently.

A successful invocation of the connection service is illustrated in Figure 11.

Message Flow: Successful Connection Service

Figure 11. Message Flow: Successful Connection Service


3.2.5 Action Service

The action service provides the ability for the MGS user to request that an action be performed on a termination point within a session, or on an entire session. It allows the MGS user to provide tones, anouncements, test terminations, etc.

  • MG_ACTION_REQ: The MG_ACTION_REQ message is used by the MGS user to request that an action be performed on a session or on a termination point within a session. The action can be an audio pattern provided by the MGS user in associated data blocks, or can be a pre-established pattern specified by the MGS user. The MGS user has control of the session and termination point within the session to which the action is applied, the duration or repetition of the action.
  • MG_ACTION_IND: The MG_ACTION_IND message is used by the MGS provider to indicate to the MGS user that a requested action has been initiated or has passed a repetition point.
  • MG_ACTION_CON: The MG_ACTION_CON message is used by the MGS provider to confirm to the MGS user that an action of restricted duration or repetitions has reached the endi of its duration or repetitions.
  • MG_ABORT_REQ: The MG_ABORT_REQ message is used by an MGS user to abort an ongoing actions that was previously initiated with an MG_ACTION_REQ message, but has not yet terminated (i.e. with an MG_ACTION_CON).

A successful invocation of the action service is illustrated in Figure 20.

Message Flow: Successful Action Service by MGS Provider

Figure 20. Message Flow: Successful Action Service by MGS Provider

An aborted invocation of the action service is illustrated in Figure 21.

Message Flow: Aborted Action Service by MGS Provider

Figure 21. Message Flow: Aborted Action Service by MGS Provider


3.2.6 Data Transfer Service

The data transfer service provides the MGS user with the ability to request that bits be transmitted on the medium, and the MGS provider with the ability to indicate bits that have been received from the medium.

  • MG_DATA_REQ: The MG_DATA_REQ message is used by the MGS user to place raw bits onto the medium. The Stream must have first been successfully activated in the transmit direction using the MG_CONN_REQ message.
  • MG_DATA_IND: The MG_DATA_IND message is issued by the MGS provider when activated for the receive direction with the MG_CONN_REQ message, to indicate bits received on the medium.

A successful invocation of the data transfer service is illustrated in Figure 12.

Message Flow: Successful Data Transfer Service

Figure 12. Message Flow: Successful Data Transfer Service


3.2.7 Notify Service

The notify service provides the MGS user with the ability to request notification of specific events or detected conditions. These notifications can be on a specific termination point, within a session context, or on a global basis.

  • MG_NOTIFY_REQ: The MG_NOTIFY_REQ message is used by the MGS user to request that the MGS provider issue notification indications for specific events or detected conditions with the Media Gateway.
  • MG_NOTIFY_IND: The MG_NOTIFY_IND message is issued by the MGS provider when a detected event requested by the MGS user has occured.

This service is roughly equivalent to the Audit service of ITU-T Recommendation H.248.1.


3.2.8 Disconnection Service

The disconnection service provides the ability for the MGS user to disconnect from the medium, withdrawing from the purpose of transmitting bits, receiving bits, or both. It allows the MGS provider to autonomously indicate that the medium has been disconnected from the Stream. In OSI, this is a Layer 1 function, possibly the responsiblity of a multiplex or digital cross-connect switch.

  • MG_DISCON_REQ: The MG_DISCON_REQ message is used by the MGS user to request that the Stream be disconnected from the medium. Disconnection from the medium might require some switching or other mechanism. Disconnection can be performed for the receive direction or the transmit direction independently.
  • MG_DISCON_CON: The MG_DISCON_CON message is used by the MGS provider to confirm that the Stream has been disconnected from the medium. Disconnect from the medium might require some switching or other mechanism. Disconnection can be confirmed for the receive or transmit directions independently.
  • MG_DISCON_IND: The MG_DISCON_IND message is used by the MGS provider to indicate to the MGS user that the termination point has been disconnected from the session context. Disconnection is indicated for both the receive and transmit directions. Disconnection indications can result from such things as loss of an RTP stream, on-hook condition, trunk release, or hardware-failure oriented circuit blocking. This primitive is roughly equivalent to the ServiceChange service of ITU-T Recommendation H.248 for a specific termination.

A successful invocation of the disconnection service by the MGS user is illustrated in Figure 13.

Message Flow: Successful Disconnection Service by MGS User

Figure 13. Message Flow: Successful Disconnection Service by MGS User

A successful invocation of the disconnection service by the MGS provider is illustrated in Figure 14.

Message Flow: Successful Disconnection Service by MGS Provider

Figure 14. Message Flow: Successful Disconnection Service by MGS Provider


3.2.9 Disable Service

The disable service provides the ability for the MGS user to release resources associated with a termination point. It is equivalent in part to the Subtract service for a single termination point in ITU-T Recommendation H.248.

The MGS user can choose th point at which termination points are to be enabled and disabled. An enabled or disable termination point is not necessarily connected into a session context. Where the nature of the termination point does not require a procedure to be disabled, the Disconnection Service can be used to both disable the termination point and disconnect communications within the session in a single operation.

Note that a termination point does not need to be joined to a session context to be disabled.

  • MG_DISABLE_REQ: The MG_DISABLE_REQ primitive is used by the MGS user to request that resources be released for a termination point. This may include, for example, the deactivation of an RTP session, or the release of a TDM trunk.
  • MG_DISABLE_CON: The MG_DISABLE_CON primitive is issued by the MGS provider to confirm that resources have been released for a termination point. This may include, for example, the release of an RTP stream, or the release of a TDM trunk.

A successful invocation of the disable service is illustrated in Figure 22. The disable service is an acknowledged and confirmed service that requries the immediate acknowledgement or refusal of the requires penultimately followed by a confirmation on success.

Message Flow: Successful Disable Service by MGS Provider

Figure 22. Message Flow: Successful Disable Service by MGS Provider


3.2.10 Leave Service

The leave service provides the ability for the MGS user to disassociate a termination point with a session context. It is roughly equivalent to the Subtract service for a single termination point in ITU-T Recommendation H.248. The leave service may also be used to disconnect a termination point in one operation.

  • MG_LEAVE_REQ: The MG_LEAVE_REQ service provides the ability for the MGS user to disassociate a termination point from a session context. The primitive affects one or more termination points within a given session context. The primitive may also be used to disconnect termination points from the session context as they are being disassociated.
  • MG_LEAVE_CON: The MG_LEAVE_CON primitive is issued by the MGS provider to confirm that a termination point, or a number of termination points, have been disconnected from and disassociated with a session context. The primitive confirms one or more termination point disconnects and removals from the session.

A successful invocation of the leave service is illustrated in Figure 23. The leave service is an acknowleged and confirmed service that requires the immediate acknowledgement or refusal of the request penultimately followed by a confirmation on success.

Message Flow: Successful Leave Service by MGS Provider

Figure 23. Message Flow: Successful Leave Service by MGS Provider

The lifespan of termination points within a session context can be long-lived or short-lived depending on the needs of the MGS user. For example, a Media Gateway can establish all of the session contexts that it might need in advance and enjoin termination points into the session contexts in advance of any need for communiction among the termination points within the sessions. This permits pre-assigned association of termination points to session contexts. In this case, the leave service is only required when tearing down an entire Media Gateway.


3.2.11 Destroy Service

The destroy service allows an MGS user to request the destruction of a session context. Destruction of a session context may result in the disconnection and disassociation of all termination points that are currently connected or enjoined in the session context.

  • MG_DESTROY_REQ: The MG_DESTROY_REQ primitive is used by an MGS user to request that a session context be deleted.
  • MG_DESTROY_ACK: The MG_DESTROY_ACK primitive is issued by the MGS provider to acknowledge the destruction of a session context. The session context identfier is available again to be used for the creation of a session context.

Session contexts can be long-lived or short-lived depending on the needs of the MGS user. For example, it is possible for the Media Gateway to allocated all of the session contexts that it might need to perform its functions in advance of the need for communications within any given session context. In this case, the destroy service might only be required when tearing down an entire Media Gateway.


4 MGI Service Primitives


4.1 Local Management Service Primitives

These service primitives implement the local management services (see Local Management Services).


4.1.1 Acknowledgement Service Primitives

These service primitives implement the acknowledgement service (see Acknowledgement Service).


4.1.1.1 MG_OK_ACK

Description

This primitive is used to acknowledge receipt and successful service completion for primitives requiring acknowledgement that have no confirmation primitive.

Format

This primitive consists of one M_PCPROTO message block, structured as follows:

typedef struct MG_ok_ack {
    mg_ulong mg_primitive;
    mg_ulong mg_correct_prim;
    mg_ulong mg_state;
} MG_ok_ack_t;

Parameters

The service primitive contains the following parameters:

mg_primitive

Indicates the service primitive type. Always MG_OK_ACK.

mg_correct_prim

Indicates the service primitive that was received and serviced correctly. This field can be one of the following values:

MG_ATTACH_REQAttach request.
MG_ENABLE_REQEnable request.
MG_CONN_REQConnect request.
MG_DISCON_REQDisconnect request.
MG_DISABLE_REQDisable request.
MG_DETACH_REQDetach Request.
mg_state

Indicates the current state of the MGS provider at the time that the primitive was issued. This field can be one of the following values;

MGS_UNINITUnitialized.
MGS_UNUSABLEDevice cannot be used, Stream in hung state.
MGS_DETACHEDNo PPA attached, awaiting MG_ATTACH_REQ.
MGS_ATTACHEDPPA attached, awaiting MG_ENABLE_REQ.
MGS_WCON_EREQWaiting to send MG_ENABLE_CON.
MGS_WCON_RREQWaiting to send MG_DISABLE_CON.
MGS_ENABLEDReady for use, awaiting primitive exchange.
MGS_WCON_CREQWaiting to send MG_CONN_CON.
MGS_WCON_DREQWaiting to send MG_DISCON_CON.
MGS_CONNECTEDConnected, active data transfer.

State

This primitive is issued by the MGS provider in the MGS_WACK_AREQ, MGS_WACK_UREQ, MGS_WACK_CREQ or MGS_WACK_DREQ state.

New State

The new state is MGS_DETACHED, MGS_ATTACHED, MGS_ENABLED or MGS_CONNECTED, depending on the primitive to which the message is responding.


4.1.1.2 MG_ERROR_ACK

Description

The error acknowledgement primitive is used to acknowledge receipt and unsuccessful service completion for primitives requiring acknowledgement.

Format

The error acknowledgement primitive consists of one M_PCPROTO message block, structured as follows:

typedef struct MG_error_ack {
    mg_ulong mg_primtive;
    mg_ulong mg_error_primitive;
    mg_ulong mg_error_type;
    mg_ulong mg_unix_error;
    mg_ulong mg_state;
} MG_error_ack_t;

Parameters

The error acknowledgement primitive contains the following parameters:

mg_primitive

Indicates the primitive type. Always MG_ERROR_ACK.

mg_error_type

Indicates the MG error number. This field can have one of the following values:

[MGSYSERR]UNIX system error.
[MGBADADDR]Bad address format or content.
[MGOUTSTATE]Interface out of state.
[MGBADOPT]Bad options format or content.
[MGBADPARM]Bad parameter format or content.
[MGBADPARMTYPE]Bad paramater structure type.
[MGBADFLAG]Bad flag.
[MGBADPRIM]Bad primitive.
[MGNOTSUPP]Primitive not supported.
[MGBADSLOT]Bad multplex slot.
mg_unix_error

Indicates the reason for failure. This field is protocol-specific. When the mg_error_type field is [MGSYSERR], the mg_unix_error field is the UNIX error number as described in errno(3).

mg_error_primitive

Indicates the primitive that was in error. This field can have one of the following values:

MG_INFO_REQInformation request.
MG_OPTMGMT_REQOptions management request.
MG_ATTACH_REQAttach request.
MG_ENABLE_REQEnable request.
MG_CONN_REQConnect request.
MG_DATA_REQData request.
MG_DISCON_REQDisconnect request.
MG_DISABLE_REQDisable request.
MG_DETACH_REQDetach Request.
MG_INFO_ACKInformation acknowledgement.
MG_OPTMGMT_ACKOptions Management acknowledgement.
MG_OK_ACKSuccessful receipt acknowledgement.
MG_ERROR_ACKError acknowledgement.
MG_ENABLE_CONEnable confirmation.
MG_CONN_CONConnect confirmation.
MG_DATA_INDData indication.
MG_DISCON_INDDisconnect indication.
MG_DISCON_CONDisconnect confirmation.
MG_DISABLE_INDDisable indication.
MG_DISABLE_CONDisable confirmation.
MG_EVENT_INDEvent indication.
mg_state

Indicates the state of the MGS provider at the time that the primitive was issued. This field can have one of the following values:

MGS_UNINITUnitialized.
MGS_UNUSABLEDevice cannot be used, Stream in hung state.
MGS_DETACHEDNo PPA attached, awaiting MG_ATTACH_REQ.
MGS_WACK_AREQWaiting for attach.
MGS_WACK_UREQWaiting for detach.
MGS_ATTACHEDPPA attached, awaiting MG_ENABLE_REQ.
MGS_WCON_EREQWaiting to send MG_ENABLE_CON.
MGS_WCON_RREQWaiting to send MG_DISABLE_CON.
MGS_ENABLEDReady for use, awaiting primitive exchange.
MGS_WACK_CREQWaiting acknowledgement of MG_CONN_REQ.
MGS_WCON_CREQWaiting to send MG_CONN_CON.
MGS_WACK_DREQWaiting acknowledgement of MG_DISCON_REQ.
MGS_WCON_DREQWaiting to send MG_DISCON_CON.
MGS_CONNECTEDConnected, active data transfer.

State

This primitive can be issued in any state for which a local acknowledgement is not pending. The MGS provider state at the time that the primitive was issued is indicated in the primitive.

New State

The new state remains unchanged.


4.1.2 Information Reporting Service Primitives

These service primitives implement the information reporting service (see Information Reporting Service).


4.1.2.1 MG_INFO_REQ

Description

This MGS user originated primitive is issued by the MGS user to request that the MGS provider return information concerning the capabilities and state of the MGS provider.

Format

The primitive consists of one M_PROTO or M_PCPROTO message block, structured as follows:

typedef struct MG_info_req {
    mg_ulong mg_primitive;
} MG_info_req_t;

Parameters

This primitive contains the following parameters:

mg_primitive

Specifies the primitive type. Always MG_INFO_REQ.

State

This primitive may be issued in any state but only when a local acknowledgement is not pending.

New State

The new state remains unchanged.

Response

This primitive requires the MGS provider to acknowledge receipt of the primitive as follows:

  • - Successful: The MGS provider is required to acknowledge receipt of the primitive and provide the requested information using the MG_INFO_ACK primitive.
  • - Unsuccessful (non-fatal errors): The MGS provider is required to negatively acknowledge the primtive using the MG_ERROR_ACK primitive, and include the reason for failure in the primitive.

Reasons for Failure

Non-Fatal Errors: applicable non-fatal errors are as follows:

[MGSYSERR]UNIX system error.
[MGBADADDR]Bad address format or content.
[MGOUTSTATE]Interface out of state.
[MGBADOPT]Bad options format or content.
[MGBADPARM]Bad parameter format or content.
[MGBADPARMTYPE]Bad paramater structure type.
[MGBADFLAG]Bad flag.
[MGBADPRIM]Bad primitive.
[MGNOTSUPP]Primitive not supported.
[MGBADSLOT]Bad multplex slot.

4.1.2.2 MG_INFO_ACK

Description

This MGS provider originated primitive acknowledges receipt and successful processing of the MG_INFO_REQ primitive and provides the requested information concerning the MGS provider.

Format

This message is formatted a one M_PROTO or M_PCPROTO message block, structured as follows:

typedef struct MG_info_ack {
    mg_ulong mg_primitive;    /* always MG_INFO_ACK */
    mg_ulong mg_addr_length;  /* media gateway address length */
    mg_ulong mg_addr_offset;  /* media gateway address offset */
    mg_ulong mg_parm_length;  /* media gateway parameters length */
    mg_ulong mg_parm_offset;  /* media gateway parameters offset */
    mg_ulong mg_prov_flags;   /* provider options flags */
    mg_ulong mg_prov_class;   /* provider class */
    mg_ulong mg_style;        /* provider style */
    mg_ulong mg_version;      /* media gateway interface version */
    mg_ulong mg_state;        /* media gateway state */
} MG_info_ack_t;

Parameters

The information acknowledgement service primitive has the following parameters:

mg_primitive

Indicates the service primitive type. Always MG_INFO_ACK.

mg_addr_length

Indicates the length of the PPA address to which the provider is attached. When in states MGS_DETACHED or MGS_WACK_AREQ, this value will be zero (‘0’).

mg_addr_offset

Indicates the offset, beginning from the start of the M_PCPROTO message block of the PPA address associated with the provider. When the mg_addr_length field is zero, this field is also zero (‘0’).

mg_parm_length

Indicates the length of the parameters associated with the provider.

mg_parm_offset

Indicates the offset, beginning from the start of the M_PCPROTO message block, of the parameters associated with the provider. When the mg_parm_length field is zero, this field is also zero (‘0’).

mg_prov_flags

Indicates the options flags associated with the provider. This is a bitwise OR of zero or more of the following flags:

mg_prov_class

Indicates the provider class. This can be one of the following values:

MG_CIRCUITCircuit provider class.
mg_addr_length

This is a variable length field. The length of the field is determined by the length attribute.

For a Style 2 driver, when mg_style is MG_STYLE2, and when in an attached state, this field provides the current PPA associated with the Stream; the length is typically 4 bytes.

For a Style 1 driver, when mg_ppa_stype is MG_STYLE1, the length is 0 bytes.

mg_style

Indicates the PPA style of the MGS provider. This value can be one of the following values;

MG_STYLE1PPA is implicitly attached by open(2s).
MG_STYLE2PPA must be explicitly attached using MG_ATTACH_REQ.
mg_version

The version of the interface. This version is MG_VERSION_1_1.

MG_VERSION_1_0Version 1.0 of interface.
MG_VERSION_1_1Version 1.1 of interface.
MG_VERSIONAlways the current version of the header file.
mg_state

Indicates the state of the MGS provider at the time that the information acknowledgement service primitive wsa issued. This field can be one of the following values:

MGS_UNINITUnitialized.
MGS_UNUSABLEDevice cannot be used, Stream in hung state.
MGS_DETACHEDNo PPA attached, awaiting MG_ATTACH_REQ.
MGS_WACK_AREQWaiting for attach.
MGS_WACK_UREQWaiting for detach.
MGS_ATTACHEDPPA attached, awaiting MG_ENABLE_REQ.
MGS_WCON_EREQWaiting to send MG_ENABLE_CON.
MGS_WCON_RREQWaiting to send MG_DISABLE_CON.
MGS_ENABLEDReady for use, awaiting primitive exchange.
MGS_WACK_CREQWaiting acknowledgement of MG_CONN_REQ.
MGS_WCON_CREQWaiting to send MG_CONN_CON.
MGS_WACK_DREQWaiting acknowledgement of MG_DISCON_REQ.
MGS_WCON_DREQWaiting to send MG_DISCON_CON.
MGS_CONNECTEDConnected, active data transfer.

State

This primitive can be issued in any state where a local acknowledgement is not pending.

New State

The new state remains unchanged.


4.1.3 Physical Point of Attachment Service Primitives

These service primitives implement the physical point of attachment service (see Physical Point of Attachment Service).


4.1.3.1 MG_ATTACH_REQ

Description

This MGS user originated primitive requests that the Stream upon which the primitive is issued be associated with the specified Physical Point of Attachment (PPA). This primitive is only applicable to Style 2 MGS provider Streams, that is, Streams that return MG_STYLE2 in the mg_style field of the MG_INFO_ACK.

Format

This primitive consists of one M_PROTO message block, structured as follows:

typedef MG_attach_req {
    mg_ulong mg_primitive;
    mg_ulong mg_addr_length;
    mg_ulong mg_addr_offset;
    mg_ulong mg_flags;
} MG_attach_req_t;

Parameters

The attach request primitive contains the following parameters:

mg_primitive

Specifies the service primitive type. Always MG_ATTACH_REQ.

mg_addr_length

Specifies the Physical Point of Attachment (PPA) to which to associate the Style 2 Stream. This is a variable length identifier whose length is determined by the mg_addr_length value. Specifies the length of the Physical Point of Attachment (PPA) address. The form of the PPA address is provider-specific.

mg_addr_offset

Specifies the offset, from the beginning of the M_PROTO message block, of the start of the Physical Point of Attachment (PPA) address.

mg_flags

Specifies the options flags for attachment. Options flags are provider-specific.

State

This primitive is only valid in state MGS_DETACHED and when a local acknowledgement is not pending.

New State

Upon success, the new state is MGS_WACK_AREQ. Upon failure, the state remains unchanged.

Response

The attach request service primitive requires that the MGS provider respond as follows:

  • - Successful: The MGS provider acknowledges receipt of the primitive and successful outcome of the attach service with a MG_OK_ACK primitive. The new state is MGS_ATTACHED.
  • - Unsuccessful (non-fatal errors): The MGS provider acknowledges receipt of the primitive and failure of the attach service with a MG_ERROR_ACK primitive containing the reason for failure. The new state remains unchanged.

Reasons for Failure

Non-Fatal Errors: applicable non-fatal errors are as follows:

[MGSYSERR]UNIX system error.
[MGBADADDR]Bad address format or content.
[MGOUTSTATE]Interface out of state.
[MGBADOPT]Bad options format or content.
[MGBADPARM]Bad parameter format or content.
[MGBADPARMTYPE]Bad paramater structure type.
[MGBADFLAG]Bad flag.
[MGBADPRIM]Bad primitive.
[MGNOTSUPP]Primitive not supported.
[MGBADSLOT]Bad multplex slot.

4.1.3.2 MG_DETACH_REQ

Description

This MGS user originated primitive requests that the Stream upon which the primitive is issued be disassociated from the Physical Point of Appearance (PPA) to which it is currently attached. This primitive is only applicable to Style 2 MGS provider Streams, that is, Streams that return MG_STYLE2 in the mg_style field of the MG_INFO_ACK.

Format

The detach request service primitive consists of one M_PROTO message block, structured as follows:

typedef struct MG_detach_req {
    mg_ulong mg_primitive;
} MG_detach_req_t;

Parameters

The detach request service primitive contains the following parameters:

mg_primitive

Specifies the service primitive type. Always MG_DETACH_REQ.

State

This primitive is valid in the MGS_ATTACHED state and when no local acknowledgement is pending.

New State

Upon success, the new state is MGS_WACK_UREQ. Upon failure, the state remains unchanged.

Response

The detach request service primitive requires that the MGS provider respond as follows:

  • - Successful: The MGS provider acknowledges receipt of the primitive and successful outcome of the detach service with a MG_OK_ACK primitive. The new state is MGS_DETACHED.
  • - Unsuccessful (non-fatal errors): The MGS provider acknowledges receipt of the primitive and failure of the detach service with a MG_ERROR_ACK primitive containing the reason for failure. The new state remains unchanged.

Reasons for Failure

Non-Fatal Errors: applicable non-fatal errors are as follows:

[MGSYSERR]UNIX system error.
[MGBADADDR]Bad address format or content.
[MGOUTSTATE]Interface out of state.
[MGBADOPT]Bad options format or content.
[MGBADPARM]Bad parameter format or content.
[MGBADPARMTYPE]Bad paramater structure type.
[MGBADFLAG]Bad flag.
[MGBADPRIM]Bad primitive.
[MGNOTSUPP]Primitive not supported.
[MGBADSLOT]Bad multplex slot.

4.1.4 Initialization Service Primitives

Initialization service primitives allow the MGS user to enable or disable the protocol service interface. Enabling the protocol service interface may require that some action be taken to prepare the protocol service interface for use or to remove it from use. For example, where the PPA corresponds to a multiplex identifier as defined in G.703, it may be necessary to perform switching to connect or disconnect the circuit identification code associated with the multiplex identifier.

These service primitives implement the initialization service (see Initialization Service).


4.1.4.1 MG_ENABLE_REQ

Description

This MGS user originated primitive requests that the MGS provider perform the actions necessary to enable the protocol service interface and confirm that it is enabled. This primitive is applicable to both styles of PPA.

Format

The enable request service primitive consists of one M_PROTO message block, structured as follows:

typedef struct MG_enable_req {
    mg_ulong mg_primitive;
    mg_ulong mg_addr_length;
    mg_ulong mg_addr_offset;
    mg_ulong mg_flags;
} MG_enable_req_t;

Parameters

The enable request service primitive contains the following parameters:

mg_primitive

Specifies the service primitive type. Always MG_ENABLE_REQ.

mg_addr_length

Specifies a remote address to which to connect the PPA. The need for and form of this address is provider-specific. The length of the field is determined by the value of this field. This remote address could be a circuit identification code, an IP address, or some other form of circuit or multiplex identifier.

mg_addr_offset

Specifies the offset, from the beginning of the M_PROTO message block, of the start of the remote address.

mg_flags

Specifies the options flags associated with the enable request. Options flags are provider-specific.

State

This primitive is valid in the MGS_ATTACHED state and when no local acknowledgement is pending.

New State

Upon success the new state is MGS_WCON_EREQ. Upon failure, the state remains unchanged.

Response

The enable request service primitive requires that the MGS provider acknowledge receipt of the primitive as follows:

  • - Successful: When successful, the MGS provider acknowledges successful completion of the enable service with a MG_ENABLE_CON primitive. The new state is MGS_ENABLED.
  • - Unsuccessful (non-fatal errors): When unsuccessful, the MGS provider acknowledges the failure of the enable service with a MG_ERROR_ACK primitive containing the error. The new state remains unchanged.

Reasons for Failure

Non-Fatal Errors: applicable non-fatal errors are as follows:

[MGSYSERR]UNIX system error.
[MGBADADDR]Bad address format or content.
[MGOUTSTATE]Interface out of state.
[MGBADOPT]Bad options format or content.
[MGBADPARM]Bad parameter format or content.
[MGBADPARMTYPE]Bad paramater structure type.
[MGBADFLAG]Bad flag.
[MGBADPRIM]Bad primitive.
[MGNOTSUPP]Primitive not supported.
[MGBADSLOT]Bad multplex slot.

4.1.4.2 MG_ENABLE_CON

Description

This MGS provider originated primitive is issued by the MGS provider to confirm the successful completion of the enable service.

Format

The enable confirmation service primitive consists of one M_PROTO message block, structured as follows:

typedef struct MG_enable_con {
    mg_ulong mg_primitive;
    mg_ulong mg_addr_length;
    mg_ulong mg_addr_offset;
    mg_ulong mg_flags;
} MG_enable_con_t;

Parameters

The enable confirmation service primitive contains the following parameters:

mg_primitive

Indicates the service primitive type. Always MG_ENABLE_CON.

mg_addr_length

Confirms the length of the remote address to which the enable is confirmed.

mg_addr_offset

Confirms the offset, from the beginning of the M_PROTO message block, of the start of the remote address.

mg_flags

Confirms the options flags associated with the enable confirmation. Options flags are provider-specific.

State

This primitive is issued by the MGS provider in the MGS_WCON_EREQ state.

New State

The new state is MGS_ENABLED.


4.1.4.3 MG_DISABLE_REQ

Description

This MGS user originated primitive requests that the MGS provider perform the actions necessary to disable the protocol service interface and confirm that it is disabled. The primitive is applicable to both styles of PPA.

Format

The disable request service primitive consists of one M_PROTO message block, structured as follows:

typedef struct MG_disable_req {
    mg_ulong mg_primitive;
} MG_disable_req_t;

Parameters

The disable request service primitive contains the following