JBoss.orgCommunity Documentation

Mobicents MTP Library User Guide

by Amit Bhayani, Bartosz Baranowski, and Oleg Kulikov

Abstract

This User Guide introduces SS7 MTP Stack.


This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:

The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.

Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:

The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.

Note the > shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the main menu bar' approach.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in the the Issue Tracker, against the product Mobicents MTP Library , or contact the authors.

When submitting a bug report, be sure to mention the manual's identifier: MTPLibrary_User_Guide

If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

Common Channel Signaling System No. 7 (i.e., SS7 or C7) is a global standard for telecommunications defined by the International Telecommunication Union (ITU) Telecommunication Standardization Sector (ITU-T) . The standard defines the procedures and protocol by which network elements in the public switched telephone network (PSTN) ) exchange information over a digital signaling network to effect wireless (cellular) and wireline call setup, routing and control. The ITU definition of SS7 allows for national variants such as the American National Standards Institute (ANSI) and Bell Communications Research (Telcordia Technologies) standards used in North America and the European Telecommunications Standards Institute ( ETSI ) standard used in Europe.

The hardware and software functions of the SS7 protocol are divided into functional abstractions called "levels". These levels map loosely to the Open Systems Interconnect (OSI) 7-layer model defined by the International Standards Organization (ISO) .

SS7 Stack overview

  1. Downloading the source code

    Use SVN to checkout a specific release source, the base URL is http://mobicents.googlecode.com/svn/tags/protocols/mtp, then add the specific release version, lets consider 1.0.0.BETA3.

    [usr]$ svn co http://mobicents.googlecode.com/svn/tags/protocols/mtp/1.0.0.BETA3 mtp-1.0.0.BETA3
  2. Building the source code

    Important

    Maven 2.0.9 (or higher) is used to build the release. Instructions for using Maven2, including install, can be found at http://maven.apache.org

    Use Maven to build the binaries.

    				    [usr]$ cd mtp-1.0.0.BETA3
    				    [usr]$ mvn install
    				    

    Once the process finishes you should have the binary jar files in the target directory of module.

Similar process as for Section 2.2.1, “Release Source Code Building”, the only change is the SVN source code URL, which is http://mobicents.googlecode.com/svn/trunk/protocols/mtp.

Important

Be aware, Mobicents MTP Library is subject to changes as it is under active development!

This module builds layer on top of hardware signaling devices. It allows top level protocols to use its API regardless of used device. Top overview of logical components is depicted on diagram below:

MTP layer is built with several components. Following list those that may be directly involved in creating application on top of this stack:

org.mobicents.protocols.ss7.mtp.Mtp1

This interface is implemented by classes directly interacting with SS7 hardware. It declares utility methods to open/close underlying implementations and generic read/write methods. It is decalred as follows:



package org.mobicents.protocols.ss7.mtp;
import java.io.IOException;
public interface Mtp1 {
    /**
     * Gets the code of this channel.
     * 
     * @return the code of this channel.
     */
    public int getCode();
    /**
     * Set MTP2 layer serving this MTP1
     * 
     * @param link
     */
    public void setLink(Mtp2 link);
    /**
     * Get MTP2 latyer serving this MTP1
     * 
     * @return
     */
    public Mtp2 getLink();
    /**
     * Reads up to buffer.length bytes from layer 1.
     * 
     * @param buffer
     *            reader buffer
     * @return the number of actualy read bytes.
     */
    public int read(byte[] buffer) throws IOException;
    /**
     * Writes data to layer 1.
     * 
     * @param buffer
     *            the buffer containing data to write.
     * @param bytesToWrite
     */
    public void write(byte[] buffer, int bytesToWrite) throws IOException;
    /**
     * Open message tranfer part layer 1.
     */
    public void open() throws IOException;
    /**
     * Close message tranfer part layer 1.
     */
    public void close();
}
                    
org.mobicents.protocols.ss7.mtp.SelectorFactory

This is simple factory interface with one method: public ChannelSelector getSelector(); . This method returns concrete implementation of interface used for I/O select operations. Implementation is tied directly to layer 1 interface implementation. Concrete factory class should be provide along it.

It is defined as follows:



package org.mobicents.protocols.ss7.mtp;
import java.util.Collection;
public interface ChannelSelector {
    /**
     * Register specfield channel for IO.
     *
     * @param channel the channel to be registered.
     */
    public void register(Mtp1 channel);
    
    /**
     * Unregisters channels
     *
     * @param channel to be unregistered 
     */
    public void unregister(Mtp1 channel);
    
    /**
     * Gets channels ready for IO operations.
     *
     * @param key IO operations.
     * @param timeout the wait timeout.
     */
    public Collection<Mtp1> select(int key, int timeout);
}
                    
org.mobicents.protocols.ss7.mtp.Mtp2

This is concrete implementation of MTP2 layer. It requires Mtp1. It declares following methods, relevant to configuration process:

Mtp2 declares single method for data send operation: public boolean queue(byte[] msg). This method requires properly formed Mtp3 message.

org.mobicents.protocols.ss7.mtp.Mtp3

This is concrete implementation of MTP3 layer. It implements state machine and encoding/decoding rules. It declares following methods, relevant from user point:

MtpUser is defined in following way:



package org.mobicents.protocols.ss7.mtp;
public interface MtpUser {
    /**
     * Callback method from lower layers MTP3-. This is called once MTP3
     * determines that link is stable and is able to send/receive messages
     * properly. This method should be called only once. Every linkup event.
     */
    public void linkUp();
    /**
     * Callback method from MTP3 layer, informs upper layers that link is not
     * operable.
     */
    public void linkDown();
    /**
     * Callback from Layer4+. It expects properly encoded MTP3 message. It forwards data to MTP3
     * @param msgBuff
     */
    public void receive(byte[] msgBuff);
    
    public void setMtp3(Mtp3 mtp);
}
                    
org.mobicents.protocols.ss7.mtp.RoutingLabel

This is utility class used by other layers. It extracts routing label from MTP3 MSU and performs operation to create label ready to be used in answers.

org.mobicents.protocols.ss7.mtp.provider.MtpProvider

This interface defines contract with upper layer protocol stacks. Its concrete implementation is created wtih MtpProviderFactory class. It is defined as follows:



package org.mobicents.protocols.ss7.mtp.provider;
import java.io.IOException;
import java.util.Properties;
import org.mobicents.protocols.ConfigurationException;
import org.mobicents.protocols.StartFailedException;
public interface MtpProvider {
    /**
     * Sets listener for MTP callbacks. If null is passed internal refence is
     * cleared.
     * 
     * @param lst
     */
    public void setMtpListener(MtpListener lst);
    /**
     * Passes argument to MTP layers for processing. Passed buffer should not be
     * reused after passing to this method!
     * 
     * @param msu
     * @throws IOException
     *             - when IO can not be performed, ie, link is not up.
     * @return
     */
    public void send(byte[] msu) throws IOException;
    /**
     * Starts this provider implementation. Depending on internal it can start
     * local MTP process, or M3UA layer.
     * 
     * @throws IOException
     * @throws StartFailedException
     */
    public void start() throws StartFailedException;
    /**
     * Stops this provider. This call clears all references, ie. listener is
     * cleared as {@link #setMtpListener(MtpListener)} with null argument.
     */
    public void stop();
    /**
     * Method which configures concrete classs. Depending on implementation
     * different properties are supported. However each property starts with
     * "mtp." prefix.
     * 
     * @param p
     */
    public void configure(Properties p) throws ConfigurationException;
    /**
     * Checks if link is up;
     * 
     * @return
     */
    public boolean isLinkUp();
}
                    
org.mobicents.protocols.ss7.mtp.provider.MtpListener

This interface defines callback methods which are called from MtpProvider concrete class.

org.mobicents.protocols.ss7.mtp.provider.MtpProviderFactory

Factory class for concrete implementation of MtpProvider. Create method accepts java.util.Properties. It expects mtp.driver property to contain either full class name of concrete implementation of provider or name of supported providers.

Revision History
Revision 1.0Wed June 2 2010Bartosz Baranowski
Creation of the Mobicents MTP Library User Guide.