Media Gateway (MG) Stack

MG(4) provides an introductory manual page for MG Switching stack components and interfaces. You can also select one of the component or interface sections from the diagram below:

Components

Interfaces

Components

MG Stack Manager (MGLM)

This section provides a roadmap to Manual Pages for Voice over IP (VoIP) Stack Manager (VoIP SM).

Media Gateway (MG)

This section provides a roadmap to Manual Pages for Media Gateway (MG).

H.248/MEGACO

This section provides a roadmap to Manual Pages for Media Gateway Control (H.248/MEGACO).

Media Gateway Control Protocol (MGCP)

This section provides a roadmap to Manual Pages for Media Gateway Control Protocol (MGCP).

Channel Driver

This section provides a roadmap to Manual Pages for Multiplex/Channel (MX/CH).

Real-Time Transport Protocol (RTP)

This section provides a roadmap to Manual Pages for Real-Time Transport Protocol (RTP).

MGI

Section: Media Gateway Interface (MGI) (7)
Updated: 2008-10-31
Index Return to Main Contents

NAME

mgi - Media Gateway Interface

SYNOPSIS

#include <ss7/mgi.h>
#include <ss7/mgi_ioctl.h>

int mg_stream = open(mg_device, flags);

DESCRIPTION

The Media Gateway Interface, MGI, specifies a STREAMS(4)-based kernel-level instantiation of a Media Gateway Control interface definition compatible with SGCP, MGCP, MEGACO H.248.1, ITU-T H.245, and other media control and switching protocols. The Media Gateway Interface (MGI) enables the user of a media gateway service to access and use any variety of conforming media gateway control service providers without specific knowledge of the provider's protocol. The service interface is designed to support any media gateway control service providers, and does not address issues concerning media gateway circuit management, protocol performance, and performance analysis tools. The specification assumes that the reader is familiar with the ITU-T state machines and media gateway control interface (e.g. H.248.1), and STREAMS(4).

MGI specifies an interface that supports the services provided by the Media Gateway Control Protocol (MGCP), mgcp(4), ITU-T H.248.1 Media Gateway Control (MEGACO), h248(4), and local media switching using the Media Gateway drivers, mg(4). See MG(4) for a description of appropriate drivers and auxiliary modules. These specifications are targeted for use by developers and testers of protocol modules that require media gateway control service.

The Media Gateway Control Layer

The Media Gateway Control Layer provides the means to manage the connection and disconnection of channels (or termination points) within multi-party communications sessions. It is a local control protocol in the sense that there are no remote peers entities. Communications is between the local user entity and the local provider entity only.

Model of the MGI

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

The MGI allows the MG to be configured with any media gateway controller (such as ISDN or H.225.0 call control) that also conforms to the MGI. A media gateway controller can also be a user program (such as the OpenSwitch call framework) that conforms to the MGI and accesses the MG via putmsg(2) and getmsg(2) system call.s

MGI Services: The features of the MGI are defined in terms of services provided by the MG, and the individual primitives that may flow between the MGC and the MG.
Local Management: The MGI specification also defines a set of local management functions. These services have significance only to the local stream.

Tables 1, 2 and 3 summarizes the MGI service primitives by their state and service.

MGI SERVICES DEFINITION

The MGI services are categorized as Local Management Services, Session Services, Connection Services, Action Services, Event Services or Media Services as follows:

Local Management Services

The media gateway provides the following local management services:

Information Serivce The information service provides the media gateway controller with the ability to query the media gateway concerning options and parameters specific to the media gateway and associated with attached multiplex and channels. The information service uses the following primitives:

---: MG_INFO_REQ(7): Requests information about the associated media gateway session and attached channels. This primitive requires local acknowledgment with the MG_INFO_ACK(7) primitive.
---: MG_INFO_ACK(7): Indicates information about the associated media gateway session and attached channels.

Options Management Service. The options management service provides a mechanism whereby the media gateway controller can query and change parameters associated with the attached channels and manage options associated with the media gateway. The options management service uses the following primitives:

---: MG_OPTMGMT_REQ(7): Requests management of the specified options. This primitive requires local acknowledgment with the MG_OPTMGMT_ACK(7) primitive.
---: MG_OPTMGMT_ACK(7): Acknowledges that the management of previously specified options is complete.

Channel Attachment Service. The channel attachement service provides the media gateway controller with the ability to attach a specified channel to a participant slot in the session associated with the requesting stream. The channel attachement service uses the following primitives:

---: MG_ATTACH_REQ(7): Requests that the specified channels be attached to the specified participant slots within the specified media gateway session. This primitive requires local acknowledgment with the MG_ATTACH_ACK(7) primitive.
---: MG_ATTACH_ACK(7): Acknowledges successful attachment of the indicated channels to the indicated participant slots within the indicated media gateway session.

Channel Detachment Service. The channel detachment service provides the media gateway controller with the ability to detach a specified channel from a participant slot in the session associated with the requesting stream. The channel detachment service uses the following primitives:

---: MG_DETACH_REQ(7): Requests that the specified channels be detached from the media gateway session to which they are currently attached. This primitive requires local acknowledgment with the MG_OK_ACK(7) primitive.
---: MG_OK_ACK(7): Acknowledges successful receipt of the channel detach request primitive.

Receipt Acknowledgement Service. The receipt acknowledgement service provide an indication to the media gateway controller of the positive or negative acknowledgment of the previous primitive issued by the media gateway controller requiring local acknowledgment. The receipt acknowledgment service uses the following primitives:

---: MG_OK_ACK(7): Acknowledges the successful receipt and processing of the previous request primitive for which a local acknowledgment is outstanding, that has no other means of local acknowledgment.
---: MG_ERROR_ACK(7): Acknowledges the unsuccessful (non-fatal error) receipt of the previous request primitive for which a local acknowledgment is outstanding.

Session Services

The media gateway provides the following session services:

Session Join Service. The session join service provides the media gateway controller with the ability to add a participant to the session associated with the requesting stream, or any other session under the control of the media gateway. The session join service uses the following primitives:

---: MG_JOIN_REQ(7): Requests that the specified channels join the specified media gateway communications session at the specified termination point (participant slot).
---: MG_JOIN_CON(7): Confirmst that the indicated channels have joined the indicated media gateway communication session at the indicated termination point (participant slot).

Session Leave Service. The session leave service provides the media gateway controller with the ability to remove a participant from the session associated with the requesting stream, or any other session under the control of the media gateway. In addition, it is possible that an autonomous exit from a communication session occurs without the request of the media gateway controller. In this case, the session leave service is used to indicated to the media gateway controller that an autonomous exit from the communications session has occurred. The session leave service uses the following primitives:

---: MG_LEAVE_REQ(7): Requests that the specified termination point (participant) leave the specified media gateway communications session.
---: MG_LEAVE_CON(7): Confirms that the indicated termination point (participant) has left the indicated media gateway communication session.
---: MG_LEAVE_IND(7): Indicats that the indicated termination point (participant) has autonomously left the indicated media gateway communications session.

Connection Services

The media gateway provides the following connection services:

Media Connection Service. The media connection service provides the media gateway controller with the ability to connect a channel in the receive and/or transmit directions within a joined session. The media connection service uses the following primitives:

---: MG_CONN_REQ(7): Requests that the specified termination point (participant) be connected into the specified media gateway communications session in the transmit or receive directions, or with the specified topology, and with the specified digital padding.
---: MG_CONN_CON(7): Confirms that the indicated termination point (participant) has been connected into the indicated media gateway communications session in the directions indicated, or with the topology indicated.

Media Disconnection Service. The media disconnection service provides the media gateway controller with the ability to disconnect a channel from the receive and/or transmit directions within a joined session. In addition, it is possible that an autonomous disconnect from a communications session occurs without the request of the media gateway controller. In this case, the media disconnection service is used to indicate to the media gateway controller that an autnomous disconnect from the communications session has occured. The media disconnection service uses the following primitives:

---: MG_DISCON_REQ(7): Requests that the specified termination point (participant) be disconnected from the specified media gateway communications session in the directions specified, or with the topology specified.
---: MG_DISCON_CON(7): Confirmst that the indicated termination point (participant) has been disconnected from the indicated media gateway communications session in the directions indicated, or with the topology indicated.
---: MG_DISCON_IND(7): Indicates that the indicated termination point (participant) has autonomously disconnected from the indicated media gateway communications session in the directions indicated, or with the topology indicated.

Action Services

The media gateway provides the following action services:

Termination Point Action Service. The action service provides the media gateway controller with the ability to perform a specified action on a specified channel within a joined session. The termination point action service uses the following primitives:

---: MG_ACTION_REQ(7): Requests that the specified action be invoked on the specified termination point (participant) in the specified communications session.
---: MG_ACTION_CON(7): Confirmst that the indicated action has begun.
---: MG_ACTION_IND(7): Indicates that the indicated action has completed.

Termination Point Action Abort Service. The action abort service provides the media gateway controller with the ability to abort a previously invoked action on a channel associated with a joined session. The termination point action abort service uses the following primitives:

---: MG_ABORT_REQ(7): Requests that the specified action be aborted.

Event Services

The media gateway provides the following event services:

Termination Point Notification Service. The event service provides the media gateway with the ability to indicate to the media gateway controller when an event has occurred. The termination point notificiation service uses the following primitives:

---: MG_NOTIFY_REQ(7): Requests that the specified events generate an event notification.
---: MG_NOTIFY_IND(7): Indicates that the event for which notification was requested has occurred.

Media Services

The media gateway provides the following media services:

Data Transfer Service. The data transfer service is used by the media gateway controller to request the transmission of session media data on the specified channel within a joined session. It is also used by the media gateway to indicate the reception of session media data on the indicated stream. The data transfer service uses the following primitives:

---: MG_DATA_REQ(7): Requests that the specified media data be transmitted to the communications session on the multiplex slot associated with the requesting stream.
---: MG_DATA_IND(7): Indicates that the indicated media data was received from the communications session on the indicated multiplex slot associated with the stream upon which the indication was issued.

OPTIONS

typedef struct MG_channel_opt {
    ulong mg_obj_type;          /* always MG_OBJ_TYPE_CH */
    ulong mg_obj_id;            /* channel id */
    ulong ch_type;              /* channel media type */
    ulong ch_flags;             /* channel media options flags */
    ulong ch_block_size;        /* data block size (bits) */
    ulong ch_encoding;          /* encoding */
    ulong ch_sample_size;       /* sample size (bits) */
    ulong ch_rate;              /* clock rate (Hz) */
    ulong ch_tx_channels;       /* number of tx channels */
    ulong ch_rx_channels;       /* number of rx channels */
    ulong ch_opt_flags;         /* options flags */
} MG_channel_opt_t;
typedef struct MG_connleg_opt {
    ulong mg_obj_type;          /* always MG_OBJ_TYPE_LG */
    ulong mg_obj_id;            /* channel id */
    ulong lg_type;              /* conn leg media type */
    ulong lg_flags;             /* conn leg media options flags */
    ulong lg_block_size;        /* data block size (bits) */
    ulong lg_encoding;          /* encoding */
    ulong lg_sample_size;       /* sample size (bits) */
    ulong lg_rate;              /* clock rate (Hz) */
    ulong lg_tx_channels;       /* number of tx channels */
    ulong lg_rx_channels;       /* number of rx channels */
    ulong lg_opt_flags;         /* options flags */
} MG_connleg_opt_t;
typedef struct MG_session_opt {
    ulong mg_obj_type;          /* always MG_OBJ_TYPE_SE */
    ulong mg_obj_id;            /* session id */
    ulong se_type;              /* session media type */
    ulong se_flags;             /* session media options flags */
    ulong se_block_size;        /* data block size (bits) */
    ulong se_encoding;          /* encoding */
    ulong se_sample_size;       /* sample size (bits) */
    ulong se_rate;              /* clock rate (Hz) */
    ulong se_tx_channels;       /* number of tx channels */
    ulong se_rx_channels;       /* number of rx channels */
    ulong se_opt_flags;         /* options flags */
} MG_session_opt_t;
#define SEF_INTERWORKING        0x01    /* encoding interworking */
#define SEF_CONFERENCING        0x02    /* conferencing in effect */
#define SEF_CLEARCHANNEL        0x04    /* clear channel enforced */
typedef union MG_options {
    struct {
        ulong mg_obj_type;      /* object type */
        ulong mg_obj_id;        /* object id */
    } obj;
    struct MG_channel_opt ch;   /* channel options */
    struct MG_connleg_opt lg;   /* conn leg options */
    struct MG_session_opt se;   /* session options */
} MG_options_t;
#define MG_SE_OPT_AUTO_GAIN_CONTROL     0x01    /* perform Automatic Gain Control */
#define MG_SE_OPT_LIMITING              0x02    /* perform limiting */
#define MG_SE_OPT_COMPRESSION           0x04    /* perform compression */

CAVEATS

This documentation is not complete and needs some work before it is finalized.

FILES

The Media Gateway Interface (MGI) is defined in the <sys/mgi.h> and <sys/mgi_ioctl.h> header files. Additional header files are specified by specific providers of the MGI interface.

DEVICES

The Media Gateway Interface (MGI) does not provide any devices of its own. Specific providers of the interface will provide their own devices.

MODULES

Some generic STREAMS(4) modules can be provided that convert between the MGI interface and other interfaces (such as the CHI).

VERSIONS

This manpage was written for MGI Version 1.

REFERENCES

[1]: MGI Revision 1.0.0, Media Gateway Interface (MGI) Specification, Draft 1, May 2003, (Edmonton), B. Bidulock, OpenSS7 Corporation. <http://www.openss7.org/docs/mgi.pdf>
[2]: RFC 3435, Media Gateway Control Protocol (MGCP) Version 1.0, January 2003, F. Andreasen, ed., The Internet Society. <http://www.ietf.org/rfc/rfc3435.txt>
[3]: ITU-T Recommendation H.248.1, Gateway Control Protocol Version 1, March 2002, ITU, ITU-T Telecommunication Standardization Sector of ITU. <http://www.itu.int/rec/T-REC-H.248/>