• RFC3435 Media Gateway Control Protocol

• Jain MGCP provider and Resource Adaptor

• RFC3435 Media Gateway Control Protocol^?

• How to install Media gateway
• How to install Media gateway control protocol modules
• Jain MGCP
• MGCP Resource Adaptor

INTRODUCTION

Media gateways were introduced to interwork with traditional telephony systems and enable support of large phone-to-phone deployments. In traditional telephone systems, signaling (D-channel) and media (B-channel) are carried separately. In VoIP networks, each needs to be handled by a different type of entities: a Signaling Call State Control Function (CSCF) and a Media Gateway (MGW). Signaling Gateways translate the D-channel data to VoIP-compatible signaling protocols, such as ISUP-over-IP, SIP or H.323, and do not involve media gateway control protocols. Media Gateways provide the bridge for media to seamlessly transit between PSTN and VoIP networks by ferrying media between B-channels and RTP streams.

There is a fundamental difference between SIP and H.323 and media gateway control protocols. SIP and H.323 are signaling protocols that set up and manage calls, whereas media gateway control protocol define how media streams are set up and establish media paths between IP and other networks.

ENDPOINT

It is convinient to consider media gateway as a collection of endpoints. An Endpoint is a logical representation of a physical entity, such as an analog phone or a channel in a trunk. Endpoints are sources or sinks of data and can be physical or virtual. Physical Endpoint creation requires hardware installation while software is sufficient for creating a virtual Endpoint. An interface on a gateway that terminates a trunk connected to a PSTN switch is an example of a physical Endpoint. An audio source in an audio-content server is an example of a virtual Endpoint.

Basic Implementation

public interface EndpointMBean  extends ServiceMbean {
     public void setConfiguration(Properties conf);
     public Properties getConfiguration();
}

From other side, the intelligence of the call control is outside the gateways and handled by external call control elements. This mean that a master/slave protocol should be involved, where the gateways are expected to execute commands sent by the call control elements. Command processor executed control commands can be presented as an interface (MGCP for example).

public interface MgcpCommandProcessor  {
     ....
    // MGCP specific methods 
}

So, the basic representation of an endpoint will looks like (for MGCP example):

public abstract class Endpoint extends ServiceMBeanSupport 
        implements EndpointMBean, MgcpCommandProcessor  {
   // configuration properties of this endpoint */
   private Properties config;
   
   //collection of the connections
   private HashMap connections = new HashMap();
   ...

   /**
    * Modify properties of this endpoint.
    *
    * @param config the properties object.
    */
   public void setConfiguration(Properties config) {
          this.config = config;
   }

   /**
    * Returns properties of this endpoint.
    *
    * @return  the properties object.
    */
   public Properties getConfiguration() {
          return config;
   } 
   
           ....
    // MGCP  implementation
}

The actual class representing an endpoint is derived from the class Endpoint and overrides methods startService() and stopService() to establish comminication with hardware. For example the class which represent a channel in a trunk may looks like:

public  class BChannel extends Endpoint    {

   /**
    * Starts this endpoint and attaches to a B-Channel configured
    *
    */
   public void startService() {
          //load native driver of the PSTN card and prepare B-channel specified in
         //a configuration for input/output
   }

   /**
    * Closes this endpoint. 
    */
   public Properties stopService() {
              // close channel and free all resources
   } 
   
           ....
}

Configuration Entry

<server> 
   <mbean code="org.mobicents.media.digium.BChannel" 
               name="org.mobicents:service=ds0/s0/c1">
                      <attribute name="Configuration">
                                   ...
                      </attribute> 
   </mbean> 
</sever>

Naming conventions

As specified in the MGCP specification the syntax of the local endpoint name is hierarchical, where the least specific component of the name is the leftmost term,and the most specific component is the rightmost term. The name depends on the type of endpoint being named. The individual terms of the naming path should be separated by a single slash. The symbols * and $ could not be used as part of the name and use as wildcard symbols for searching endpoints. An asterisk sign means "all" and dollar sign means "any".

CONNECTION

public abstract class Connection  {
   ....
    private String id;
    private int mode;
    private String localDescriptor; 
    private String remoteDescriptor;
    private Connection remoteConnection;
}

Here local and remote descriptors are used to specify parties for RTP stream using Session Description Protocol - localDescriptor reprsents the connection itself and remoteDescriptor represents remote party. Attributes remoteDescriptor and remoteConnection are mutually exclusive and determine the type of the communication (RTP, or DataSource^?). If none of these attributes are provided then a connection is "half" opened.

Each endpoint also should override methods used for managing connections:

public abstract class Endpoint extends ServiceMBeanSupport 
        implements EndpointMBean, MgcpCommandProcessor  {
            ....
            public abstract Connection createConnection(String callID, int mode) 
                          throws TooManyConnections;
            public abstract Connection getConnection(String connectionID) 
                          throws ConnectionNotFound;
            public abstract void deleteConnection(Connection connection);

}

CALL

Connections are created on each endpoint that will be involved in the "call". The connections identifiers is unique within a call. The creation of the connections is done via the three following steps:

1. Call Controller chooses appropriate endpoint and asks the gateway to "create a connection" . The gateway acquire specified endpoint, initialze JMF's processor, create RTPManager and respond to command by providing the local connection descriptor as specified by SDP.
2. Call Contoller ask the gateway to acquire the second endpoint and creates a second connection. Call Controller includes connection descriptor of the first connection into the request. Second endpoint apply provided connection descriptor as remoteDescriptor and respond to request by providing it own connection descriptor.
3. Call Controller "modify connection" to provide the second connection description for the first connection

EVENTS

A Call Conroller may ask to be notified about certain events occurring in an endpoint or connection (e.g., dtmf events) by including the name of the event in a command. The gateway uses the standard Java listener mode to detect some events. When an endpoint receives the command which requests notification, the new instance of the appropriate listener is created and added to endpoint or to connection. The class which represents the basic listener implements the delivery procedure of the event to Call Controller.

public abstract class BaseListener   {
            ....
      public BaseListener(Call call)  {
         ...
      }
}

CONTROL PROTOCOL

<server> 
   <mbean code="org.mobicents.media.control.MgcpProvider" 
               name="org.mobicents:service=MgcpProvider">
                      <attribute name="Configuration">
                                   ...
                      </attribute> 
   </mbean> 
</sever>

RESOURCE ADAPTOR

Resource adaptor type identifier

Activity object.

Events

Event types

Event classes.

Activity Context Interface Factory Interface

import javax.slee.ActivityContextInterface;
import javax.slee.FactoryException;
import javax.slee.UnrecognizedActivityException;

public interface RadiusActivityContextInterfaceFactory {
    public ActivityContextInterface getActivityContextInterface(Call)
        throws NullPointerException, UnrecognizedActivityException, FactoryException;
    
    public ActivityContextInterface getActivityContextInterface(Connection)
        throws NullPointerException, UnrecognizedActivityException, FactoryException;

    public ActivityContextInterface getActivityContextInterface(Endpoint)
        throws NullPointerException, UnrecognizedActivityException, FactoryException;

}

Resource Adaptor object

EXAMPLES

Personal Ringback Tone

In terms of the SIP signaling protocol it means that call controller should catch Ringning message and setup an earlier media session for calling party, from one hand, and media gateway which will play sound files from other. When called party answers, the call controller should drop this media session and join parties. Lets use the MGCP RA to create manage media sessions. As mentioned above, all MGCP commands are executed per endpoint basis. It means that developers should know the configuration of the media gateway will be used. For this application announcement endpoint's fatures will be enough. Mgcp assumes that endpoint name is consist of two parts: local name and domain name. The local name is a name of the endpoint within media gateway and is same as Mbean name for us. Domain name may be specified as host name or ip address, port number can be included also. This part of the MGCP endpoint's name used by MGCP provider to deliver message to the gateway.

For PRBT application there is no matter which concrete announcement endpoint will execute commands, so the name of the endpoint for the first CreateConnection^? message can be wildcarded. We can't use "all" wildcard symbol, but "any" symbol can be used. The gateway will determine the appropriate endpoint to execute CreateConnection^? and then will return concrete endpoint's name in the response.

public void onRingningEvent(RequestEvent event, ActivityContextInterface aci) {
         ....
         //prepare mgcp create connection message         
        EndpointIdentifier endpoint = new EndpointIdentifier("ann/$",
                          "mediagateway.mobicents.org");
}

There are the activity objects declared for MGCP RA. These objecs can be used to create an ActivityContextInterface^?. Obtain ActivityContextInterfaceFactory^? and attach this SBB to receive response

public void onRingningEvent(RequestEvent event, ActivityContextInterface aci) {
     Call call = new Call(callIdHeader); //activity object
     CallIdentifier callIdentifier = new CallIdentifier(call.getID());

     ActivityContextInerfaceFactory acif = (ActivityConextInterfaceFactory) 
         context.lookup( "slee/resources/mgcp/ActivityContextInterface");
    ActivityContextInterface ac = acif.getActivityContextInterfface(call);
    ac.attach(this)
     
}

Prepare CreateConnection^? message: provide session descriptor of the calling party presented in the Invaite message, and create the "equest event" to media gateway with instruction to play file from specified URL and notify imediately when file will finished. Then obtain provider object and send message to the gateway.

public void onRingningEvent(RequestEvent event, ActivityContextInterface aci) {
         ....
        ConnectionDescriptor desc = new ConnectionDescriptor(sdp);
        try {
            createConnection.setRemoteConnectionDescriptor(desc);
        } catch (ConflictingParameterException e) {
            //should never happen
        }
        
        EventName eventName = new EventName(PackageName.Announcement,
                MgcpEvent.ann.withParm("http://user.domain.com/ringbacktone.wav"));
        RequestedEvent event = new RequestedEvent(eventName,
                new RequestedAction[]{RequestedAction.NotifyImmediately});
        NotificationRequestParms request = new NotificationRequestParms(
                        new RequestIdentifier(Integer.toString(GEN++)));
        request.setRequestedEvents(new RequestedEvent[]{event});
        createConnection.setNotificationRequestParms(request);

        JainMgcpProvider provider =  (JainMgcpProvider) context.lookup(
                      "slee/resources/mgcp/factoryprovider");
        provider.send(new JainMgcpCommand[]{createConnection});
     
}

The gateway will respond with CreateConnectionResponse^? message which will include the concrete name of the endpoint acquired by gateway, the idebtifier of the connection created and local (for this connection) session descriptor. We should use this session descriptor in the SESSION_PROGRESS SIP message to establish an earlier media session.

public void onCreateConnectionResp(JainMgcpResponseEvent evt, 
    ActivityContextInterface aci) {
         ....
        CreateConnectionResponse res = (CreateConnectionResponse) evt;
        String sdp = res.getLocalConnectionDescriptor().toString();

        //hold specific parameters for future use
        Endpoint endpoint = res.getSpecificEndpointIdentifier();
        ConnectionIdentifier connectionID = res.getConnectionIdentifier();
 
        //generate SESSION_PROGRESS message.
        //using sdp of the connection
}

At this time calling party hear ringback tone while called party alerting. When the specified ringback tone finishes, the gateway will send notify message (as requested) This event may be used to repeat ringback tone from the begining or send Ringning event if some thing fail.

public void onNotify(JainMgcpCommandEvent evt, ActivityContextInterface aci) {
         ....
       Notify notify = (Notify) evt;
       eventName = notify.getObservedEvents()[0];
       if (eventName.getEventIdentifier().equals(MgcpEvent.of)) {
            //faile to play a file
            //generate Ringin message    
       } else if (eventName.getEventIdentifier().equals(MgcpEvent.of)) {
           //send NotifyRequest to play file again
           EventName eventName = new EventName(PackageName.Announcement,
                MgcpEvent.ann.withParm("http://user.domain.com/ringbacktone.wav"));
           RequestedEvent event = new RequestedEvent(eventName,
                new RequestedAction[]{RequestedAction.NotifyImmediately});
           NotificationRequest req = new NotificationRequest(this, 
                    endpoint, 
                    new RequestIdentifier( new Integer(GEN++).toString());
          req.setRequestedEvents(RequestedEvent[]{event});
          provider.send(new JainMgcpCommandEvent[]{req});
          ..
       } 
         
}

When called party answers, SBB shout catch OK message and drop the media session.

public void onOkEvent(RequestEvent event, ActivityContextInterface aci) {
         ....
         DeleteConnection dc = new DeleteConnection(this, endpoint);
         provider.send(new JainMgcpCommandEvent[]{dc});
}

Now subscribers hear each other.

Event classes. The JAIN MGCP define an event class for all avents.

EXAMPLES

Call

• Introduction
• Endpoints

Connections

IVR endpoint

Conference bridge

Control protocol

Resource Adaptor

Example application

There is a fundamental difference between SIP and H.323 and media gateway control protocols. SIP and H.323 are signaling protocols that set up and manage calls, whereas media gateway control protocols define how media streams are set up and establish media paths between IP and other networks. It is convinient to consider media gateway as a collection of endpoints.

• Introduction
• Endpoints

Media gateways were introduced to interwork with traditional telephony systems and enable support of large phone-to-phone deployments. In traditional telephone systems, signaling (D-channel) and media (B-channel) are carried separately. In VoIP networks, each needs to be handled by a different type of entities: a Signaling Call State Control Function (CSCF) and a Media Gateway (MGW). Signaling Gateways translate the D-channel data to VoIP-compatible signaling protocols, such as ISUP-over-IP, SIP or H.323, and do not involve media gateway control protocols. Media Gateways provide the bridge for media to seamlessly transit between PSTN and VoIP networks by ferrying media between B-channels and RTP streams. CSCF control Media Gateways by means of a media gateway control protocol.

public Connection getConnection(String connectionID) throws ConnectionNotFound^? { if (connections.containsKey(connectionID) { return (Connection) connections.get(connectionID); } else throw new ConnectionNotFoundException^?("Connection not found: " + connectionID)); }

Endpoints

org.mobicents.media.Endpoint