Manual. Programmer's Guide for Java API

2013-02-01 1 (15) Programmer's Guide for Java API Description This document describes how to develop Content Gateway services with Java API. TS1209243890 1.0 Company information TeliaSonera Finland Oyj Teollisuuskatu 15, 00510 HELSINKI, FI Registered office: Helsinki Business ID 1475607-9, VAT No. FI14756079

2013-02-01 2 (15) Version history Versions Status Modified by Comments 1.0 Approved 01.02.2013 TeliaSonera Finland Oyj Renewed version Table of contents 1 Introduction... 3 1.1 The Content Gateway API Library... 3 1.2 Additional Information... 3 1.3 General Instructions for Using the Java API... 3 2 Developing Applications with Java API... 3 2.1 Developing a Send Only Application... 4 2.2 Developing a Receive Only Application... 6 2.3 Developing a Query/reply Application... 7 2.3.1 Closing a Message Session... 9 2.3.2 Multiple Reply Messages within One Session... 10 2.4 Developing a Push Application... 10 2.5 Messages... 12 2.6 Implementing Positioning Interface... 12 3 Classes and Methods... 14 4 Error Messages in Java API... 14

2013-02-01 3 (15) 1 Introduction Content Gateway Java API is designed to provide a Java programming interface to the Content Gateway platform. API handles all the connections and data transfer between the platform and content/service provider s applications. This document describes the basic principles of creating and running a Content Gateway service with the Java API. Content Gateway Java API provides you with a simple programming interface for developing mobile value added services and applications. Further and more detailed information about class usage can be found in the JavaDoc documentation. 1.1 The Content Gateway API Library The Content Gateway software contains the C++, ActiveX and Java API libraries. The API libraries offer you the following functionalities: Interpreting the SMSC protocol via Provider Server and Operator Server and controlling the functional features of the application. Changes in the SMSC do not generally affect your applications. Converting messages to a format that Provider Server and SMSC understand. Content Gateway currently supports SMS messages in a text or binary format. In mobile terminated messages, the system also supports Nokia Smart Messaging. Performing character set conversions between the SMSC and API. Controlling message handling and routing messages to the correct session instances or call-back functions. Setting parameters for sending messages. Developing TCP/IP socket client applications. The API library communicates with Provider Server, opens the connection and creates the message structure. Developing TCP/IP socket server applications. The API library communicates with Provider Server, opens the connection and creates the message structure. Deleting unnecessary characters from the recipient s MSID number. The MSID number is currently a mobile station number. Controlling sessions automatically. 1.2 Additional Information The supported service types, billing and general guidelines for service and application development are explained in Service Development Guide. 1.3 General Instructions for Using the Java API CGW Java API requires the installation and proper configuration of Content Gateway Provider Server version 3.0 (or newer) and JDK 1.3 (or newer). 2 Developing Applications with Java API The basic function of the Content Gateway platform is to transfer SMS messages between the SMSC and the content/service provider. The transferred messages can be mobile originated (MO) or mobile terminated (MT). One of the important aspects is billing, i.e. charging transactions between the content/service provider and the subscriber. To create successful Content Gateway applications, it is important to understand the concept of a Content Gateway

2013-02-01 4 (15) session. The term session describes a single money transaction, a single service provided to the subscriber. A session may contain several SMS messages, e.g. a traditional weather service session consists of two SMS messages: a MO query from the subscriber and a MT reply from the content/service provider. The session is billed when the subscriber receives the MT reply successfully. This concept is implemented in the Java API. The following three classes are used to handle the Content Gateway sessions: 1. The base class CGW provides the interface to the Content Gateway platform, it creates the connections and manages the sessions. 2. The CGWMessage class represents the actual SMS messages that can be sent by the content/service provider or received from the subscriber. It contains all the necessary information, such as the sender, the recipient and the message text. 3. The CGWSession class stores the status of the Content Gateway session, i.e. sending a CGWMessage always produces an instance of the CGWSession class containing information on the session success. 2.1 Developing a Send Only Application The Send Only mode is a common and simple way to use the Java API. It provides an easy way to create an application that only needs to send messages, e.g. an intranet page calling a Java servlet to send SMS messages. The API will be automatically in the Send Only mode if the callback interface is not used, i.e the class CGW is instantiated. In addition, send methods are always blocking in the Send Only mode, which means that the session status information is available immediately after the message has been sent. The following example illustrates how this can be done: import cgw.*; public class Sender { public Sender() { // Construct the new CGW instance CGW cgw = new CGW(); // send the message and catch the possible exception cgw.send("007", "0101234567", "CGW Java API"); catch (CGWException e) { System.out.println(e); // The main method used to start the sender public static void main(string[] args) { new Sender();

2013-02-01 5 (15) Note that the class CGW instance was created with no parameters. In this case the Java API uses the default values to connect Provider Server at the localhost in port 21772. The constructor could also have been called using specified Provider Server connection settings: CGW cgw = new CGW( server.company.com, 21772); The actual sending is done within a try-catch block, since the send method throws an exception if the sending fails. When the API is in the Send Only mode, you do not have to care about the CGWSession instance the send method returns. The session status will be correct if no exception is thrown. The next example shows how to use the Java API correctly in a Java servlet. The most important thing to notice is that the class CGW should be constructed only once in an application. In a servlet, the correct location is the init() method. This way the connection to Provider Server is kept open and sending messages is faster. If you wish to create a subclass that sends messages, just pass the CGW instance as a reference; do not create a new instance each time the class is used. import javax.servlet.*; import javax.servlet.http.*; import java.io.*; import cgw.*; public class Sender extends HttpServlet { // Define a global CGW instance CGW cgw; public void init(servletconfig config) throws ServletException { super.init(config); // Construct a new CGW instance in servlet init cgw = new CGW(); public void doget(httpservletrequest request, HttpServletResponse response) throws ServletException, IOException { response.setcontenttype("text/plain"); PrintWriter out = new PrintWriter(response.getWriter()); // Read the message and recipient parameters

2013-02-01 6 (15) String recipient = request.getparameter("recipient"); String message = request.getparameter("message"); // send the message and catch the possible exception cgw.send("007", recipient, message); out.println("the message was successfully sent."); catch (CGWException e) { out.println("sending the message failed."); Following examples show how to use Send Only service type with servlet: If you have a servlet engine running in the localhost (default http port 80), you will be able to send SMS messages just by calling the servlet: http://localhost/sms/sender?message=test+message&recipient=0101234567 This would be an easy way to create, for example, a service that sends ringing tones to subscribers. An HTTP interface of Provider Server can be used to receive the SMS request and configured to call the servlet. The Provider Server application type should be set to receive-only for the keyword since the actual ringing tone is sent by the servlet. The application for incoming message configuration would be as follows: http://localhost/sms/sender?message=$(1)&recipient=$(m) The ringing tone could be ordered by sending an SMS, e.g. TONE FINLANDIA and the HTTP request that the servlet gets is: http://localhost/sms/sender?message=finlandia&recipient=0101234567 See the JavaDoc documentation for further details on sending binary Messages. 2.2 Developing a Receive Only Application When an application is designed to receive SMS messages, Java API callback functionality has to be implemented. The callback API is based on an inheritable and overridable architecture. It is very similar to, e.g. the Servlet API. To use the interface in an application, the application class has to be extended from the superclass CGW. The SMS message interface contains two overridable methods in class CGW that handle incoming messages and session status information. By default, the only method that needs to be overridden, is the receive(cgwmessage) method. import cgw.*;

2013-02-01 7 (15) // Inherit the class from superclass CGW public class Receiver extends CGW { public Receiver() { // Start the receiver at default port 21779 this.listen(); catch (CGWException ce) { System.out.println("Receive error: " + ce); // Loop indefinitely while (true) { Thread.sleep(10000); catch (InterruptedException e) { // Override the receive SMS message method public void receive(cgwmessage message) { // Print the text of the incoming message System.out.println("The received message is " + message.getmessage()); // The main method used to start the receiver public static void main(string[] args) { 2.3 Developing a Query/reply Application new Receiver(); The possible reply messages are sent blocked (a confirmation by the SMSC is required before the send() method returns). The following example demonstrates a simple application that receives SMS messages to a local port 21779 from Provider Server and sends back a reply message. The session status information can be found from the returned CGWSession class, although an exception is thrown if an error occurs during the sending.

2013-02-01 8 (15) If you wish to send the reply message non-blocking, you have to set the delivery synchronization off. This can be done with the setdeliverysync() method in the class CGW. In this case the returned CGWSession contains only the message ID of the sent message. The actual session status information has to be received by overriding the receive(cgwsession) method. The information is just printed on the screen: // Override the session status receive method public void receive(cgwsession session) { if (session.isfailed()) { else { System.out.println("Session failed: " + session.getmessageid()); System.out.println("Session ready: " + session.getmessageid()); The previous example assumes that the SMS message was received using a Query/reply type application from Provider Server. This type of a session always requires a reply message in order to close the session and bill the event. The reply can be sent in several ways. The receiver example used the simple send()method that requires only the message text to be able to send the reply. You can send the reply, e.g. by constructing a new CGWMessage. Note that the sender and recipient numbers cannot be altered since the reply should be sent to the actual message sender. public void receive(cgwmessage message) { // Get the text of the incoming message and send a reply CGWMessage reply = new CGWMessage(); reply.settext("from Java API: " + message.gettext()); CGWSession session = this.send(reply); catch (CGWException ce) { System.out.println("Send error: " + ce); It is also possible to reply with the same message instance that was received. Although it would be seemingly possible to change the sender and recipient numbers, the reply will still be sent to the original sender using the same Provider Server application, from which the

2013-02-01 9 (15) message was received. Use this only when the reply is sent to the original sender of the message. public void receive(cgwmessage message) { // Get the text of the incoming message and send a reply message.settext("from Java API: " + message.gettext()); CGWSession session = this.send(message); catch (CGWException ce) { System.out.println("Send error: " + ce); 2.3.1 Closing a Message Session If a reply message has to be sent to a different mobile station than where it came from, the original session has to be either aborted or finished. The session has to be aborted, e.g. in high-priced services where invalid subscriber input would be otherwise billed. However, an informational info message should still be sent to explain the situation. In both cases the reply message has to be sent using a different Provider Server application than from which the message was received. When the incoming message session is aborted or finished, it is possible to freely set the sender and recipient numbers of the new message. You should always create a new message instance when the incoming message session has been finished or aborted, for example to send an error message. public void receive(cgwmessage message) { // Abort the received message (not billed) message.abort(); // Or finish the session (will be billed) message.ready(); // Get the sender of the incoming message and send a reply CGWMessage reply = new CGWMessage("007", message.getsender()); reply.settext("from Java API: " + message.gettext()); CGWSession session = this.send(reply); catch (CGWException ce) { System.out.println("Send error: " + ce);

2013-02-01 10 (15) 2.3.2 Multiple Reply Messages within One Session In some services it is required to send several reply messages to the same subscriber within one session. The number of the replied messages can differ, but the session will be billed as specified in Content Gateway. When all replied messages are sent within the same receivecallback, they will be combined into one session. Provider Server needs to be informed to wait for more messages for the current session by calling the continuesession() method for the incoming message: public void receive(cgwmessage message) { // Create three reply messages and continue session message.continuesession(); CGWMessage reply1 = new CGWMessage("Reply 1: " +message.gettext()); CGWMessage reply2 = new CGWMessage("Reply 2: " + message.gettext()); CGWMessage reply3 = new CGWMessage("Reply 3: " + message.gettext()); CGWSession session1 = this.send(reply1); CGWSession session2 = this.send(reply2); CGWSession session3 = this.send(reply3); catch (CGWException ce) { System.out.println("Send error: " + ce); If the session callback is used, you will receive three separate CGWSession instances, but the session ID will be the same for all of them. The message ID is the same ID that can be found from the returned CGWSession instance for each message. 2.4 Developing a Push Application A Push service with the JAVA API is implemented with the Send Only and Receive Only service types. You can use the same mechanisms as described in chapters 2.1 and 2.2. You need to implement a receiver, which handles incoming push open and close messages (See Service Development Guide). Sending the actual content can be done with the send method. You can define the used application with the method String SetApplication(String application_name). import java.io.*;

2013-02-01 11 (15) import cgw.*; import java.util.*; public class TestSend { // Define a global CGW instance public static void main(string[] args) { CGW cgw; cgw = new CGW(); cgw.sethost("localhost"); cgw.setport(21772); CGWMessage message = new CGWMessage(); // Service name/service id setting message.setapplication("f1"); message.setsender("12121"); message.setrecipient("0101234567"); message.settext("hungary GP result: 1. Fernando Alonso, 2. Kimi Raikkonen, 3. Juan Pablo Montoya."); message.setcharge("78"); message.setbillinginfo("billing info!"); // send the message and catch the possible exception cgw.send(message); System.out.println("The message was successfully sent."); catch (CGWException e) { System.out.println("Sending the message failed."); System.out.println("Exception: " + e);

2013-02-01 12 (15) 2.5 Messages Query/reply service type cannot be used in implementing the whole push functionality, since receiving push orders and sending the actual content needs to be done separately. In order to receive content, the end user needs to have an active push order. There are two possibilities of receiving for example an error message from the API. 1. Java Api has a class CGWException(java.lang.String info). It can be used to catch error messages if message sending fails. As in the following example: // send the message and catch the possible exception cgw.send(message); catch (CGWException e) { System.out.println("Exception: " + e); 2. Class CGWSession has also methods for handling session related messages. Method getinfo() gets a string representation of the message associated with the session. Value is null, if there is no info message available. Otherwise info offers detailed information about the error. For example: // Get detailed info of session if (session.isfailed()) { System.out.println("Session failed: " + session.getmessageid()); System.out.println("Info: " + session.getinfo()); More information about the message handling can be found from JavaDoc documentation. 2.6 Implementing Positioning Interface CGW provides end-user location information if agreed with the operator. The basic positioning data includes end-user coordinates and an estimation of the accuracy. The values (latitude, longitude and estimate) can be read using the methods in the CGWMessage class. Other available position- related data can be read using the getproperty() method. See the JavaDoc documentation for more detailed information. First, configure the service with Provider Admin and ask the operator to add positioning support to your service. Your service ID number is needed. Then write your Java application. For example, an extremely simple Java application that only returns the location coordinates: import cgw.*;

2013-02-01 13 (15) public class SPSExample extends CGW { // Start the listener and loop public SPSExample() throws CGWException { listen(12345); while (true) { Thread.sleep(10000); catch (InterruptedException e) { // Override the receive SMS message method (with positioning) public void receive(cgwmessage message) { // Get parameters from incoming message and send reply String position = "Your position:\n"; position += "Lat: " + message.getlatitude() + "\n"; position += "Lon: " + message.getlongitude() + "\n"; position += "Acc: " + message.getestimate() + "\n"; position += "City: " + message.getproperty("position-city") + "\n"; this.send(position); catch (CGWException ce) { System.err.println("Send error: " + ce); public static void main(string[] args) { new SPSExample(); catch (CGWException e) { System.err.println("Error initializing SPSExample: "+

2013-02-01 14 (15) NOTE e); When positioning is enabled, the end-user MSISDN number is displayed as a position ID that has no relation with the actual MSISDN. However, the ID can be used normally when sending messages to the end-user. 3 Classes and Methods See the JavaDoc documentation about detailed class and method descriptions. 4 Error Messages in Java API Java API can return the following error messages: Error Message listen: Address in use. Change port. listen error Timeout: no response in [ ] seconds Provider Server not responding Connection refused Connection failed op:err session-id: txt:java API: end:err Description The defined port is in use and the listening failed. You need to change the port number or shut down the other listening application. Listening the defined port failed for some other reason. Try again later. The session has not received a response during the defined time -> timeout has occurred. Find out the reason why the response is delayed and fix it. Provider Server does not respond. Check that Provider Server is up and running. Check also that you are trying to connect to it properly. The connection to the defined application is refused. Find out the reason why you cannot connect the application and fix it. The reason can be, for example, insufficient user rights for the application. The connection to the defined application failed for some other reason. CGW error information on the SMS message transaction. An instance of this message is received in the API when sending or receiving a message fails. The error text can be: Error processing message or something that has been defined separately.

2013-02-01 15 (15) Input queue closed Timeout: close processor Message text missing Sender missing Recipient missing Operation type missing Invalid operation type: Operation missing: Message type missing Application missing Cannot open log file Adding customer failed Removing customer failed File read error Cannot read customer file The input queue has been closed for some reason. Try again. The defined timeout has been reached. The message to be sent does not include text. Add the message. The message to be sent does not include the sender. Add the sender. The message to be sent does not include the recipient. Add the recipient. A type for the operation has not been defined (parameter op). You need to define this parameter (delivery, ok, msg, status, err). The defined operation type is unknown. The type should be: Delivery, ok, msg, status or err. A type for the operation has not been defined (parameter end). The message type is missing. Add the message type. The application is missing. Add the application. Opening the log file failed. Try to find out why the log file could not be opened (for example, due to permissions). Adding a customer to the user list failed. Removing a customer from the user list failed. Reading a specified file (text or binary) failed. Reading a customer (User Group) file failed.