Software Solutions for a Mobile World NCL Logo

Table Of Contents

  1. Introduction.
  2. Generic API.
  3. Smart Messaging & Narrow Band Sockets.
  4. Proxies, Firewalls, Internet Gateways and SMSCs.

Introduction

SwiftNote Java Developer’s Kit is used to develop platform-independent value added service applications to integrate with short message wireless networks. Applications developed using SwiftNote can run as standalone applications on a corporate LAN/Intranet or across the Internet using World Wide Web browsers such as Mozilla™ or Microsoft's Internet Explorer .

Short messaging is a low-cost transport used to communicate with mobile stations (e.g. cellular phones, pagers) across wireless networks such as GSM networks. Using SwiftNote short message services such as message bureaux and paging services, E-mail to SMS Gateways, information services (e.g. stock market and news updates), over-the-air mobile unit configuration (e.g. SIM card programming), WWW access services and many others.

SwiftNote is a development tool which provides a Java implementation of the protocols necessary to interface with the short message wireless networks.

SwiftNote provides a simple and effective interface to the world of wireless short messaging, hiding all the protocol complexities from the application developer and allows the developer to focus on the application's service. This significantly reduces the development time-frame, maintenance overhead and cost.

This guide should provide all the necessary information to help get you quickly up and running, developing inovative messaging applications without worrying about underlying protocols. This document tries to achieve this by providing concise information regarding the background to the API, a brief introduction to all aspects of the API and advice and information surrounding good development practices when using SwiftNote. As each new section of the API is introduced, examples are also included to reninforce how to correctly apply it.

In the 1980s, analogue cellular telephone systems experienced rapid growth in Europe. Each country developed its own non-standardised system with specialised equipment incompatible with one another. Mobile equipment was limited to national boundaries and the economic ramifications on the European market were unnecessarily large.

In 1982, the study group Groupe Spécial Mobile (GSM) was formed to study and develop a pan-European public land mobile system. In 1989, GSM responsibility was transferred to the European Telecommunication Standards Institute (ETSI), and phase I of the GSM specifications were published in 1990.

Commercial service was started in mid-1991, and by 1993 there were 36 GSM networks in 22 countries, with 25 additional countries having already selected or considering GSM. Although standardised in Europe, GSM is not only a European standard. GSM networks (including DCS1800 and PCS1900) are operational or planned in over 80 countries around the world. In the beginning of 1994, there were 1.3 million subscribers world-wide. At the beginning of 1995 there were over 5 million subscribers, and by December 1995 there were over 10 million subscribers in Europe alone. With North America making a delayed entry into the GSM field with a derivative of GSM called PCS1900, GSM systems exist on every continent, and the acronym GSM now aptly stands for Global System for Mobile communications.

The Short Message Service, or SMS, is a bi-directional service for short binary and alphanumeric messages (up to 160 bytes). Messages are transported in a store-and-forward fashion via a Short Message Service Centre ( SMSC).

Mobile stations ( MSs) can send and received messages to and from other mobile stations. In a short messaging context, the mobile stations are known as SMEs or Short Message Entities.

Messages can also be sent and received by short message value added services (Application such as Email to SMS gateways, short message bureaux) to and from mobile stations. In a short messaging context, these entities are known as ESMEs or External Short Message Entities.

The diagram below outlines the context in which SMEs and ESMEs reside in a wireless network.

Short Messaging Network
Figure 1 - Short Messaging Network

SwiftNote provides an interface to the wireless network for ESME applications. Applications which are developed using SwiftNote can connect with the SMSC and can send and receive short messages as well as provision customers and distribution lists on the SMSC. Applications can also connect to the wireless network with the use of a compatible cellular device (mobile station or MS). Details of the supported devices can be found in the section . In this instance a SIM card must be inserted into the cellular device for GSM networks.

The protocols supported by SwiftNote are detailed below. The protocols are designed to allow applications interface with an SMSC. The GSM 03.39 protocol specification was originally designed by Aldiscon Ltd. in 1995 as SMPP 3.0. (Aldiscon, Logica-Aldiscon, now known as Logica, are market leaders in SMSC technology.) The protocol was standardised a year later by the ETSI group.

The remaining SMPP 3.3, 3.4 and SMPPP 1.1 protocols are proprietary protocols of Logica-Aldiscon, publicly available at the web sites www.logica.com.and www.smpp.org. These are compatible with Logica-Aldiscon's Telepath SMSC(TM) version 2.1 and upward though other SMSC vendors such as CMG and SEMA have adapted these protocols.

SwiftNote is ETSI GSM 03.39 compliant, and as such provides the following functionality:-

  • Send, Receive Messages
  • Cancel, Replace, Query Messages
  • Bind, Unbind
  • Query Link (session check)

SwiftNote is SMPP 3.3 compliant. The SMPP (Short Message Peer to Peer) protocol version 3.3 is an extension to the GSM 03.39 protocol and as such provides the following functionality:-

  • Send multiple recipient message
  • Retrieve all short message details
  • Query parameters
  • Query all messages (per subscriber)
  • TLV parameters

SwiftNote is SMPPP 1.1 compliant. The SMPPP (Short Message Peer to Peer Provisioning) protocol version 1.1 is an extension to the SMPP 3.3 protocol and as such provides the following functionality:-

  • Add, Query, Modify, Delete subscriber
  • Add, Query, Delete distribution list
  • Add, Query, Delete distribution list member

SwiftNote supports a number of features of Nokia's CIMD protocol including:-

  • Login and Logout
  • Send and Receive (mode 1) messages
  • Alive (link checking)
  • Status Reports

SwiftNote supports the following devices:-

New devices are being added to the above list frequently. For a more up-to-date list please consult www.ncl.ie.

Short message value added services can be developed using SwiftNote and run in Corporate LAN/Intranet, Internet and WWW environments. The diagrams below outline the various environments in which such applications can run.

Operator Assisted Services
Figure 2 - Operator Assisted Services
End User Access
Figure 3 - End User Access

SwiftNote connects with the SMSC over TCP/IP. This gives Java Applications great flexibility regarding the range of networks in which applications can run. The applications can be run on almost every platform using Java Virtual Machines (interpreters) or via Web Browsers, that are freely available on the Internet.

SwiftNote includes a Proxy Application that forwards connections onto the SMSC from a WWW Server. SMS applications can be downloaded to end-users' workstations over the Internet from the WWW server, and connect to the SMSC via this proxy. (The WWW Server has TCP/IP connectivity with the SMSC.) The Proxy Application is a Java application and as such can also run on any platform with a Java virtual machine.

The API is split into 2 groups:-

The fundamental classes describe the structures of the various simple SMS and SMSC entities such as messages, addresses, customers and distribution lists.

The session classes are the classes used during a connection with the SMSC, such as the SMPP connection class, the exceptions and errors it returns, and the asynchronous call-back interfaces.

This guide provides section by section cover of all the core elements of the API. Its is not intended as a definitve guide to every aspect of the API but more as an overview. More in depth information can be found in the API Javadoc.

This guide contains a series of simple examples, which cover the core aspects of the API's. The examples appear in the document as follows:-

package ie.ncl.msg.example;

import ie.ncl.msg.*;

// Step 1. implement .... 
public class SomeExample implements ......
{
    .......
    ....
}

Full java source for all the examples in this document is included in the examples directory of the distribution. There is also an accompanying Ant build file, which will compile and run all the examples against a default configuration.

Configuraion is explained in more depth later. The examples illustrate how to go about sending/receiving messages. Obviously the manner these messages get sent will depend on some underlying connection(mobile device, SMSC connection etc).

The examples come with a Mock connection configured which instead of sending or receiving any messages across underlying networks will instead just log any activity.

The properties file contained at ie/ncl/msg/Factory.properties in the examples directory is where we go about configuring real connections to use to send or recieve across mobile networks. The section Factory Configuration will explain in detail how to configure some real connections.

To turn on logging and debugging you will need to create a file called EventLog.properties in the classpath. This file specifies the name and location of the log file and the debugging options. The file takes the format:

FILE NOT FOUND ******************************

Where debugOn enables or disables the debug, outputLogFile specifies the name of the file to place the log (%D if detected is replaced by the current date/time) useLog4j if configured will use the Apache open source Log4J module to write logging and debug (the outputLogFile will be ignored), and debug specifies the modules to be debugged.

Document Description Source
GSM 03.40 Version 5.6.0 - document reference ETS 300 901 Aug 97 Point to Point Short Message Service (SMS) of the digital cellular telecommunications system - relevant for new/emerging Protocol Identifiers (PID) European Telecommunications Standards Institute ( ETSI)
Annex A of GSM 03.39 Version 4.0.0 - document reference ETR 243 Nov 95 Short Message Peer to Peer (SMPP) Interface Specification ETSI
GSM 03.38 - document reference ETS 300 900 Alphabets and language specific information for the digital cellular telecommunications system - relevant for new/emerging Data Coding Schemes (DCS) ETSI
SMPP 3.3 and SMPPP 1.1 Proprietary extensions to Short Message Peer to Peer protocol - protocol specifications Aldiscon Ltd. www.logica.com
WAP WTP Wireless Application Protocol Wireless Transport Protocol Specification - specifies how lowest layer of WAP stack operates over SMS WAP Forum. www.wapforum.com

Microsoft, MS, MS-DOS and Windows are registered trademarks and Visual J++, and Windows NT are trademarks of Microsoft Corporation. Java is a trademark of Sun Microsystems, Inc. Netscape and Netscape Navigator are trademarks of Netscape Communications Corporation. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. Telepath SMSC is a trademark of Aldiscon, Ltd. SwiftNote is a registered trademark of NCL Technologies, Ltd.

Start Of Chapter - Table Of Contents

Generic API

This section describes the new Generic API. This is a set of classes used to write transport independent SMS applications.

The purpose of the Generic API is to allow the programmer to develop messaging applications independent of the underlying protocols and communication transports. For example, Short Messages (or SMS) can be transmitted and received to and from a cellular device or over a network connection to a short message service centre (SMSC). Indeed, as new protocols and mechanisms are added to the message toolkit they will comply with this interface. Moreover, the Generic API is designed to cater for future message types such as mp3s, video files, picture messages etc. as they become more widely adapted by handset manufacturers.

The Generic API classes can be summarised as follows:-

Sender
an interface used to send messages (asynchronously)
Receiver
an interface used to receive messages (asynchronously)
Address
source or destination address of a message
Message
the message object itself
Factory
used to dynamically load the underlying message transport object
Attributes
used to get and set the attributes of a message or address

There are also two convenience classes:-

SyncSender
used to send messages synchronously
SyncReceiver
used to receive messages synchronously

A number of objects implement the Sender and Receiver interface such as the GSM Modem, SMPP Connection and CIMD Connection objects. These are discussed individually in the preceding sections.

There are two types of Exception also:-

ConnectionException
The ConnectionException is used to indicate that some thing has gone wrong in the underlying connection. This is generally non-recoverable (like the SMSC is no longer responding).
MessageException
The MessageException is used to indicate message specific failures. When a MessageException occurs generally there is something wrong with that particular message. The application can continue to send/receive other messages.

Before sending and receiving messages, a Sender or Receiver object must be created. This can be done in one of two ways:-

Instantiation in code

If an SMPP Sender is used to send short messages (i.e. connect directly to the SMSC of a mobile network operator over the Short Message Peer to Peer protocol) then connectivity can be established as follows:-

    
Sender sender = new SmppConnection("Host",2775,"SysId","SysType","Password");
sender.connect();
                    

If a cellular terminal device is used, then connectivity can be established by:-

    
Sender sender = new GsmModem("Pin","Com1","19200");
sender.connect();
                    
Factory instantiation

To make the code independent on the underlying SMS connectivity the Factory object can be used to instantiate the sender object. Specific configuration information is stored in a separate configuration file. This can be done as follows:-

    
Sender sender = Factory.getSender("modem");
sender.connect();
                    

or

    
Sender sender = Factory.getSender("smsc2");
sender.connect();
                    

The properties configuration file would look like:-

    
modem.class=ie.ncl.sms.modem.GsmModem
modem.pin=Pin
modem.port=Com1
modem.speed=19200

smsc2.class=ie.ncl.sms.smpp.SmppConnection
smsc2.host=Host
smsc2.port=2775
smsc2.id=SysId
smsc2.type=SysType
smsc2.pass=Password
smsc2.type=transmitter
                    

Note that the class parameter specifies the underlying implementation class to be instantiated.

The default configuration file is ie\ncl\msg\Factory.properties and must be in the classpath. This is the recomended method of configuration but alternatively the properties can be specified using one of:-

  • Factory.setProperties(String filename);
  • Factory.setProperties(java.util.Properties properties);

The advantage of using the factory class is that new and future protocols and transports can be added with minimal or no code changes.

Instantiation in code

If SMPP is used to receive short messages, then connectivity can be established by:-

    
Receiver receiver =new SmppConnection("Host",2775,"SysId","SysType","Password","44.*");
receiver.setReceiverListener(this);
receiver.connect();
                    

If a cellular terminal is used, then connectivity can be established by:-

    
Receiver receiver = new GsmModem("Pin","Com1","19200");
receiver.setReceiverListener(this);
receiver.connect();
                    
Factory instantiation

Again, to make the code independent of the underlying SMS connectivity the Factory object should be used to instantiate the receiver object. This can be done as follows:-

    
Receiver receiver = Factory.getReceiver("smsc");
receiver.setReceiverListener(this);
receiver.connect();
                    

or

    
Receiver receiver = Factory.getReceiver("modem");
receiver.setReceiverListener(this);
receiver.connect();
                    

Then in the configuration file would look like:-

    
modem.class=ie.ncl.sms.modem.GsmModem
modem.pin=Pin
modem.port=Com1
modem.speed=19200

smsc.class=ie.ncl.sms.smpp.SmppConnection
smsc.host=Host
smsc.port=2775
smsc.id=SysId
smsc.type=SysType
smsc.pass=Password
smsc.type=receiver
                    

Again, the default configuration file is ie\ncl\msg\Factory.properties and must be in the classpath. This is the recomended method of configuration but alternatively the properties can be specified using one of:-

  • Factory.setProperties(String filename);
  • Factory.setProperties(java.util.Properties properties);

The advantage of using the factory class is that new and future protocols and transports can be added with minimal or no code changes.

Consider the five steps used to send a message in Example 1 shown below

package ie.ncl.msg.example;

import ie.ncl.msg.*;

public class SynchronousSendExample
{
    public static void main(String[] args)
            throws ConnectionException, MessageException
    {
        // Step 1. Load Sender Object 
        SyncSender syncSender =
                new SyncSender(Factory.getSender("mockConnection"));

        // Step 2. Open Sender Connection 
        syncSender.connect();

        // Step 3. Construct message 
        Address destinationAddress = new Address("+353801234567");
        String messageText = "Hello World";
        Message message = new TextMessage(destinationAddress, messageText);

        // Step 4. Send message 
        syncSender.send(message);

        // Step 5. Close connection if finished 
        syncSender.close();
    }
}

A Sender object is created in Step 1. The sender object is instantiated with the specified configuration, in this case defined by the 'smsc' properties. The Sender is wrapped in a convenience object, the SyncSender which is used to send messages synchronously.

A connection is established in Step 2, in this case with an SMSC.

A message is constructed in Step 3. The message in this instance is a TextMessage which consists of a destination address and some text. Alternatively, the message could have been just BinaryMessage, which is constructed with a destination address and a byte array instead of a text string.

The message is sent in Step 4. Send will block until it gets an appropriate response back from the underlying implementation to say that the message has been indeed sent with out any problems. Otherwise an exception will be thrown.

The connection is closed in Step 5 however normally the connection would remain open for the life of the application, as more messages would be sent.

Consider Example 2 shown below

package ie.ncl.msg.example;

import ie.ncl.msg.*;

public class SynchronousReceiveExample
{
    public static void main(String[] args) throws ConnectionException, MessageException
    {
        // Step 1. Load Sender Object 
        SyncReceiver syncReceiver =
                new SyncReceiver(Factory.getReceiver("mockConnection"));

        // Step 2. Open Receiver Connection 
        syncReceiver.connect();

        // Step 3. Block until received 
        Message receivedMessage = syncReceiver.receive();

        // Step 4. Make use of message 
        Address sourceAddress = receivedMessage.getSource();
        System.out.println("Received message from " + sourceAddress);
        if (receivedMessage instanceof TextMessage)
            System.out.println(((TextMessage) receivedMessage).getText());
        else if (receivedMessage instanceof BinaryMessage)
            System.out.println("Binary data " +
                    ((BinaryMessage) receivedMessage).size() + " bytes");


        // Step 5. Close connection if finished 
        syncReceiver.close();

    }
}

A Receiver object is created in Step 1. The receiver object is instantiated with the specified configuration, in this case defined by the 'smsc' properties. The Receiver is wrapped in a convenience object, the SyncReceiver which is used to receive messages synchronously.

A connection is established in Step 2, in this case with an SMSC.

The receive method is called in step 3 which will block indefinitely until a message is received (or an error occurs on the connection).

A received message is received and printed to screen in Step 4. A Message received may be for example a TextMessage or simply a BinaryMessage object.

The connection is closed in Step 5, however normally the connection would remain open for the life of the application, as more messages would be sent.

Note that received messages will be either a TextMessage or BinaryMessage or some other object that extends the base Message class.

Sending a message synchronously waits until the message has been successfully transmitted over the underlying transport and a response has been received. Sending a message asynchronously, does not wait for a response, but rather the application is informed at a later stage that the message has been sent - successfully or unsuccessfully. This is useful where network latency is high and repeated transmission of messages asynchronously improves throughput and performance.

To send messages asynchronously, the calling application must implement a listener (also known as handler or call-back) that is called by the message library when the message has been successfully been sent. This listener is called the SenderListener interface and consists of one method; sent.

Consider Example 3 shown below

package ie.ncl.msg.example;

import ie.ncl.msg.*;

// Step 1. Implement SenderListener 
public class AsynchronousSendExample implements SenderListener
{
    // Step 2. implement the message sent handler method 
    public void sent(Sender sender, Exception ex, Message m)
    {
        if(ex!=null)
            System.out.println("Error sending message to "+m.getDestination());
        else
            System.out.println("Successfully sent message to "+m.getDestination());
    }

    public AsynchronousSendExample() throws ConnectionException, MessageException
    {
        // Step 3. Load sender object 
        Sender sender = Factory.getSender("mockConnection");

        // Step 4. Connect 
        sender.connect();

        // Step 5. Construct message 
        Address destinationAddress = new Address("+353801234567");
        String messageText = "Hello World";
        TextMessage message = new TextMessage(destinationAddress,messageText);

        // Step 6. Send message 
        sender.send(message, this);

        // Step 7. Close connection if finished 
        sender.close();
    }

    public static void main(String[] args)
    {
        try
        {
            new AsynchronousSendExample();
        } catch (Exception e)
        {
            e.printStackTrace();
        }
    }
}

SenderListener is implemented in Step 1. This is done by declaring ‘implements SenderListener’ in the class declaration.

The SenderListener listener method is implemented in Step 2. This is the method that will be called by the library when a message has been sent.

A Sender object is created in Step 3. The Sender object is instantiated with the specified configuration, in this case that defined by the 'smsc' properties.

A connection is established in Step 4, in this case with an SMSC.

A message is constructed in Step 5. The message in this instance is a TextMessage which consists of a destination address and some text. Alternatively, the message could be a BinaryMessage that is constructed with a destination address and a byte array instead of a text string.

The message is sent asynchronously in Step 6. The send method will NOT block however. In this case it returns immediately. When the underlying implementation gets an appropriate response for the sent message it will call the listener that was specified, in this case this.sent(). If a different listener object X was specified, then X. sent() would be called. Note that different listeners maybe specified for different messages.

The connection is closed in Step 7, however normally the connection would remain open for the life of the messaging application, as more messages would be sent.

Receiving a message asynchronously is used when an application wants to be notified of messages as they arrive - rather than block or poll.

To receive asynchronously the calling application must implement a listener (also known as handler or call-back) which will be called as messages are received. This listener is called the ReceiverListener interface and consists of one method ' received'.

In the program Example 4 shown below there are 6 steps outlining the process.

package ie.ncl.msg.example;

import ie.ncl.msg.Factory;
import ie.ncl.msg.Message;
import ie.ncl.msg.Receiver;
import ie.ncl.msg.ReceiverListener;

// Step 1 implements ReceiverListener 
public class AsynchronousReceiveExample implements ReceiverListener
{
    // Step 2 the receiver listener (handler/callback) method 
    public boolean received(Receiver r, Exception e, Message m)
    {
        if (e != null)
            System.out.println("Error receiving - " + e);
        else
            System.out.println("Successfully received " +
                    "message to " + m.getDestination());
        return true;
    }

    public AsynchronousReceiveExample() throws Exception
    {
        // Step 3. Load object 
        Receiver receiver = Factory.getReceiver("mockConnection");

        // Step 4. Setup callback listener 
        receiver.setReceiverListener(this);

        // Step 5. Connect 
        receiver.connect();

        // Step 6. Close connection if finished 
        Thread.sleep(1000);
        receiver.close();
    }

    public static void main(String args[])
    {
        try
        {
            new AsynchronousReceiveExample();
        } catch (Exception e)
        {
            e.printStackTrace(System.out);
        }
    }
}

ReceiverListener is implemented in Step 1. This is done by declaring 'implements ReceiverListener' in the class declaration. In this case it is the AsynchronousReceiveExample object itself.

The ReceverListener interface method is implemented in Step 2. This is the method that will be called when a message has been received.

A Receiver object is created in Step 3. The receiver object is instantiated with the specified configuration. In this case it is the configuration defined by the 'smsc' properties.

The receiver listener is specified in Step 4. All messages received will be sent to the listener. Note that this MUST be done before a connection is called. If a connection is established before the receiver listener is specified, then messages may arrive before the listener is set-up and get discarded. Indeed, the underlying implementation can throw exceptions in such a case.

A connection is made established in Step 5 with the underlying SMS transport, in this case the SMSC.

The connection is closed in Step 6. Normally the connection would be left open for the life of the messaging application as more messages would be received. (If the connection was closed as soon as it was opened, then no messages may be received so for the purposes of this example there is a pause of 10 seconds.)

NOTE: that the receiver listener received(…) should return true to indicate a positive acknowledgement for the message. Depending on the underlying implementation, a return value of false indicates to the underlying transport that something went wrong. In such a case, the underlying transport may attempt to re-deliver the message at a later stage or record an error in some remote system.

SMS attributes can be set and retrieved using the methods:-

    
// Put an attribute
Message.putAttribute(String name,Object value);

// Get an attribute
Object value = Message.getAttribute(String name);
                

This applies to all message classes - both binary and text. Attribute names are unique so adding an attribute with the same name as one previously added will override that attribute value. Attributes are optional and the defaults depend on the underlying transport.

A message attribute is ignored if it is not understood by the underlying transport.

A short message has a number of attributes that are common to all transports (SMSC and cellular devices). These are as follows:-

The DCS is an integer field. It is used to indicate to the recipient handset that the message payload is a specific type of data and to handle accordingly. Examples of DCS values are :-

  • DataCodingScheme.Unicode – the message payload contains Unicode data.
  • DataCodingScheme.Default – the message payload contains text.
  • DataCodingScheme.DisplayOnly – the message containing text is to be displayed immediately on the phone but not stored (on the SIM or otherwise).
  • DataCodingScheme.Binary – the message payload is a binary message. The binary message contains data which could be destined for an application on the phone (such as a Calendar or a WAP browser)

To set/get the DCS field of a message use:-

    
import ie.ncl.sms.dcs.DataCodingScheme;
// To set the attribute
message.putAttribute(
    ie.ncl.sms.MessageAttributeNames.DCS,
    new DataCodingScheme(value));

// To get the attribute
DataCodingScheme dcs = (DataCodingScheme)
    message.getAttribute(
    ie.ncl.sms.MessageAttributeNames.DCS);
                    

The DataCodingScheme object is located in the package ie.ncl.sms.dcs.

The PID is a short message attribute used to route the message. Though not often used, the PID can be used for actions such as:-

  • routing data to the SIM card
  • replace existing messages –
    • ProtocolIdentifier.REPLACE_SHORT_MESSAGE_TYPE1 ...
    • ProtocolIdentifier.REPLACE_SHORT_MESSAGE_TYPE7
  • de-personalising or resetting the phone
    
import ie.ncl.sms.gsm.ProtocolIdentifier;

// To set the attribute
message.putAttribute(
    ie.ncl.sms.MessageAttributeNames.PID,
    new ProtocolIdentifier(value));

// To get the attribute
ProtocolIdentifier pid = (ProtocolIdentifier)
    message.getAttribute(
    ie.ncl.sms.MessageAttributeNames.PID);
                    

Note however that PID values may not be permitted by the underlying transport service (or denied by the network carrier).

The ProtocolIdentifier object is located in the package ie.ncl.sms.gsm.

The UDHI is one bit. It is used to tell the recipient phone that the message payload (bytes) contains some protocol specific header information and that it is not a normal text message. For example this could be used to indicate that the message may contain a WAP datagram, or smart messaging data such as that in ring-tones and pictures messages.

The individual protocols such as WAP and Smart Messaging are not discussed here. These protocols run above the SMS transport layer.

To set and get the UDHI field of a message use:-

    
// To set the attribute
message.putAttribute(ie.ncl.sms.MessageAttributeNames.UDHI,new Boolean(true));

// To get the attribute
Boolean b = (Boolean)message.getAttribute(ie.ncl.sms.MessageAttributeNames.UDHI);
                    

The UDHI is a java.lang.Boolean object.

The validity period is used to specify the life time of a message. To set and get this attribute use the following :-

    
import ie.ncl.sms.gsm.ValidityPeriod;
// To set the attribute
message.putAttribute(
    ie.ncl.sms.MessageAttributeNames.VALIDITY,
    new ValidityPeriod (date));

// To set the attribute
message.putAttribute(
    ie.ncl.sms.MessageAttributeNames.VALIDITY,
    new java.util.Date(…));

// To get the attribute
ValidityPeriod vp = (ValidityPeriod)
    message.getAttribute(
    ie.ncl.sms.MessageAttributeNames.VALIDITY);
                    

The validity period can be specified using relative time:-

    ValidityPeriod(int days)

or absolute time:-

    ValidityPeriod(java.util.Date date).

The ValidityPeriod object is located in the package ie.ncl.sms.gsm.

The scheduled delivery message attribute is used to tell the message server the time at which to send the message.

The scheduled delivery object is a java.util.Date object.

    
// To set the attribute
message.putAttribute(
ie.ncl.sms.MessageAttributeNames.SCHEDULE,
    new java.util.Date(…) );
                    

The time stamp message attribute is used to find out the time when a received message was sent from the originating mobile handset. (Messages may not received immediately!)

    
// To get the attribute
java.util.Date timestamp = (java.util.Date)
    message.getAttribute(
        ie.ncl.sms.MessageAttributeNames.TIMESTAMP);
                    

The timestamp is a java.util.Date object.

This registered delivery message attribute is a Boolean that indicates if a delivery receipt (also known as a delivery report) is required for a message being sent . When set, a delivery receipt will be received for the send message to indicate its final state such as delivered or failed. See RECEIPT below.

    
// To set the attribute
message.putAttribute(
    ie.ncl.sms.MessageAttributeNames.REGISTERED,
    new Boolean(true));
                    

This message attribute is a Boolean object and indicates if a message on the SMSC is to be replaced with a new one. The source and destination addresses must match. (Note this field applies to SMSC connections only.)

    
// To set the attribute
message.putAttribute(
    ie.ncl.sms.MessageAttributeNames.REPLACE,
    new Boolean(true));
                    

The receipt attribute is a Boolean that indicates if a message is actually a message receipt or a delivery report.

    
import ie.ncl.sms.gsm.Status;

// To get the attribute
Boolean receipt = (Boolean)
    message.getAttribute(
        ie.ncl.sms.MessageAttributeNames.RECEIPT);

if(receipt!=null && receipt.booleanValue()==true)
{
    Status status= (Status)
    message.getAttribute(
    ie.ncl.sms.MessageAttributeNames.RECEIPT_STATUS);
}
                    

A message that is a receipt - or delivery report - will contain a time stamp attribute that will hold the time of delivery. Message receipts are of type TextMessage with some textual information on the delivery receipt. The source address of the message contains the address from where the delivery report originated.

The ie.ncl.sms.gsm.Status object holds an enumerative status value that can be accessed using the method:-

    int Status.getState ()

This will have one of the values:-

  • Status.DELIVERED
  • Status.ENROUTE
  • Status.EXPIRED
  • Status.FAILED
  • Status.CANCELLED
  • Status.DELETED
  • Status.OTHER

The message has been successfully delivered if it is in a DELIVERED state. It is en route if it is in a ENROUTE state (as is the case if phone is turned off). All other states are error states.

The Type of Address is used to specify additional information about an SMS address. Usually the SMS address is a simple international number in textual form. However additional information about an address can be specified using the TypeOfAddress object. This is located in the package ie.ncl.sms.gsm.

To set/get the TypeOfAddress:-

    
import ie.ncl.sms.gsm.TypeOfAddress;
// To set the attribute
address.putAttribute(
    ie.ncl.sms.AddressAttributeNames.TOA,
    new ie.ncl.sms.gsm.TypeOfAddress(ton,npi);

// To get the attribute
TypeOfAddress  = (TypeOfAddress)
    message.getAttribute(
        ie.ncl.sms.AddressAttributeNames.TOA);
                    

The integers TON (type of number) and NPI (number plan indicator) in the example are used to specify additional routing information for a short message service centre. These are normally both set to 1 for international numbers.

Valid TON values are:-

    TypeOfAddress.TON_UNKNOWN
    TypeOfAddress.TON_INTERNATIONAL
    TypeOfAddress.TON_NATIONAL
    TypeOfAddress.TON_NETWORK_SPECIFIC
    TypeOfAddress.TON_SUBSCRIBER
    TypeOfAddress.TON_ALPHANUMERIC
    TypeOfAddress.TON_ABBREVIATED
    TypeOfAddress.TON_RESERVED

Valid NPI values are:

    TypeOfAddress.NPI_UNKNOWN
    TypeOfAddress.NPI_ISDN
    TypeOfAddress.NPI_E164
    TypeOfAddress.NPI_DATA
    TypeOfAddress.NPI_X121
    TypeOfAddress.NPI_TELEX
    TypeOfAddress.NPI_NATIONAL
    TypeOfAddress.NPI_PRIVATE
    TypeOfAddress.NPI_ERMES

Normally the TON and NPI are set to International, E164 respectively. This means that the destination number is an international mobile number. The number should be in international format and without the international dialling code prefix (such as ‘00’ or ‘011’).

If the TON is national then the international country code should be omitted. For example the number would be 0841234567 instead of 353841234567 where 353 is the country code.

Some SMSCs are clever and automatically set the TON/NPI depending on the mobile number (MSISDN) itself. It is best to confirm this with the SMSC administrator to see what format the SMSC expects the MSISDN to be in.

There are a number of classes that implement the Sender and Receiver class for SMS. Currently there are:-

The default properties of each connection can be specified in the file , located at:-

    ie\ncl\msg\Factory.properties

so when a Sender or Receiver object is created by (the static methods):-

    Sender   s = Factory.getSender(“mySender”);
    Receiver s = Factory.getReceiver(“myReceiver”);

the Factory class will search the file for all attributes ‘mySender.*’ properties. It will detect the relevant class from the line ‘mySender.class=…’ and pass the remaining parameters to the object once it has been instantiated.

The properties of each connection can also be specified directly with :-

    java.util.Properties

class by calling :-

    Sender   s = Factory.getSender(“mySender”, properties);
    Receiver r = Factory.getReceiver(“myReceiver”, properties);

Where the properties have a string name and value pair, each name prefixed by ‘mySender’ or ‘myReceiver’ in the example above.

Multiple configurations can be specified in the properties file as long as each has it’s own unique prefix (e.g. each line starts with ‘mySettings.’)

Some objects are both a Sender AND Receiver implementation and may need to share a common resource. So it would be required that the underlying object implementation be instantiated only once. This can be done by sharing the object.

To do this the first object needs to declared the object as shared , by adding the property shared=true . So in the example configuration below, when mySender configuration is requested by:-

    Factory.getSender(“mySender”);

it is:-

  • instantiated as normal and
  • a reference to this object is kept internally in the Factory’s lookup table - as indicated by the shared property.

The other configuration that shares this object should have simply one line with the property shares=otherConfigurationName . This tells the Factory method to use a previously instantiated object. So in the example below, when myReceiver configuration is requested by:-

    Factory.getReceiver(“myReceiver”);

it is not instantiated but looks up the previously instantiated object mySender .

    
mySender.class=ie.ncl.sms.modem.GsmModem
mySender.propertyX=…
mySender.propertyY=…
mySender.propertyZ=…
mySender.shared=true

myReceiver.shares=mySender
                    

This is particularly useful where for example a GsmModem object can be both a sender and a received.

The SmppConnection object is used to establish a communication link with an SMPP protocol compliant Short Message Service Centre, usually located on a mobile network operator’s site.

The SmppConnection properties with sample values are listed below.

    
X.class=ie.ncl.sms.smpp.SmppConnection
X.host=127.0.0.1
X.port=8011
X.id=id
X.type=type
X.pass=pass
X.bindType=receiver
X.version=50
x.range=123456789
x.ton=1
x.npi=1
                    

The host specifies the SMSC host name. The port is the IP port on which the SMPP server is listening.

Authentication is specified using the three parameters id , type and pass which are the System ID, System Type and Password. These parameters are allocated by the SMSC administrator.

The bindType tells the SMSC that the connection is a receiver , transmitter or transceiver connection.

The range tells the SMSC the range of addresses to receive messages on. This is relevant only for a receiver connection. Though the SMPP standard specifies the range as a regular expression, it does vary from SMSC to SMSC. Normally however this is not set and the default set-up on the SMSC is used. The additional properties range.ton and range.npi specify the binding range’s Type of Number (TON) and Number Plan Indicator (NPI). These are also optional. See the TypeOfAddress object for more information on TON and NPI. Range is not used for a transmitter bind type.

The version tells the SMSC what version of SMPP to use.

The optional defaultAlphabetEncoding specifies the alphabet encoding used on the SMSC. This can be GSM or ROMAN8 or any character set encoding supported by Java e.g UTF16 .

The linkAliveIfAnyDataReceived when set to true means that the link is alive if ANY data is received to a query link operation (like a ping) within the smscResponseTimeoutSeconds response timeout. Set to false means that the link is alive if query link response is received to a query link request within response timeout. This is sometimes set in very high volume message applications where may pending messages are holding up the response to a query link operation.

If the reconnectOnDisconnect is set to true reconnection is attempted when a IO error is detected. If this is false then no reconnection is attempted.

The reconnectRetryAttempts (int) is the number of attempts reconnection should be tried before giving up. This value is ignored if reconnectOnDisconnect is false .

The reconnectTimerSeconds (int - seconds) specifies how much time to wait between reconnection attempts. 60 seconds should be sufficient. This is ignored if the reconnectOnDisconnect is set to false .

The queryLinkEverySeconds (int - seconds) specifies how often query links are sent. If this is 0 then none are sent. Usually 30 seconds is sufficient. Some SMSC administrators require this to be set to tell the SMSC that the application is up and running.

The flowControlTimerSeconds (int - seconds) specifies how long to pause when a flow control messages is received from SMSC (0 for no pause)

The unackedQueueSize (int) specifies the maximum number of sent messages for which there are no acknowledgements received from the SMSC. This is usually 10 depending on SMSC.

The smscResponseTimeoutSeconds specifies the response timeout for various requests - particularly the query link response (usually twice query link time).

The defaultTon , defaultNpi specify the TON/NPI values of an address. TON is type of number. NPI is Number plan indicator. These values will be used when not defined in the address of a sent message.

The sourceTon , sourceNpi , sourceNumber parameters can be used to specify the source address of a sent message. Normally these values default to null.

If specified, the internationalPrefix property value will replace occurrences of the + symbol in a mobile number.

The CimdConnection object is used to establish a communication link with an Nokia CIMD protocol compliant Short Message Service Centre, usually located on a mobile network operator’s site.

The CimdConnection properties with sample values are listed below.

    
X.class=ie.ncl.sms.cimd.CimdConnection
X.host=127.0.0.1
X.port=8001
X.id=id
X.pass=pass
X.queryLinkEverySeconds=10
X.smscResponseTimeoutSeconds=20
                    

The host specifies the SMSC host name. The port is the IP port on which the CIMD server is listening.

Authentication is specified using the two parameters id and pass which are the UserID, Password. These parameters are allocated by the SMSC administrator.

The queryLinkEverySeconds tells CIMD to check the link every specified number of seconds. This is used to ensure that the connection has not gone down.

The smscResponseTimeoutSeconds tells CIMD to report an error if a response to a request has not been received within the specified time-period.

The UCPConnection object is used to establish a communication link with an CMG UCP protocol compliant Short Message Service Centre, located on a mobile network operator’s site.

The UCPConnection properties with sample values are listed below.

    
X.class=ie.ncl.sms.ucp.UCPConnection
X.host=127.0.0.1
X.port=8001
X.sessionLogin=12345
X.sessionPassword=secret
                    

The host specifies the SMSC host name. The port is the IP port on which the UCP server is listening.

Authentication is specified using the two parameters sessionLogin and sessionPassword . These parameters are optional (when configured send over a session management packet to the SMSC for authentication. They allocated by the SMSC administrator.

The GsmModem object is used to establish a communication link with an GSM Cellular device connected to a workstation (PC/UNIX) usually via the serial port (PCMCIA is also possible). Such GSM Cellular devices include

  • Siemens M20
  • Siemens TC35
  • Falcom A2
  • Nokia Phone Card 2.0

The GsmModem properties with sample values are listed below.

    
X.class=ie.ncl.sms.modem.GsmModem
X.type=serial
X.device=COM1
X.speed=19200
X.pin=22765
X.loopbackAllowed=false
X.ownNumber=+353868881685
                    

The type specifies the device is accessed by a serial port. The device specifies the serial port name. This is ‘COM1’, ‘COM2’, etc.. for a Windows operating system. This is ‘/dev/ttyS0’, ‘/dev/ttyS1’, etc. for a Unix based operating system.

The speed specifies the speed. Note that for some devices only one speed will work. Siemens use a speed of 19200, where Falcom use 9600.

Authentication is specified using the parameters pin which is the PIN of the SIMcard in the cellular device.

The ownNumber tells Cellular device that all sent messages will have this number as a source.

The loopbackAllowed is used to prevent the modem from sending messages to itself. The purpose of this is to prevent a potential infinite loop in some applications that responds to received messages (and generating a huge bill!).

Advance Settings

The sendRetries specifies the integral number of retries to be performed when a message send fails. If sendRetries is specified, sendRetryPauseSeconds is species the number of seconds to pause between such retries.

If a network terminal server is being use, the type should be set to ip and host , port should specify the host and port of the terminal server. ( device and speed parameters are not required in this instance.)

Serial Communication Support

Serial communication support uses two external software packages. The first is JavaComm from Sun. At the time of writing this was located at http://java.sun.com/products/javacomm/

The jar files that are shipped here should be used on a Solaris or Windows platform.

For Linux, we recommend Trent Jarvi's RXTXcomm - version 1.5-7 or later (packaged under gnu.io rather than javax.comm). Many thanks to Trent Jarvi for all his assistance in helping us get this working with our software!

Both software packages require the installation of native libraries to get them working. I've addressed each briefly below.

Quick Installation of Trent Jarvi's RXTXcomm (Linux).
  • Download Version 1.5-7 or later from www.rxtx.org & install.
    • $ tar -xzvf rxtx-1.5-7.tar.gz
    • $ cd rxtx-1.5-7
    • $ ./configure (follow the instructions)
    • $ make install
  • Read "R. How can I use Lock Files with rxtx?" in the INSTALL file.
  • The RXTXcomm.jar should be present in /usr/java/jre/lib/ext. It should not be necessary to add this to your classpath.

NOTE: You may need to be logged in as root to create libraries in java library path and MUST be in or added to the uucp group . See /etc/group file (root to edit!).

Quick Installation of Sun's JavaComm 2.0 (Windows/Solaris).
  • Download from http://java.sun.com/products/javacomm/
  • Unzip the file into a directory.
  • The win32com.dll must be in the PATH. So copy this to the JRE\bin directory (or say C:\WINNT directory).
  • The comm.jar must be in your classpath. So copy this to (say) the JRE\lib directory and add JRE\lib\comm.jar to your classpath.
  • The properties file 'javax.comm.properties' must be placed in the JRE\lib directory.

If one of these steps are ignored (or one of these files cannot be found at runtime) then an error such as port not found will be produced for a valid port.

IMPORTANT: If an application is run from another volume drive (such as 'J:') then the win32com.dll may not pick it up by the 'java' command and so issue a port not found error. Always ensure that the paths are set-up correctly. Note that sometimes development environment products may place java commands in the WINNT/system directory. As such, when the java command is started from here it may not detect the JRE bin directory and again not pick up the relevant DLL. The same error may ensue - port not found.

Start Of Chapter - Table Of Contents

Smart Messaging & Narrow Band Sockets

Smart Messaging and Narrow Band Sockets are the protocols used to send data messages such as pictures, ring-tones, business cards and calendar reminders to mobile phones.

The Narrow Band Sockets specification was originally developed by Intel and Nokia with the purpose of designing a protocol that could be used to exchange data between mobile stations (phones) over high latency, low performance small packet sized networks – or more specifically SMS. The protocol provides fragmentation, reassembly and reliability over such networks in much the same way the internet protocols work.

In the SMSJDK, the Narrow Band Sockets implementation is used over SMS. When a long stream of data is sent to a mobile phone (such as a picture or a ring tone) that is considerably longer than the length of an SMS, the Narrow Band Socket functions split the message up into a selection of formatted fragments, and each is sent over SMS. The recipient phone on the other end reassembles the fragments back into the original long stream of data.

Narrow Band Sockets work much like TCP/UDP internet protocols in that a destination port number can be used to identify individual applications on the mobile phone. For example one port number might be used to tell the phone that the data is intended for the ‘Business Card’ application on the mobile phone while another port number would indicate that the data was intended for a ‘Ring tone’ application on the mobile phone.

Protocol Layers fir Smart Messaging
Figure 4 - Protocol Layers fir Smart Messaging

Smart Messaging is a protocol developed solely by Nokia which operates over Narrow Band Sockets. This protocol specifies the format of a number of different types of messages such as:-

While the specification is public, to date only Nokia phone models handle these types of messages although there are indications that other mobile phones will adapt this specification in light of the surge in demand for different ring-tones and operator logos.

Before you can start sending Smart Messages, a Narrow Band Socket or NBS must be created. And before this can be done, an SMS Sender object must be created. The Sender object was discussed in detail in the last chapter. For the purposes of this section, it will be assumed that one is already configured in the Factory configuration file with the configuration setting name ‘sms’.

Creating a NBS is simple, as seen in the sample code:-

    
// Get a sender object
Sender sender  = Factory.getSender(“sms”);

// Narrow band socket uses sender to transmit messages
NarrowBandSocket myNbs = new NarrowBandSocket(sender);

// send smart messages
…

// Close it when finished
myNbs.close();
…
                

The Narrow Band Socket will cause the sender object to ‘connect’ i.e. it will call the sender.connect() method.

Note that it is vitally important that the Narrow Band Socket remain open for the duration of the application rather than creating one each time a smart message is sent. The reason for this is that the Narrow Band Socket uses sequential numbering on packets of information sent to mobile phones which increment monotonically. If a Narrow Band Socket is closed and then re-created, all packet numbering will be lost. So if a phone receives another smart message with the same sequence number, it may discard it as it will have assumed that it already has received the packet and it was a retransmission.

A RingToneMessage is composed of Melody object and a destination Address . The Melody object is a sequence of Phrase objects. A Phrase is a sequence of Note objects with a volume and speed and optional repeat. Each Note has a pitch , duration and optional specifier to add specific length attributes to the note.

The example below shows how to create and send a ring tone message object.

package ie.ncl.sms.nbs.example;

import ie.ncl.msg.*;
import ie.ncl.sms.nbs.*;

public class RingToneSendExample
{
    public static void main(String args[])
    {
        try
        {
            // Step 1. Connect to the SMS transport 
            Sender sender = Factory.getSender("mockConnection");

            // Step 2. Create a narrow band socket 
            NarrowBandSocket nbs = new NarrowBandSocket(sender);

            // Step 3. Create a new phrase and add notes to it 
            Phrase p = new Phrase(Phrase.STYLE_NORMAL, 16);
            p.add(new Note(Note.C, 1));
            p.add(new Note(Note.D, 1));
            p.add(new Note(Note.E, 1));
            p.add(new Note(Note.F, 1));
            p.add(new Note(Note.G, 1));
            p.add(new Note(Note.A, 1));
            p.add(new Note(Note.B, 1));
            p.add(new Note(Note.C + 12, 1));

            // Step 4. Create a melody with the one phrase 
            Melody melody = new Melody("Scales");
            melody.add(p);

            // Step 5. Send it 
            Address to = new Address("0872352079");
            nbs.send(new RingToneMessage(to, melody));

            // Step 6. Close the connection 
            nbs.close();
        } catch (Exception e)
        {
            System.out.println("An error occured - " + e);
            e.printStackTrace(System.out);
        }
    }
}

In step 1 & 2 a narrow band socket is created. In step 3 a musical phrase is created which in this case a C scale . In step 4 this is added to a melody. Step 5 creates the ring tone message using the melody and a destination address and sends the RingTone message.

Finally, step 6 closes the connection, however note that the connection should remain open for the duration of the application for reasons described in the previous section on Narrow Band Sockets.

The individual music objects RingToneMessage , Melody , Phrase and Note are described below.

A note is used to represent a musical note. A series of notes are used to compose a Phrase object. It is in the ie.ncl.sms.nbs package.

Variables

The following constants are static integers used to represent the pitch of the note:-

  • C or MIDDLE_C
  • CSHARP
  • D
  • DSHARP
  • E
  • F
  • FSHARP
  • G
  • GSHARP
  • A
  • ASHARP
  • B
  • (PAUSE)

When 12 is added to these values, the note is an octave higher, when 12 is subtracted, the note is an octave lower. It should be ‘noted’ that the scale on a Nokia phone is four octaves, one below middle C to three octaves above it. See below.

Musical notes
Figure 5 - Musical notes

Note that a PAUSE indicates a rest i.e. no note.

Notes should range between Note.PITCH_MIN and Note.PITCH_MAX

The following constants are static integers used to represent the duration of each note:-

  • DURATION_BREVE
  • DURATION_SEMIBREVE
  • DURATION_MINIM
  • DURATION_CROTCHET
  • DURATION_QUAVER
  • DURATION_SEMIQUAVER
  • DURATION_DEMISEMIQUAVER
  • DURATION_HEMIDEMISEMIQUAVER

Each note length is half that of the previous. For example a crotchet duration is half the length of a minim duration and so on. (Note! that the overall tempo of a melody can be specified in the Phrase object – a collection of notes.)

Finally the following optionally qualify the length of a note. This optional specifier parameter modifies the duration of the musical note accordingly.

  • SPECIFIER_DOTTED
  • SPECIFIER_DOUBLE_DOTTED
  • SPECIFIER_TWO_THIRDS

A Phrase object is used to represent a musical phrase i.e. a collection of notes. A series of phrases constitute a Melody object. The Phrase object is located in the ie.ncl.sms.nbs package.

Variables

The following constants are static integers used to represent the style of the note:-

  • STYLE_CONTINUOUS – no break between notes.
  • STYLE_NORMAL – normal music style.
  • STYLE_STACCATO – the notes are very detached.

The following constants are static integers used to represent the minimum and maximum tempo or speed of the music:-

  • TEMPO_FAST - Fast tempo is 900 beats per minute.
  • TEMPO_SLOW - Slow tempo is 25 beats per minute.

The following constants are static integers used to represent the volume of the music:-

  • VOLUME_HIGH - High volume is the loudest allowable.
  • VOLUME_LOW - Low volume is no sound.
  • VOLUME_MEDIUM – midway volume.

A Melody is used to represent a collection of musical phrases. The Melody object is located in the ie.ncl.sms.nbs package.

A RingToneMessage is the structure used by the NarrowBandSocket to send the melody to the mobile handset. The RingToneMessage is an extension of the SmartMessage Class. The RingToneMessage class is located in the ie.ncl.sms.nbs package.

A Bitmap is used to produce a picture message., icon or logo bitmap. It is a series pixels (represented by RGB integers) together with a width and height value.

Bitmap Diagram
Figure 6 - Bitmap Diagram

A PictureMessage is used by the NarrowBandSocket to send a picture message to a mobile handset. The PictureMessage is an extension of the SmartMessage class and is located in the ie.ncl.sms.nbs package.

Picture messages may contain optional text.

A IconMessage is used by the NarrowBandSocket to send a group icon message to a mobile handset. The IconMessage is an extension of the SmartMessage class and is located in the ie.ncl.sms.nbs package.

Group Icons are used on handsets to associate images with caller ids. Thus when a phone rings with a particular caller ID the group image will be displayed.

A LogoMessage is used by the NarrowBandSocket to send an operator logo message to a mobile handset. The LogoMessage is an extension of the SmartMessage class and is located in the ie.ncl.sms.nbs package.

Logos are used on handsets to associate images with a particular mobile operator. They are usually displayed permanently on the phone’s screen when the user is registered on the mobile operator’s cellular network.

A NetworkOperator is the used to store information about a network operator such as the :-

  • name of the mobile network operators
  • international Country Code (CC)
  • National Dialling Code (NDC)
  • Mobile Country Code (MCC)
  • Mobile National Code (MNC)

Note that the CC and the MCC are not the same. The country code (CC) is the standard international country codes for all phone systems. The mobile country code (MCC) is a special identifier used within mobile networks to uniquely identify each country. This is maintained by the GSM standards body.

Each country may have a number of mobile networks.

The NetworkOperator class is used by the LogoMessage and is located in the ie.ncl.sms.nbs package.

VCards and VCalendars are what are used to send appointments and contact details to mobile phone hand sets.

Below is are two examples of how this is done.

package ie.ncl.sms.nbs.example;

import ie.ncl.sms.nbs.VCardMessage;
import ie.ncl.sms.nbs.VCard;
import ie.ncl.sms.nbs.NarrowBandSocket;
import ie.ncl.msg.Address;
import ie.ncl.msg.Factory;
import ie.ncl.msg.Sender;

public class SendVCardExample
{
    public static void main(String[] args)
    {
        try
        {
            // Step 1. Connect to the SMS transport 
            Sender sender = Factory.getSender("mockConnection");

            // Step 2. Create a narrow band socket 
            NarrowBandSocket nbs = new NarrowBandSocket(sender);

            // Step 3. Create a new business card 
            VCard card = new VCard("Joe", "Bloggs", "0872352079");

            // Step 4. Create a VCardMessage 
            Address to = new Address("0872352079");
            VCardMessage cardMessage = new VCardMessage(to, card);

            // Step 5. Send the VCardMessage 
            nbs.send(cardMessage);

            // Step 6. Close the connection if finished 
            nbs.close();

        } catch (Exception e)
        {
            System.out.println("An error occured - " + e);
            e.printStackTrace(System.out);
        }
    }
}

package ie.ncl.sms.nbs.example;

import ie.ncl.msg.Address;
import ie.ncl.msg.Factory;
import ie.ncl.msg.Sender;
import ie.ncl.sms.nbs.NarrowBandSocket;
import ie.ncl.sms.nbs.VCalendar;
import ie.ncl.sms.nbs.VCalendarMessage;
import ie.ncl.sms.nbs.VEvent;

import java.util.Date;

public class SendVCalendarExample
{
    public static void main(String args[])
    {
        try
        {
            // Step 1. Connect to the SMS transport 
            Sender sender = Factory.getSender("mockConnection");

            // Step 2. Create a narrow band socket 
            NarrowBandSocket nbs = new NarrowBandSocket(sender);

            // Step 3. Create a new calendar event 
            VEvent event = new VEvent("Off on holiday!", new Date(), new Date());
            VCalendar cal = new VCalendar(event);

            // Step 4. Create a VCalendarMessage 
            Address to = new Address("0872352079");
            VCalendarMessage callendarMessage = new VCalendarMessage(to, cal);

            // Step 5. Send the VCalendarMessage 
            nbs.send(callendarMessage);

            // Step 6. Close the connection if finished 
            nbs.close();
        } catch (Exception e)
        {
            System.out.println("An error occured - " + e);
            e.printStackTrace(System.out);
        }
    }
}

In this example, a VEvent is created with the details of the event. This is wrapped in the VCalendar object (which may support multiple cards in the future).

The VCalendarMessage is used to specify what mobile number the event is sent to.

A VCard is the structure used by the NarrowBandSocket to send a business card message to a mobile handset. The VCardMessage is an extension of the SmartMessage class and is located in the ie.ncl.sms.nbs package and is used to send a VCard.

VCards are used on handsets to associate textual names with phone numbers. Indeed, some models of phones (e.g. Nokia 7110) support much more by being able to store email addresses, fax numbers, street addresses etc. Phones that do not support such normally strip out unwanted fields in the VCard and just use the name and telephone number fields.

A VCardMessage is used by the NarrowBandSocket to send a business card message to a mobile handset. The VCardMessage is an extension of the SmartMessage class and is located in the ie.ncl.sms.nbs package.

See the VCards class for more information.

A VEvent is used construct calendar entries that are used by the NarrowBandSocket to send a calendar appointment to a mobile phone. The VEvent is used by VCalendar which in turn can be used by the VCalendarMessage to be sent to a mobile handset using the NarrowBandSocket.send() method.

VEvents and VCalendars are used on handsets (e.g. Nokia 7110) to place entries in the appointments/calendars.

A VCalendar is used to send a events to a mobile handset. The VCalendar is used by the VCalendarMessage that is then sent to a mobile handset using the NarrowBandSocket.send() method.

VEvents and VCalendars are used on handsets (e.g. Nokia 7110) to place entries in the appointments/calendars.

Currently VCalendar supports only one VEvent at a time. Future implementations may support multiple VEvents in a VCalendar .

A VCalendarMessage is used by the NarrowBandSocket to send a calendar-event message to a mobile handset. The VCalendarMessage is an extension of the SmartMessage class and is located in the ie.ncl.sms.nbs package.

See the VCalendar class for more information.

Start Of Chapter - Table Of Contents

Proxies, Firewalls, Internet Gateways and SMSCs

The SMS JDK comes with a Java Proxy Application which can be used by downloaded Java applets to connect to the Short Message Service Centre. The SMS JDK also provides support for Socks V4 compliant Firewalls and Internet Gateways.

Java applets down-loaded over the Internet from a WWW server are subjected to security restrictions by the browser which runs them. Such restrictions include file and network access restrictions. Regarding network access restrictions, the applets are only permitted to connect to the WWW server from which they are downloaded. The Java Proxy Application runs on the WWW server and forwards connections to the SMSC.

No network restrictions are imposed on Java applications, only on Java applets. Note also that file access restrictions are not imposed on Java applications.

The SMS JDK includes Socks V4 support for Java Applications which need to connect across the Internet via a Socks V4 Compliant Firewall or Internet Gateway on a Corporate LAN/Intranet.

While a Socks V5 (Internet) standard has been released, the new functionality it provides is not implemented in the SMS JDK. The reason for this is that most implementations of a Socks V5 compliant firewall come equipped with shared libraries which transparently implement the Socks V5 protocol by intercepting the network calls made by applications (Java or otherwise). See the Socks web site for more information on the Socks protocol.

NOTE: A proxy is software that makes a connection to a server on an application’s behalf. Of course, such an application must first make a connection with the proxy. The two proxies - Sock V4 Compliant Firewalls/Gateways (client side) and the Java Proxy Application (server side) – are discussed in more detail in the sections below.

In the case where a mobile network operator’s SMSC platform is not directly accessible from the Internet, a proxy application must be run on the WWW server from which applets are downloaded. (Note some firewalls may have proxy functionality.)

NOTE: To coincide with future releases of the SMS JDK, an encrypt option will turn on encryption between the proxy application and connecting SMS applets/applications, thus establishing a secure connection between a downloaded applet and a mobile network operators firewall.

To run the Java Proxy application on the WWW server you need to specify the IP address and port number of the SMSC.

To run the application, the following (assuming SUN's JRE - java command) must be entered at the command line

    
java proxy smsc-ip smsc-port local-port [log] [encrypt]
                

The smsc-ip specifies the IP address of the SMSC inside the firewall. The smsc-port specifies the IP port on which the SMPP server is listening (on the SMSC platform).

The local-port tells the Java Proxy Application (running on the WWW server) what IP port to listen on. When incoming calls are detected, a new connection is established with the SMSC by the proxy application and data is forwarded/returned over this connection. SMS Applications/applets should specify this local-port and the IP address of the WWW server when they connect to the SMSC via the proxy.

The log option turns on the log which display a list of IP addresses of client applications as they connect.

Server Side Proxy Diagram
Figure 7 - Server Side Proxy Diagram

An SMS Java Application that needs to connect to an SMSC through a Socks V4 compliant Internet Firewall/Gateway can use the Socks V4 Java class supplied with the SMS-JDK. To use this class, the following must be specified to gain Socks access:-

The Java application using the Firewall/Gateways can specify this by calling the public static method

    
socks.setProxy(String ip, int port, String userid)
                

or

    
socks.setProxy(String ip, int port)
                

When an SMPP connection is being established with the SMSC, the SMS JDK first establishes a connection with the Firewall/Gateway (as specified in socks.setProxy host and port arguments). Once this has been successful, the SMS JDK requests a connection via the firewall to the SMSC server (as specified in the Smpp host and port arguments). See the diagram below.

Client Side Socks V4 Diagram
Figure 8 - Client Side Socks V4 Diagram

For any application (Java or otherwise) that requires access to an SMSC over SMPP, a minimum of three parameters must be configured on the SMSC by the SMSC administrator (on the mobile network operator’s side). These three parameters are:

  • System ID
  • System Type
  • Password

Some SMSC vendors concatenate the System ID and System. Until these parameters are configured on the SMSC, the application will not be able to Bind ( see Smpp.bind(), Binding )

In addition to this, the SMSC administrator may have to configure other attributes such as:

  • default source address consisting of a TON,NPI and MSISDN combination
  • default address range consisting of a TON,NPI and regular expression

The default source address is the originating address of the short message, substituted at the SMSC if none is supplied when a message is sent (see Message.setFrom() ).

The default address range is used only when (i) binding as a receiver and (ii) no address range is specified ( see Smpp.bind, Binding receiver ).

Important : The SMSC may perform certain validations which may reject messages, distribution lists and customer (provisioning) based on source and/or destination addresses, and even reject binding with arbitrary address ranges. Consult with the mobile network operator’s SMSC system administrator to find out what limitations are imposed.

The SMS JDK communicates with the SMSC via SMPP(short message peer to peer protocols) that, in turn, operate over TCP/IP. A platform running an application (that uses the SMS JDK) must have TCP/IP connectivity with the SMSC. Such TCP/IP connectivity can be established in a number of ways:

  • platform and SMSC are on the same (mobile network operator’s) Intranet LAN (Ethernet/Tokenring etc.)
  • platform makes a PPP/SLIP dialup connection to (mobile network operator’s) PPP/SLIP Server terminals on same Intranet LAN as SMSC.
  • platform makes a PPP/SLIP dialup connection to PPP/SLIP server software on the (mobile network operator’s) SMSC
  • platform has a lease line to same WAN/PDSN as (mobile network operator’s) SMSC

In the last solution, X25 may be the underlying protocol for the PSDN (Public Switching Data Network). In such a case, it should be noted that TCP/IP can run over X25. If the SMSC has only X25 connectivity, you will have to check that the SMSC vendor’s platform can run PPP Server software so as to allow (point to point) TCP/IP connectivity over X25. Also, TCP/IP-over-X25 gateway will be required on the client side’s LAN.

Start Of Chapter - Table Of Contents