Manual Programmer's Guide for other supported protocols - Sonera

ManualDatePage2013-02-01 1 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayProgrammer’s Guide for other supported protocolsDescriptionThis document describes the protocols Content Gatewaysupports.TS1209243890 1.0Company informationTeliaSonera Finland OyjTeollisuuskatu 15, 00510 HELSINKI, FIRegistered office: HelsinkiBusiness ID 1475607-9, VAT No. FI14756079

ManualDatePage2013-02-01 2 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayVersion historyVersions Status Date Modified by Comments1.0 Approved 1.2.2013 TeliaSonera Finland Oyj Renewed versionTable of contents1 PROTOCOLS ............................................................................................................................... 31.1 CGW3 .................................................................................................................................. 31.1.1 Transmission Requirements ...................................................................................... 31.1.2 Service Configuration ................................................................................................. 31.1.3 Protocol errors ........................................................................................................... 41.2 UCP/EMI .............................................................................................................................. 41.2.1 Transmission Requirements ...................................................................................... 51.2.2 Service Configuration ................................................................................................. 51.2.3 Transaction Sequence ............................................................................................... 61.2.4 Supported Operations ................................................................................................ 71.2.5 Protocol errors ........................................................................................................... 71.3 MMS Tunneling with Nokia EAIF .......................................................................................... 71.3.1 Transmission Requirements ...................................................................................... 81.3.2 Service Configuration ................................................................................................. 81.3.3 Transaction Sequence ............................................................................................. 101.3.4 Protocol errors ......................................................................................................... 111.4 SMTP ................................................................................................................................. 111.4.1 Transaction Sequence ............................................................................................. 111.5 HTTP ................................................................................................................................. 121.5.1 Transmission Requirements .................................................................................... 121.5.2 Transaction Sequence ............................................................................................. 121.5.3 Positioning Support with HTTP Protocol .................................................................. 241.5.4 Protocol errors ......................................................................................................... 251.6 OTP - Open Text Protocol .................................................................................................. 261.6.1 Transmission Requirements .................................................................................... 261.6.2 Service Configuration ............................................................................................... 261.6.3 Message Format ...................................................................................................... 281.6.4 Description ............................................................................................................... 281.6.5 Message (op:msg) ................................................................................................... 291.6.6 Immediate Acknowledgement (op:ok and op:err) ..................................................... 311.6.7 Delivery Report (op:delivery) .................................................................................... 321.6.8 Session Status (op:status) ....................................................................................... 331.6.9 Transaction Sequence ............................................................................................. 331.6.10 Positioning Support with OTP Protocol .................................................................. 401.6.11 Protocol errors ....................................................................................................... 432 ERROR MESSAGES ................................................................................................................... 433 APPENDIX ................................................................................................................................... 463.1 Software and Documents ................................................................................................... 463.2 Contact Information ............................................................................................................ 464 GLOSSARY ................................................................................................................................. 46

ManualDatePage2013-02-01 3 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway1 PROTOCOLS1.1 CGW3Content Gateway supports standardized open protocols and the proprietary CGW andCGW3 protocols. You can integrate an application into the Content Gateway platform ifthe application supports one of the following protocols:• CGW, CGW3• UCP/EMI tunneling• HTTP• MMS tunneling (Nokia EAIF)• OTP (Open Text Protocol)• SMTP• SMPP tunnelingIf you wish to integrate an application using UCP/EMI, you must make a separateagreement with the operator. The following chapters describe the protocols and how youcan use the applications with Content Gateway.The Content Gateway software has the ability to handle the CGW3 protocol frame. Theseframes can be created using the CgwApi Library (C++). Check for the Latest Library packagesfrom your Local Content Gateway operator.1.1.1 Transmission RequirementsThe CGW3 protocol uses TCP/IP connections to the Provider Server. Both parties can openthe connection. It depends on which side wants to deliver a message first. The only thing tokeep in mind is that in the service configuration you have to tell the address of your application.The connection is used for two-way communication.1.1.2 Service ConfigurationThe following figures show an example of setting up service using CGW3 protocol. Theapplication URI field is like “cgw://”.

ManualDatePage2013-02-01 4 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayFigure 1. Service Using CGW3 Protocol1.1.3 Protocol errorsApplications may use the CGW3 protocol only through CgwApi Library. All protocol errors arehandled in the API. For more information about errors and exceptions, please see thedocument “Programmer's Guide for C++ API.”1.2 UCP/EMIThe Content Gateway software includes SMS protocol support, EMI (External MachineInterface), which is an extension of UCP (Universal Computer Protocol). EMI is defined in thecommon European ERMES standard of ETSI (European Telecommunication StandardizationInstitute).

ManualDatePage2013-02-01 5 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayContent Gateway’s EMI support uses EMI tunneling, which offers the same interface as adirect connection to the SMSC. The only difference is that messages are routed through theContent Gateway system.1.2.1 Transmission RequirementsTo use EMI tunneling for the connection from Provider Server to the application, you musthave a functioning TCP/IP connection. In addition, you have to decide if you wish to use onewayor two-way transmissions.A one-way transmission means that the IT system sends a message to the mobile station, butdoes not expect an answer. An example of this is a notification of a new email message. Theapplication only needs to send the correct EMI frames to Provider Server and to understandthe reply sent from Provider Server. The reply tells the application whether the transmissionwas successful or not.A two-way transmission means that either the IT system or the mobile station sends amessage and expects an answer. An example of this is a database query. A two-waytransmission requires more from the application: it must always be ready to receive and replyto incoming messages.Before you can send EMI frames, you have to configure your Provider Server to acceptmessage. To configure your Provider Server, open the provider.cnf file, and add following lineto the file:emi-port Port can be any free port.1.2.2 Service ConfigurationBefore you can use the UCP/EMI tunneling, you have to configure your service to identify theapplication that uses the UCP/EMI protocol. The following display shows an example of anUCP/EMI service configuration. The application URI field is like “emi://”.

ManualDatePage2013-02-01 7 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gatewayframe is called an operation (O) and a reply to that operation is called a result (R). Thetransaction begins from an application or from a mobile station.A transaction sequence is a string of successive EMI operations and results forming asuccessful or unsuccessful message transmission. The transaction sequence variesdepending on the operation type and on the originator of the transaction.To separate the transactions from each other and to prevent overlapping transactions,Provider Server sets a transaction number for each transaction. Provider Server then attachesthe same transaction number to the operation and the result of the operation.1.2.4 Supported OperationsWhen you send an SMS message from your EMI application, you can use three different typesof send operations and one type of alert operation. The operations are as follows:• “Call Input Operation” OT = 01 (send)• “GSM Text Message Transfer” OT = 30 (send)• “Submit Short Message Operation” OT = 51 (send)• “Alert” OT = 31 (alert)Provider Server can use two different receive operations and one delivery operation. Theoperations are as follows:• “Call Input Operation” OT = 01 (receive)• “Delivery Short Message Operation” OT = 52 (receive)• “Delivery Notification Request” OT = 53 (delivery)1.2.5 Protocol errorsUCP/EMI messages are mainly just passed through the Content Gateway system. Also theerror messages are passed through the system, making Content Gateway a transparent tunnelbetween service application and SMSC. Content Gateway may also itself generate UCP/EMIerror responses if the message being delivered is not valid, or the processing was notsuccessful for some other reason. Otherwise, the error responses that the service applicationmay receive depend on how the particular SMSC behaves.If the UCP/EMI message handling fails in the Content Gateway, no matter what is the reason,a proper UCP/EMI negative result message is returned back to the service application. Forexample, if handling Submit Short Message operation (51) fails, the Content Gateway willrespond with Submit Short Message operation (negative result). The error code (EC) in theerror message is usually 02, which stands for syntax error. The system message (SM) in theerror message contains the text of one of the Content Gateway error messages. Errormessages are listed at the end of this document.1.3 MMS Tunneling with Nokia EAIFThe Content Gateway software includes support for the MMS protocol allowing you to createapplications that can send MMS messages to mobile terminals and receive MMS messagesfrom mobile terminals. Content Gateway’s MMS protocol support is based on MMS tunneling,

ManualDatePage2013-02-01 8 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gatewaywhich offers the same interface as a direct connection to the MMSC. The only difference is thatmessages are routed through the Content Gateway system. You must sign a separateagreement with the operator if you wish to use MMS tunneling.Currently, Content Gateway supports Nokia MMSC (EAIF). A Java API that can be used todevelop MMS applications for Nokia MMSC is available at www.forum.nokia.com.1.3.1 Transmission RequirementsMMS tunneling uses the HTTP port to send and receive messages so your Provider Servermust be configured to accept HTTP requests. Add the HTTP port number to your provider.cnffile. For example, add the following line for the port 7080:http-port 7080The operator places a limit on the maximum size of a message that you can send or receive(you can check this with your operator).1.3.2 Service ConfigurationOpen Provider Admin and configure a service. If you have permission to use MMS tunneling,you can specify any of your existing licensed short numbers in the Short number field. BothSMS and MMS services can use the same short numbers, but you should only define oneMMS service for each short number. The following display shows an example of an MMSservice configuration.

ManualDatePage2013-02-01 9 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayFigure 4. Service Using MMS TunnelingIf you wish the MMS service to receive messages, the Application URI should be configuredto the IP address and port that the application is listening on, e.g.http://localhost:7879/receiveMMS.

ManualDatePage2013-02-01 10 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway1.3.3 Transaction Sequence1.3.3.1 Sending Messages to a Mobile TerminalThe MMS application should send the MMS to recipient through Provider Server’s HTTP port.Provider Server will identify the service using the ‘cgw-serviceid’ HTTP header. If header is notavailable, default service with service id 1 (“send” service) will be used. The format of theHTTP POST request is shown below.POST / HTTP/1.1x-nokia-mmsc-message-type: MultiMediaMessagex-nokia-mmsc-from: 54202/TYPE=PLMNx-nokia-mmsc-to: +358101234567/TYPE=PLMNcontent-type: application/vnd.wap.mms-messagecontent-length: 495cgw-serviceid: 1002host: localhost:70801.3.3.1.1 Response Messages from Provider Server to ApplicationWhen a message is sent to a recipient, Provider Server sends a reply message to theapplication. If the message delivery is successful, Provider Server sends the following reply:HTTP/1.1 204 No contentIf there was a problem with the message header/contents, and message delivery fails,Provider Server sends back 4xx or 5xx series error HTTP response. Response line containsreason for error. Replies may be:HTTP/1.1 400 Missing recipient address in message.HTTP/1.1 400 Missing sender address in message.HTTP/1.1 400 Service xxx not found.HTTP/1.1 400 Service usage is restricted by whitelist.HTTP/1.1 400 Service usage is restricted by restriction class.HTTP/1.1 400 Sending MMS messages is restricted by license.1.3.3.2 Receiving a Message from a Mobile TerminalAfter receiving a message, the Provider Server will identify the appropriate MMS application bythe short number in the recipient field of the message. Then it will send the message to thatapplication by issuing an HTTP POST request on the address defined in that service’sconfiguration. An example:POST /receiveMMS HTTP/1.1content-type: application/vnd.wap.mms-messagehost: localhost:7879

ManualDatePage2013-02-01 11 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gatewayx-nokia-mmsc-from: +358101234567/TYPE=PLMNx-nokia-mmsc-message-id: PONLz8OcGWUAABb@AAAABgAAAAYAAAAAx-nokia-mmsc-message-type: MultiMediaMessagex-nokia-mmsc-to: 17222/TYPE=PLMNx-nokia-mmsc-version: 1.1Content-Length: 4951.3.3.2.1 Response Messages from Application to Provider ServerThe receiving application must reply with a message back to Provider Server and this shouldbe of the following format:HTTP/1.1 204 No ContentIf there was a problem with the message, the receiving application can indicate that by sendinga reply with a response code that indicates the error. Any value other that the 2XX codes willbe taken as an error. The 4XX series errors are permanent and the MMSC does not attempt toresend the message. The 5XX series errors are temporary and the MMSC will resend themessage after a short delay.1.3.4 Protocol errorsThe EAIF messages are mainly just passed through the Content Gateway system. Also theerror messages are passed through the system, making Content Gateway a transparent tunnelbetween the service application and MMSC. Content Gateway may also itself generate EAIFerror responses if the message being delivered is not valid, or the processing was notsuccessful for some other reason. Otherwise, the error responses that the service applicationmay receive depend on how the particular MMSC behaves.1.4 SMTPIf the EIAF message handling fails in the Content Gateway, no matter what is the reason, aproper EAIF response is returned back to the service application. The status line of the HTTPresponse message contains a response-code and response-phrase. The phrase contains thetext of one of the Content Gateway error messages. Error messages are listed at the end ofthis document.The Content Gateway software includes support for SMTP (Simple Mail Transfer Protocol).SMTP is used to send e-mail messages between servers or between mail client and mailserver.Use of SMTP protocol is done with the help of SMTP Gateway, which is described in ServiceDevelopment Guide document.1.4.1 Transaction SequenceThe SMTP model of communication starts with user mail request after which, sender-SMTPestablishes a two-way transmission channel to a receiver-SMTP. The SMTP commands aregenerated by the sender-SMTP and send to the receiver-SMTP. SMTP replies are sent fromthe receiver-SMTP to the sender-SMTP in response for the commands.

ManualDatePage2013-02-01 12 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway1.5 HTTPWith the HTTP protocol you can create applications that send SMS and MMS messages tomobile terminals. You can also create a static or dynamic web page and query the content ofthe web page with a mobile terminal.Provider Server operates as a simple web server. It accepts correctly formatted HTTPrequests from applications and routes the requests to mobile terminals. Provider Server canalso convert a message sent from a mobile terminal to an HTTP request, fetch the requestedpage from a web server, convert the page to plain text, and send the page to the mobileterminal as an answer to the request.Content Gateway’s HTTP support follows RFC2068 (HTTP/1.1). However, all features in theprotocol are not implemented.1.5.1 Transmission RequirementsBefore you can send messages with HTTP requests, you have to configure your ProviderServer to accept the requests. To configure your Provider Server, open the provider.cnf file,and add the following line to the file:http-port The port number can be any free port. If you run a web server on the same computer, thedefault ports (80 and 8080) are probably reserved. In that case, use another port for HTTP.It is necessary to define this port only once; all applications can use the same port.1.5.2 Transaction Sequence1.5.2.1 Sending Messages to a Mobile TerminalWith the Content Gateway HTTP support, you can send an HTTP message to a mobileterminal:Open Provider Admin and click and configure a Send Only service. You can also use the preconfiguredservice Send.In the HTTP application, type a request of the following format in the URL field:AN EXAMPLEhttp://:/?http://localhost:80/send?from=1234&to=0101234567&msg=HelloYou can test this with a web browser. The following table shows the parameters you can use inthe request. The parameters in brackets are optional.Parameter Value DefinitionFrom Sender number Your Short Number or other phone numberTo Recipient number The recipient’s mobile terminal number.You can send the message to multiple recipients byadding each recipient’s mobile terminal number as ato parameter.Msg Message The message

ManualDatePage2013-02-01 13 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gatewaytext/Binarymessage in hextext[nrqurl] Any URL address Address where to send delivery notification.If you wish to receive a notification when the messageis delivered, add this parameter to the command. Thenotification tells you that the message is delivered orthat it is buffered to wait for a later delivery.NOTE, that URL address must be URL encoded. If youwish to receive delivery notification to:http://company.com:12345/NRQReceive?from=cgwparameter value must be written like:…&nrqurl=http%3A%2F%2Fcompany.com%3A12345%2FNRQReceive%3Ffrom%3Dcgw…[ddt] DDMMYYYYhhmm The delivery time of the messageDefine the time in the format DDMMYYYYhhmm.DD = The day with two digitsMM = The month with two digitsYYYY = The year with four digitshh = The hour with two digitsmm = The minutes with two digitsFor example, if you wish the message to be sent at12:33 on October 6th 2000, define the time as061020001233.[vp] Minutes The validity period for the message.If the SMSC cannot deliver the message immediately,the message is buffered in the SMSC until it can bedelivered or until the validity period has elapsed.[bin] Any The message is a binary message[udh] UDH in hex text User Data Header information.Check that the UDH header multiplied by 8/7 androunded up to the nearest integer value plus the lengthof text message do not exceed 160 characters.If the message is a binary message, the size of theUDH header and the size of the message must notexceed 140 bytes.Do not use the UDH parameter with the smartparameter.[mcl] Class number The message class.Defines where the received message is stored in themobile terminal. The classes are as follows:0 = Displays the message (flash) on the displayimmediately, but does not store the message1 = Mobile terminal specific2 = The message is stored on the SIM card.3 = Terminal equipment specific

ManualDatePage2013-02-01 14 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayDo not add this parameter to the command if you donot know how the mobile terminal functions with thisparameter.[smart] Port number Smart messaging destination and originator ports.If the message (the msg parameter) is over 160characters long, the server splits the message tocorrectly sized parts, sets the correct UDH for eachpiece, and sets the message class to 1.Remember to use the bin parameter if the content is abinary message in hex text.[charge] Price in cents Proposed message price. This price might have effecton the real message price only if you have agreed sowith your operator.[info]Billing informationreferenceThe actual value of this reference must be agreed withthe billing organization case by case.In the following examples, Provider Server is on the same machine as the application. TheHTTP port parameter is set to 8085.EXAMPLE 1This example sends the message “Hello mobile user!” to one recipient (the mobile terminalnumber 0101234567).EXAMPLE 2http://localhost:8085/send?to=0101234567&from=12345& msg=Hello+mobile+user!This example sends the same message to two recipients.EXAMPLE 3http://localhost:8085/send?to=0101234567&to=0101234568&from=12345&msg=Hello+mobile+user!This example sends a binary message to the same recipient.EXAMPLE 4http://localhost:8085/send?to=0101234567&from=12345& msg=FAE1090012&bin=1This example sends a ringing tone.EXAMPLE 5http://localhost:8085/send?to=0101234567&from=12345&bin=1&msg=013A594D85B5C1B194080A1718DBE92C449121022CAB081000&smart=5505This example sends a caller group icon.EXAMPLE 6http://localhost:8085/send?to=0101234567&from=12345&bin=1&smart=5507&msg=000A0A0180000002008020000000002000

ManualDatePage2013-02-01 15 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayThis example sends an operator logo.http://localhost:8085/send?to=0101234567&from=12345&bin=1&smart=5506&msg=42F419000A0A0180000002008020000000002000NOTE: If you get “HTTP Status 404: The requested resource (…) is not available.” errormessage, or get an authentication window, then you have to check the http port you are using.It is probably the http administration port of the Provider Server, and you should use the plainhttp port defined for application usage.If you get “Cannot find server” then the other end is not working, or the URL’s connection is notcorrect. In that case, check Provider Server and the URL.1.5.2.1.1 Response Messages from Provider Server to ApplicationWhen a message is sent to a recipient, Provider Server sends a reply message to theapplication. If the message delivery is successful, Provider Server sends the following reply:HTTP/1.1 200 OkContent-length: nnContent-type: text/htmlSending SMS resultDelivery result: : The status can have three different values: success, delayed, or failure.EXAMPLE 7Success: 0101234567: Delivered to the SMSCIf there was a problem in the delivery and Provider Server can immediately identify theproblem, it sends the following reply:HTTP/1.1 400 Content-type: text/plainContent-length: nnError messageIf there was a problem in handling message, Operator Server sends the following reply:HTTP/1.1 401 Content-length: nnContent-type: text/html Sending SMS resultDelivery resultError message Failure: :1.5.2.2 Querying the Content of a Web Page from a Mobile TerminalWith the HTTP protocol support, you can read the content of a web page with your mobileterminal. To configure the service, open Provider Admin and configure a Query/reply service.The following figure shows an example of an HTTP service configuration. The application URIfield is like “http://”.

ManualDatePage2013-02-01 16 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayFigure 5. Service Using HTTP ProtocolTo define which section of the web page to send to the mobile terminal, enter the start and endtags in the Start tag and End tag fields. The tags can contain any kind of text.You can use the following variables in the URL, Start tag, and End tag fields:

ManualDatePage2013-02-01 17 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayVariable$(M) or$(MSISDN)$(R) or$(RECIPIENT)$(number)ValueThe sender’s numberThe recipient number. In practice, a short number.The n’th word from the message body. $(1) is first word, $(2) thesecond, etc.If the message is a binary message, the first word is themessage in the hexadecimal text format.$(*) The words in the message separated with the + character.$(*c)The words in the message separated with the character specifiedafter the asterisk.$[] The next word in the message. When this occurs for the firsttime in the URL, it is replaced with the first word after thekeyword. The next occurrence is replaced with the second wordafter the keyword and so on.$[DEF:text]The next word in the message. When this occurs for the firsttime in the URL, it is replaced with the first word after thekeyword. The next occurrence is replaced with the second wordafter the keyword and so on. If there is no word to insert,“text” after DEF: is inserted.$[*] The words in the message excluding the keyword separated with$[*c]$(MSG)the + character.The words in the message excluding the keyword separated withthe character specified after the asterisk.The full message content. Non-safe characters in the URL arereplaced with %. For example, the string“AB ÄA” is converted to “AB%20%C4A”.$(POSITION- LATITUDE) The Latitude of the mobile terminal. You need an agreementwith the operator in order to receive this information.$(POSITION-The Longitude of the mobile terminal. You need an agreementLONGITUDE)with the operator in order to receive this information.$(POSITION- ESTIMATE) An error estimate of the position of the mobile terminal. Youneed an agreement with the operator in order to receive thisinformation.___________________________________________________________________________NOTECharacter + means space. For example: “+358 “ means “ 358”. If you wish to use internationalMSISDN number, you need to use the hexadecimal format of +. For example “+358” should be“%2B358”.___________________________________________________________________________To query the content of a web page, send an SMS message that begins with the configuredkeyword from your mobile terminal to your Short Number. Provider Server makes an HTTPrequest to the web server and searches the web page specified in the service setup with the

ManualDatePage2013-02-01 18 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gatewaystart and end tags. It converts the content between the tags to the text format and sends it as areply to the mobile terminal.1.5.2.2.1 URL ConversionWhen the mobile terminal user sends a message to the HTTP service, Provider Serverconverts the SMS message to an HTTP request and replaces the variables in the URL with themessage words. The following examples illustrate the conversion.The message in the examples is “this is an example” and the sender’s mobile terminal numberis 0101234567. The keyword for the service is this.EXAMPLE 1EXAMPLE 2EXAMPLE 3EXAMPLE 4EXAMPLE 5EXAMPLE 6http://www.company.com/smpl?one=$(1)&two=$(2)->http://www.company.com/smpl?one=this&two=ishttp://www.company.com/smpl?one=$(*)&sender=$(M)->http://www.company.com/smpl?one=this+is+an+example&sender=0101234567http://www.company.com/smpl?one=$(*X)&sender=$(M)->http://www.company.com/smpl?one=thisXisXanXexample&sender=0101234567http://www.company.com/smpl?one=$[]&two=$[]->http://www.company.com/smpl?one=is&two=anhttp://www.company.com/smpl?one=$[*]&sender=$(M)->http://www.company.com/smpl?one=is+an+example&sender=0101234567http://www.company.com/smpl?one=$[*X]&sender=$(M)->http://www.company.com/smpl?one=isXanXexample&sender=0101234567EXAMPLE 7, RECEIVED BINARY MESSAGEhttp://www.company.com/smpl?one=$(1)->http://www.company.com/smpl?one=FAF11899ABBA

ManualDatePage2013-02-01 19 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway1.5.2.2.2 Get RequestAfter the conversion, Provider Server makes a GET request to the converted URL. The formatof the GET request follows RFC2068:GET / HTTP/1.1Accept: */*Character-set: iso8859-1User-Agent: CGW Provider Server 4.0Host: [:]AN EXAMPLE OF THE GET REQUESTGET /smpl?one=this&two=is HTTP/1.1Accept: */*Character-set: iso8859-1User-Agent: CGW Provider Server 4.0 Host:www.company.comThe request does not contain other parameters.When the service is defined as a positioning service, the request contains four extraparameters in the http headers. Remember that you need an agreement with the operator inorder to receive this information. With positioning services you will not receive the realMSISDN of the sender but the encrypted position ID instead. You can read more about HTTPPositioning from chapter 1.6.3 of this document.ParameterDescriptionPosition-Latitude The Latitude of the mobile terminalPosition-Longitude The Longitude of the mobile terminalPosition-estimate An error estimate of the position of the mobileterminalPosition-IDThe ID that replaces the sender MSISDN. Note that this ID isabout 40 characters Long.AN EXAMPLE OF THE GET REQUEST WITH TERMINAL POSITION INFORMATIONGET /smpl?one=this&two=is HTTP/1.1Accept: */*Character-set: iso8859-1User-Agent: CGW Provider Server 4.0Host: www.company.comPosition-latitude: 60.1234455Position-longitude: 25.112213Position-estimate: 300Position-ID: PABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB

ManualDatePage2013-02-01 20 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway1.5.2.2.3 Response Messages from Provider Server to Mobile TerminalAfter the GET request, Provider Server sends the reply to the mobile terminal. Provider Serverunderstands replies that follow RFC2068. You can define the reply parameters in the HTTPapplication or in the web page. The content-type parameter defines how Provider Serverprocesses the content of the reply. The content-type parameter can be, e.g. text/html, text/hex,text/.Content-type: text/htmlIf you have defined the start and end tags in the service setup, the reply contains all textbetween the tags. Before the application sends the reply to the mobile terminal user, itremoves all HTML tags from the reply and converts the result to plain text. Then theapplication sends the reply as a plain text message to the recipient. The length of the reply textis limited with the Max SMS setting. If tags are not found and an abort message is defined, theabort message will be send to mobile terminal.This conversion method is very simple and does not always convert complex pages correctly.The conversion removes all extra spaces from the message.AN EXAMPLE OF A REPLY TO A REQUESTHTTP/1.1 200 OKServer: Netscape-Enterprise/3.5.1GDate: Wed, 28 Jun 2000 17:14:27 GMTContent-type: text/htmlEtag: "460e-218-38219d08"Content-length: 156This is an example ExampleThis message is delivered to phone.The start tag defined in the service setup is and the end tag is . The reply sentto the mobile terminal is as follows:This message is delivered to phone.If the start and end tags were not defined in the service setup, the reply sent to the mobileterminal would be as follows:This is an example Example This message is delivered to phone.Content-type: text/hexThe content of the text is hex coded binary data. The application converts the text to binarydata, and the reply sent to the mobile terminal is in binary data.AN EXAMPLE OF A REPLY TO A REQUEST

ManualDatePage2013-02-01 21 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayHTTP/1.1 200 OKServer: Netscape-Enterprise/3.5.1GDate: Wed, 28 Jun 2000 17:14:27 GMTContent-type: text/hexF9AF889147E71200121245ABContent-type: text/The application reads all content-types beginning with text/ (excluding text/html and text/hex)directly from the web page, and sends the reply to the mobile terminal. The message length islimited to 160 characters.AN EXAMPLE OF A REPLY TO A REQUESTHTTP/1.1 200 OKServer: Netscape-Enterprise/3.5.1GDate: Wed, 28 Jun 2000 17:14:27 GMTContent-type: text/plainThis is a reply to your messageOther content-typesThe application handles other content-types as binary data and sends them to the mobileterminal as binary messages.CGW-specific parametersWhen you write the reply to an HTTP request, you can use Content Gateway specific HTTPparameters in the reply. Use these parameters only with Content Gateway. The parametersare as follows:Parameter Value Definitioncgw-nrqurl Any Address where to send delivery notification.If you wish to receive a notification when themessage is delivered, add this parameter to thecommand. The notification tells you that themessage is delivered or that it is buffered to wait for alater delivery.cgw-ddtDDMMYYYYhhmm The delivery time of the messageDefine the time in the format DDMMYYYYhhmm.DD = The day with two digitsMM = The month with two digitsYYYY = The year with four digitshh = The hour with two digitsmm = The minutes with two digitsFor example, if you wish the message to be sent at12:33 on October 6th 2000, define the time as061020001233.cgw-vp Minutes The validity period for the messageIf the SMSC cannot deliver the message immediately,

ManualDatePage2013-02-01 22 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gatewaythe message is buffered in the SMSC until it can bedelivered or until the validity period has elapsed.cgw-udh UDH in hex text User Data Header informationCheck that the UDH header multiplied by 8/7 androunded up to the nearest integer value plus the lengthof text message do not exceed 160 characters.If the message is a binary message, the size of theUDH header and the size of the message must notexceed 140 bytes.Do not use the UDH parameter with the smartparameter.cgw-mcl Class number The message classDefines where the received message is stored in themobile terminal. The classes are as follows:0 = Displays the message (flash) immediately on thedisplay, but does not store the message.1 = Mobile terminal specific2 = The message is stored on the SIM card.3 = Terminal equipment specificDo not add this parameter to the command if you do notknow how the mobile terminal functions with thisparameter.cgw-smart Port number Smart messaging destination and originator ports.If the message (the msg parameter) is over 160characters long, the server splits the message tocorrectly sized parts, sets the correct UDH for eachpiece, and sets the message class to 1.Remember to use the bin parameter if the content is abinary message in hex text.Cgw-charge Price in cents Proposed message price. This price might have effecton the real message price only if you have agreed sowith your operator.The following example sends as a reply a flash message directly to the mobile terminal’sdisplay.EXAMPLEHTTP/1.1 200 OKServer: Netscape-Enterprise/3.5.1GDate: Wed, 28 Jun 2000 17:14:27 GMTcgw-mcl: 0Content-type: text/plainThis is a reply to your message and it should be visible on your screen.The following example sends as a reply a ringing tone to the mobile terminal.

ManualDatePage2013-02-01 23 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayEXAMPLEHTTP/1.1 200 OKServer: Netscape-Enterprise/3.5.1GDate: Wed, 28 Jun 2000 17:14:27 GMTcgw-smart: 5055Content-type: text/hex013A594D85B5C1B194080A1718DBE92C449121022CAB08100

ManualDatePage2013-02-01 24 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway1.5.3 Positioning Support with HTTP ProtocolFirst configure your service with Provider Admin and ask the operator to add positioningsupport to your service. The service ID number is needed when the support is added.Figure 6. Example for HTTP Positioning Service

ManualDatePage2013-02-01 25 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayThe content/service provider can use the location information from HTTP headers. Then theURL does not need to contain any position-specific parameters. Alternatively, you can add theposition information to the URL.Then create your web application that either reads HTTP headers or parses the URLparameters. The HTTP request can be as follows:GET /whereami?lat=60.1234455&lon=25.112213&est=300 HTTP/1.1Accept: */*Character-set: iso8859-1User-Agent: CGW Provider Server 4.0Host: www.company.composition-latitude: 60.1234455position-longitude: 25.112213position-estimate: 300position-citycode: 91position-city: helsinkiposition-postcode: 00510Position-ID:PABABABABABABABABABABABABABABABABABABABABABABABABReply to this message as normal. For example valid reply is the following:HTTP/1.1 200 OKServer: Netscape-Enterprise/3.5.1GDate: Wed, 28 Jun 2000 17:14:27 GMTContent-type: text/htmlYou are in Helsinki.______________________________________________________________________NOTEError message configuration is not supported with positioning services, because the errormessage is delivered via the Send Only service._______________________________________________________________________1.5.4 Protocol errorsIf HTTP request handling fails in the Content Gateway, no matter what is the reason, a properHTTP response is returned back to the service application. The status line of the HTTPresponse message contains a response-code and response-phrase. The phrase contains thetext of one of the Content Gateway error messages. Error messages are listed at the end ofthis document.

ManualDatePage2013-02-01 26 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway1.6 OTP - Open Text ProtocolThe Open Text Protocol (OTP) is a text-based TCP/IP socket protocol slightly resembling theSMTP protocol. This Content Gateway specific protocol supports the following service types:Send Only and Receive Only and Query/reply. The protocol provides an open interface fordevelopers using programming languages other than C++. The Java API is actually built on theOTP, which means that when you have an application that is developed with the ContentGateway Java API, you must configure the service provided by the application as an OTPservice (the URL begins with text://) in Provider Admin.1.6.1 Transmission RequirementsBefore an application using OTP can connect to the Content Gateway system, you have toconfigure Provider Server to accept the Open Text Protocol connections. To configure ProviderServer, open the provider.cnf file, and add the following line to the configuration:text-port The port number can be any free port. By default, the Java API uses the port 21772. It isnecessary to define this port only once. All applications can use the same port. Only the SendOnly services need this configuration; other services use the configuration in the ServiceSetup. Remember to restart Provider Server after this configuration has been changed.You can test the port with the telnet application. Connect to the configured port, for exampletelnet localhost 21772Provider Server should answerhello:Provider Server Version 4.0 ready.You can close the connection by enteringquit:Remember that the line termination character is the linefeed.1.6.2 Service ConfigurationTo configure Receive Only applications, open Provider Admin, click New Receive onlyservice and configure the service settings for your application.The following display shows an example of an Open Text Protocol service configuration. Theapplication URI field is like “text://”.

ManualDatePage2013-02-01 27 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayFigure 7. Service for Using OTP Protocol

ManualDatePage2013-02-01 28 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway1.6.3 Message FormatAll lines in the message must be in the following format::\n________________________________________________________________NOTEDo not enter a space between the parameter name and the colon. Provider Server removes allspaces between the colon and the values. The line ends with the termination character LF =ASCII 10 = \n.________________________________________________________________The maximum length of a line including the parameter name to the termination character is2,000 characters. In all messages, parameters and values the character set is ISO8859-1(Latin1). Parameters and values are not case sensitive.All messages begin with the op parameter and the message name. The message ends withthe end parameter and the message name. The order of other parameters is free.AN EXAMPLEop:msg... message content ...end:msg1.6.4 DescriptionThe description of the Open Text Protocol is as follows:LF = SP = CHAR= hello= "Provider Server Version 4.0 ready."message= op-msg | op-ok | op-err| op-delivery | op-statusop-msg= "op:msg" LF*(msg-parameter ":" parameter-value LF)"end:msg" LFop-ok= "op:ok" LF*(ok-parameter ":" parameter-value LF)"end:ok" LFop-err= "op:err" LF*(err-parameter ":" parameter-value LF)"end:err" LFop-delivery= "op:delivery" LF*(delivery-parameter ":" parameter-value LF)"end:delivery" LFop-status= "op:status" LF*(status-parameter ":" parameter-value LF)"end:status" LF

ManualDatePage2013-02-01 29 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gatewaymsg-parameter = "app" | "session-id" | "client-id" |"to" | "from" | "session-control" |"nrq" | "ddt" | "vp" | "udh" | "mcl" |"type" | "smart" | "info" | extra-parameterok-parameter= "session-id" | "count" | "txt"err-parameter= "session-id" | "count" | "txt"delivery-parameter = "session-id" | "client-id" | "msid" |"status" | "txt"status-parameter = "session-id" | "client-id" | "session-control"parameter-valueextra-parameter= +(CHAR)= 1.6.5 Message (op:msg)The op:msg message operation is used for transferring the actual content of an SMSmessage. The op:msg message can be sent by the application or by Provider Server as aresult of a message from a mobile terminal user.The sender can add the following parameters to the op:msg message. The parameters inbrackets are optional.Parameter Value Definitionapp Service name The name of the service as defined in Provider Adminto Recipient number The recipient’s numberYou can send the message to multiple recipients in theSend Only services by adding each recipient as a toparameter.from Sender number The sender’s mobile terminal number or another phonenumber.The recipient sees this number as the sender’s number.msg Message text /Binary message inhex text[session-id]Any string lessthan 20 charactersThe messageThe op:msg operation can contain any number of msglines. The system concatenates the text in separate lineswhen the message is sent.In a plain text message you can use the followingescapes:\n = Line feed ASCII (10)\r = Carriage return ASCII (13)\\ = Backslash characterThe current transaction’s session IDYou do not need to define the session ID for the SendOnly services. Provider Server generates the session IDfor them and for mobile originated messages and reportsthe session ID in the op:ok operation.If the message is a reply to a mobile originated message,the session ID must be the same as the original

ManualDatePage2013-02-01 30 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway[client-id][sessioncontrol]Any string lessthan 20 charactersabort, ready, contmessage’s session ID.The client application’s IDThe application can set a client ID to a mobile terminatedmessage. All messages that relate to that message andhave the same session ID have the same client ID.Session status controlUse this parameter only in a reply to a mobile originatedmessage. This parameter controls the session status. Youcan define the following values for the parameter:Ready (default) = Kills the session and gives thetransaction a Success status.Abort = Kills the session and gives the transaction anInterrupt status.Cont = Does not kill the session. The mobile can replywith same session ID.If you do not define the session-control parameter, thetransaction gets the default value Ready.[nrq] Any The delivery notification requestIf you wish to receive a notification when the message isdelivered to the mobile terminal, add this parameter to thecommand. The notification tells you that the message isdelivered or that it is buffered to wait for a later delivery.[ddt]DDMMYYYYhhmm The delivery time of the messageDefine the time in the format DDMMYYYYhhmm.DD = The day with two digitsMM = The month with two digitsYYYY = The year with four digitshh = The hour with two digitsmm = The minutes with two digitsFor example, if you wish the message to be sent at 12:33on October 6th 2000, define the time as 061020001233.[ddt] mmmmm Delivery time in minutes[vp] Minutes The validity period for the message.If the SMSC cannot deliver the message immediately, themessage is buffered in the SMSC until it can be deliveredor until the validity period has elapsed.[type] asc|bin asc = The message is a plain text message.bin = The message is a binary message coded as hextext.AN EXAMPLE: 3BF01995FF0012E4push-XML = A push XML messageIf you do not give the any type-parameter, the applicationsends the message as plain text.[udh] UDH in hex text User Data Header information.Check that the UDH header multiplied by 8/7 and roundedup to the nearest integer value plus the length of text

ManualDatePage2013-02-01 31 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gatewaymessage do not exceed 160 characters.If the message is a binary message, the size of the UDHheader and the size of the message must not exceed 140bytes.Do not use the UDH parameter with the smart parameter.[mcl] Class number The message classDefines where the received message is stored in themobile terminal. The classes are as follows:0 = Displays the message (flash), like a cell broadcast,but does not store the message1 = Mobile terminal specific2 = The message is stored on the SIM card3 = Terminal equipment specificDo not add this parameter to the command if you do notknow how the mobile terminal functions with thisparameter.[smart] Port number The smart messaging destination and originator portsIf the message (the msg parameter) is over 160characters long, the server splits the message to correctlysized parts, sets the correct UDH for each piece, and setsthe message class to 1.Remember to use the bin parameter if the content is abinary message in hex text.[charge] Price in cents Proposed message price. This price might have effect onthe real message price only if you have agreed so withyour operator.[info][positionlatitude][positionlongitude][positionestimate][position-id]Billing informationreferenceThe actual value of this reference must be agreed with thebilling organization case by case.The latitude of the mobile terminal. You need anagreement with the operator in order to receive thisinformation.The longitude of the mobile terminal. You need anagreement with the operator in order to receive thisinformation.An error estimate of the position of the mobile terminal.You need an agreement with the operator in order toreceive this information.The ID that replaces the sender MSISDN. Notice that thisID is about 40 characters long.1.6.6 Immediate Acknowledgement (op:ok and op:err)When Provider Server receives an op:msg message, it checks the message for errors. IfProvider Server does not find any errors in the message, it sends an op:ok message as a replyto the sender of the original message. If Provider Server finds an error in the message, it

ManualDatePage2013-02-01 32 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gatewaysends an op:err message as a reply to the sender. The application can also check the op:msgmessage for errors and send the op:ok or op:err message.The application must also reply to Provider Server with op:ok or op:err immediately afterreceiving op:msg.The op:ok and op:err messages must be sent to the same connection where the originalmessage came.Parameter Value Definitionsession-id Any stringless than 20charactersThe current transaction’s IDProvider Server generates the session ID if necessary. Theapplication replies with the same session ID as in theclient-idAny stringless than 20charactersoriginal op:msg.The client application’s IDThe application can set a client ID to a mobile terminatedmessage. All messages that relate to that message andhave the same session ID include the client ID.count Number The number of SMS messages generated from a longmessage. The value can be over 1 only if you have set thesmart parameter in the op:msg.txt Text A description of the error1.6.7 Delivery Report (op:delivery)Provider Server sends an op:delivery delivery report when the op:msg is delivered to theSMSC. If you give the nrq parameter in the op:msg message, Provider Server sends theop:delivery delivery report when the SMSC delivers the message to the mobile terminal.Parameter Value Definitionsession-id Any stringless than 20charactersThe current transaction’s IDProvider Server generates the session ID if necessary. Theapplication replies with the same session ID as in theclient-idmsidstatusAny stringless than 20charactersRecipientnumberStatusnumberoriginal op:msg.The client application’s IDThe application can set a client ID to a mobile terminatedmessage. All messages that relate to that message andhave the same session ID include the client ID.The phone number of the op:msg recipientThis parameter can be repeated more than once with thestatus and txt parameters in the op:delivery.The delivery statusThe values indicate the following:0 = The delivery failed.1 = The delivery was delayed (the message is buffered inthe SMSC for a later delivery).2 = The message was delivered successfully.txt Status text A description of the status parameter value

ManualDatePage2013-02-01 33 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway1.6.8 Session Status (op:status)When you have sent the op:msg, the op:delivery operation controls the session status. Theapplication or Provider Server sends an op:status reply indicating the session status. ProviderServer sends this message when there is an error in the message delivery. The delivery withsession-id is cancelled.Parameter Value Definitionsession-id Any string The current transaction’s IDless than 20charactersclient-id Any stringless than 20charactersThe client application’s IDThe application can set a client ID to a mobile terminatedmessage. All messages that relate to that message andSession-controlready, cont,abort, errorhave the same session ID include the client ID.Session status controlUse this parameter only in a reply to a mobile originatedmessage. This parameter controls the session status. Youcan define the following values for the parameter:Ready (default) = Kills the session and gives the transactiona Success status.Cont = Does not kill the session; further send and receivewith same session ID is possible.Abort = Kills the session and gives the transaction anInterrupt status.Error = Kills the session and gives the transaction an errorstatus. Only Provider Server sends this status.If you do not define the session-control parameter, thedefault value for session control is ready.Txt Status text A description of the status, a possible error in the textformat.1.6.9 Transaction SequenceThis chapter describes how messages are transmitted between the application and ProviderServer when using the Open Text Protocol. Note that all messages in the examples use thesame connection.1.6.9.1 Connection HandshakeWhen you open the connection from the application to Provider Server (the Send Onlyservice), Provider Server sends the following reply to the application:hello:Provider Server Version 4.0 ready.After receiving this message, your application may send messages. The application must notreply to this message.

ManualDatePage2013-02-01 34 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayWhen Provider Server opens the connection to the application (the Query/reply, Receive Onlyservices), Provider Server sends the following message to the application:hello:Provider Server Version 4.0 ready.After receiving this message, your application will receive and may send messages. Theapplication must not reply to this message.After either side has opened the connection, it should be kept alive as long as possible.Closing the connection between messages slows the service and may cause errors. All thefollowing messages between the application and Provider Server use the same connection.This connection is used for sending a message to both directions.If your application can handle more than one service, Provider Server may open severalconnections to the application for different services. You application may also open severalsimultaneous connections to Provider Server for sending messages. When using severalconnections, be careful to send replies using the correct connection.1.6.9.2 Closing the ConnectionThe application can close the connection by sending the following message to Provider Server:quit:After receiving this message, Provider Server will close the connection.Provider Server closes the connection without a warning. It does not send any message beforeclosing the connection. For example, in C language applications you can check the returnvalue of recv() function. It will return zero when the socket connection is closed.Provider Server closes the connection after a connection timeout, i.e. when there have notbeen messages within the defined timeout period.1.6.9.3 A Mobile Terminated MessageThis is an example of services of the type Send Only.The application sends an op:msg message to Provider Server.Provider Server answers with an op:ok or an op:err message.When the message is delivered to the SMSC, Provider Server sends an op:delivery messageto the application.

ManualDatePage2013-02-01 35 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway1.6.9.4 A Mobile Originated Message without a ReplyThis is an example of a service of the type Receive Only.The mobile terminal user sends an SMS message and Provider Server forwards the messageto the application as op:msg.The application must send an op:ok or an op:err message to Provider Server. Note that op:errwill end the transaction with an error status.1.6.9.5 A Mobile Originated Message with a ReplyThis is an example of a service of the type Query Reply.The mobile terminal user sends an SMS message and Provider Server forwards the messageto the application as op:msg.The application sends an op:ok or an op:err message to Provider Server. Note that op:err willend the transaction with an error status.When the received message has been handled, the application sends a new op:msg messageas a reply to Provider Server. This message must have the same app-parameter and sessionidparameter as the original received message. If the application never answers with the sameapp and session-id, the service type must be changed to Receive Only and the applicationmust send a reply via the Send Only service.

ManualDatePage2013-02-01 36 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayProvider Server answers with an op:ok or an op:err message.When the message is delivered to the SMSC, Provider Server sends an op:delivery messageto the application.1.6.9.6 An Error Occurs after Sending a Mobile Terminated MessageWhen any error occurs after the application sends a mobile terminated message, ProviderServer will reply with an op:status message. The reason for op:status may be connectionproblems between Provider Server and Operator Server or problems with the SMSCconnection on the operator’s premises.The application sends an op:msg message to Provider Server.Provider Server answers with an op:ok or an op:err message. Note that Provider Server willnot send any delivery or status reply if it replies with op:err.When the error is recognized and reported to Provider Server, it sends an op:status messageto the application. The session-control parameter in the message in case of an error is “error”or "abort" for less severe conditions.

ManualDatePage2013-02-01 37 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway1.6.9.7 ExamplesNote that connection open and close messages (hello:, quit:) are not shown in the examples.EXAMPLE 1 MT MESSAGE WITH CLIENT-IDThe application sends the following message to the mobile terminal number 0101234567:op:msgapp:sendto:0101234567from:12345 msg:Hello mobile user!client-id:1234end:msgProvider Server replies immediately with the following message:op:oksession-id:PB1.1.230.1293client-id:1234count:1end:okWhen the message is delivered to the SMSC, Provider Server sends the following message tothe application:op:deliverysession-id:PB1.1.230.1293client-id:1234msid:0101234567status:2text:Delivered to the SMSCend:deliveryEXAMPLE 2 RINGING TONE1. The application sends a ringing tone message to the mobile terminal number 0101234567:op:msgapp:sendto:0101234567from:12345smart:5505type:bin msg:013A594D85B5C1B194080A1718DBE92C449121022CAB081000end:msg2. Provider Server replies immediately with the following message:op:oksession-id:PB1.1.230.1294count:1end:ok

ManualDatePage2013-02-01 38 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway3. When the message is delivered to the SMSC, Provider Server sends the following messageto the application:op:deliverysession-id:PB1.1.230.1294msid:0101234567status:2text:Delivered to the SMSCend:deliveryEXAMPLE 3 OPERATOR LOGO1. The application sends an operator logo message to the mobile terminal number0101234567:op:msgapp:sendto:0101234567from:12345smart:5506type:binmsg:42F419000A0A0180000002008020000000002000end:msg2. Provider Server replies immediately with the following message:op:oksession-id:PB1.1.230.1296count:1end:ok3. When the message is delivered to the SMSC, Provider Server sends the following messageto the application:op:deliverysession-id:PB1.1.230.1296msid:0101234567status:2text:Delivered to the SMSCend:deliveryEXAMPLE 4 CALLER GROUP ICON1. The application sends a caller group icon message to the mobile terminal number0101234567:op:msgapp:sendto:0101234567from:12345smart:5507

ManualDatePage2013-02-01 39 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gatewaytype:binmsg: 000A0A0180000002008020000000002000end:msg2. Provider Server replies immediately with the following message:op:oksession-id:PB1.1.230.1295count:1end:ok3. When the message is delivered to the SMSC, Provider Server sends the following messageto the application:op:deliverysession-id:PB1.1.230.1295msid:0101234567status:2text:Delivered to the SMSCend:deliveryEXAMPLE 5 A RECEIVE ONLY APPLICATION RECEIVES A MESSAGE FROM A PHONE1. Provider Server sends the received message to the applicationop:msgapp:examplesession-id:OA1.1003.20718.1197404from:0101234567to:12345type:ascmsg:Hello there!end:msg2. The application replies immediately with the following message:op:oksession-id:OA1.1003.20718.1197404end:okEXAMPLE 6 A “QUERY/REPLY” APPLICATION RECEIVES A MESSAGE AND REPLIES1. Provider Server sends the received message to the applicationop:msgapp:examplesession-id:OC1.1003.20718.1197404from:0101234567to:12345type:ascmsg:Hello there!end:msg

ManualDatePage2013-02-01 40 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway2. The application replies immediately with the following message:op:oksession-id:OC1.1003.20718.1197405end:ok3. The application replies to the message with a new MT message:op:msgapp:examplesession-id:OC1.1003.20718.1197405to:0101234567from:12345msg:Hello to you mobile user!end:msg4. Provider Server replies immediately with the following message:op:oksession-id:OC1.1003.20718.1197405count:1end:ok5. When the message is delivered to the SMSC, Provider Server sends the following messageto the application:op:deliverysession-id:OC1.1003.20718.1197405msid:0101234567status:2text:Delivered to the SMSCend:delivery1.6.10 Positioning Support with OTP ProtocolFirst configure your service with Provider Admin and ask the operator to add positioningsupport to your service. Your service ID number is needed.

ManualDatePage2013-02-01 41 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayFigure 8. Example for OTP Positioning Service

ManualDatePage2013-02-01 42 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway1. Provider Server sends the received message to the applicationop:msgapp:examplesession-id:OC1.0005.20718.1197404from:PABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABto:00000type:ascposition-latitude: 60.1234455position-longitude: 25.112213position-estimate: 300position-citycode: 91position-city: Helsinkiposition-postcode: 00510msg:whereamiend:msg2. The application replies immediately with the following message:op:oksession-id:OC1.0005.20718.1197405end:ok3. The application replies later to the message.op:msgapp:examplesession-id:OC1.0005.20718.1197405to:PABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABfrom:00000msg:You are in Helsinki!end:msg4. Provider Server replies immediately with the following message:op:oksession-id:OC1.0005.20718.1197405count:1end:ok5. When the message is delivered to the SMSC, Provider Server sends the following messageto the application:op:deliverysession-id:OC1.0005.20718.1197405msid:PABABABABABABABABABABABABABABABABABABABABABABABABABABABAB

ManualDatePage2013-02-01 43 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayABABstatus:2text:Delivered to the SMSCend:delivery1.6.11 Protocol errorsIf OTP message handling fails in the Content Gateway, no matter what is the reason, a properOTP response message is returned back to the service application. The OTP error messagecontains text of one of the Content Gateway error messages. Error messages are listed at theend of this document.2 ERROR MESSAGESSending SMS message is restricted by the license.Message can't be sent because sending SMS messages for this provider is restricted by thelicense.Sending MMS message is restricted by the license.Message can't be sent because sending MMS messages for this provider is restricted by thelicense.Missing sender address in HTTP request line.Content Gateway can't extract sender address from the HTTP request line. Parameter 'from' iseither missing or not correctly set.Missing recipient address in the HTTP request line.Content Gateway can't extract the recipient address from the HTTP request line. Parameter 'to'is either missing or not correctly set.Missing message content in the HTTP request line.Content Gateway can't extract message content from the HTTP request line. Parameter 'msg'is either missing or not correctly set.Invalid HTTP request line.Content Gateway can't extract necessary information from the HTTP request line. Line syntaxis not correct.Missing Content-Type header in HTTP request.HTTP Content-Type header is not included in the HTTP POST request.Parsing binary MMS message failed.MMS binary content is invalid. Content Gateway can't extract necessary information from themessage content.Missing recipient address in the MMS message.Content Gateway can't extract recipient address from the MMS message.Missing sender address in the MMS message.Content Gateway can't extract sender address from MMS message.Unsupported Content-Type header for the HTTP POST request.Content Gateway can't handle the HTTP POST request with given Content-Type header.Please, check the Content Gateway documentation for supported Content-Type headers.

ManualDatePage2013-02-01 44 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayMissing sender address in the message.Content Gateway can't extract sender address from the message.Missing recipient address in the message.Content Gateway can't extract recipient address from the message.Missing provider ID in the message.Content Gateway can't extract provider ID from message.Missing session ID in the message.Content Gateway can't extract session ID from message.Unsupported HTTP method [xxx].Content Gateway can't handle HTTP method xxx. Please, check the Content Gatewaydocumentation for the supported HTTP methods.Invalid message content.Content Gateway can't handle message because the message content is invalid. Please,check log files for more detailed reason.Service xxx is disabled.The identified service can't be used because it is not enabled. In order to use the service, youneed to change service configuration.Service xxx not found.The service xxx can't be found in the system. Please, check service configuration.Service usage is restricted by whitelist. (i.e. Access denied.)The user can't use the service because it is restricted by the whitelist. In case of SMSmessage with multiple recipients, the message is rejected if all recipients are restricted to usethe service. In case of MMS message with multiple recipients, the message is rejected if any ofthe recipients is restricted to use the service.Service usage is restricted by the restriction class. (i.e. User barred)The user can't use the service, because user and service restriction classes restrict it. In caseof SMS message with multiple recipients, the message is rejected if all recipients are restrictedto use the service. In case of MMS message with multiple recipients, the message is rejected ifany of the recipients is restricted to use the service.PUSH messages with multiple recipients are not yet supported. (i.e. Too manyrecipients)The Push message must have a single recipient. Support for PUSH messages with multiplerecipients will be added later.No active subscription for the service. (i.e. Not a subscriber)The user did not subscribe for the push service, or subscription has not been activated yet.User ‘xxx’ reached daily limit [n] for service [yyy]. (i.e. Passive user. Daily limit reached.)Positioning recipient map failed.Decoding of encoded phone number failed.

ManualDatePage2013-02-01 45 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayCan't transform HTTP SMS message to SMPP protocol.Content Gateway can't transform the incoming HTTP SMS message to be sent to SMPP SC.Please, check log file for more details.Can't transform HTTP SMS message to EMI protocol.Content Gateway can't transform incoming HTTP SMS message to be sent to EMI SC. Please,check log file for more details.Can't transform HTTP SMS message to xxx protocol.Content Gateway can't transform the incoming HTTP SMS message to be sent to SC. This ismost likely because of wrong configured SC protocol (xxx). Please, check service configurationand log file for more details.Unknown HTTP message type.Content Gateway can't recognize the HTTP message. Please, check log files for more details.Can't transform SMS message to SMPP protocol.Content Gateway can't transform the incoming SMS message to be sent to SMPP SC. Please,check log file for more details.Can't transform SMS message to EMI protocol.Content Gateway can't transform the incoming SMS message to be sent to EMI SC. Please,check log file for more details.Can't transform SMS message to xxx protocol.Content Gateway can't transform the incoming SMS message to be sent to SC. This is mostlikely because of wrong configured SC protocol (xxx). Please, check service configuration andlog file for more details.Unknown message type.Content Gateway can't recognize the message type. Please, check log files for more details.Can't transform message.Content Gateway can't transform message from one to another format. Please, check serviceconfiguration and log file for more details.Service is configured not to send any MT message.Content Gateway can't send message, because service is configured not to send any MT SMSmessages. Please, check the 'Max SMS messages' parameter in the service configuration.Can't send message to SMPP NE.Content Gateway can't send the message to SMPP Network Element. Please, check SMPPNetwork Element configuration (in Operator Server config file) and SMPP Network Elementconnection. Please, check log file for more details.Can't send message to EMI NE.Content Gateway can't send the message to EMI Network Element. Please, check EMINetwork Element configuration (in Operator Server config file) and EMI Network Elementconnection. Please, check log file for more details.Can't send message to HTTP NE.Content Gateway can't send the message to HTTP Network Element. Please, check HTTP

ManualDatePage2013-02-01 46 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content Gateway3 APPENDIXNetwork Element configuration (in Operator Server config file) and HTTP Network Elementconnection. Please, check log file for more details.Can't send message to NE.Content Gateway can't send the message to Network Element. Most likely reason for this iswrong configuration of Network Elements in Operator Server. Please, check Operator Serverconfig file and log file for more details.Can't send message to SC.Content Gateway can't send the message to Service Center. Please, check Service Centerconfiguration (in Network Element config file) and Service Center connection. Please, checklog file for more details.NE shutdown in progress.Content Gateway can't send the message to Service Center because Network Element'sshutdown is in progress. Please, check Network Element connection.No SC connection.Content Gateway can't send the message to Service Center because there is no suitableService Center connection. Please, check Service Center configuration (in Network Elementconfig file) and Service Center connection.Illegal message, message send failed to SC.Content Gateway can't send the message to Service Center because message content isinvalid. Please, check log files for more details.Message send failed to SC.Content Gateway can't send the message to Service Center. Please, check log files for moredetails.3.1 Software and Documents3.2 Contact Information4 GLOSSARYYou can download the Content Gateway software and documents from your operator’s website.If you cannot find answers to your questions in these documents, please contact youroperator’s help desk. When you contact the operator’s help desk, first check which version ofContent Gateway you are using.API (Application Programmer’s Interface)Program library that allows the application programmer to develop a Content Gatewayapplication.HTTP (Hypertext Transfer Protocol)A protocol for exchanging files (text, graphic images, sound, video and othermultimedia files) on the World Wide Web. HTTP is an application protocol.

ManualDatePage2013-02-01 47 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayOperator ServerA platform located on the operator’s premises. Operator Server routes incomingmessages to Provider Server, and the outgoing messages to the SMSC/MMSC.OTP (Open Text Protocol)A text-based socket protocol specific to Content Gateway and resembling the SMTPprotocol. With this protocol, you can create all types of applications that ContentGateway supports. The main goal for the protocol is to provide an open interface fordevelopers that use programming languages other than C++ or Java.Provider ServerShort NumberA program located in the company’s or content/service provider’s network. ProviderServer routes incoming messages to the applications, and outgoing messages toOperator Server.A short phone number specific to a company or a content/ service provider. The usersof the services send SMS messages to the Short Number.SMPP (Short Message Peer to Peer)A protocol used as an interface to an SMSC. Communication on the application levelis based on transaction, which consists of an operation and the result of the operation.SMSC (Short Message Service Center)A hardware device integrated in the GSM network or located outside the network. TheSMSC receives SMS messages from senders and routes them to the recipients.MMSC (Multimedia Message Service Center)SMS messageMMS messageA hardware device integrated in the GSM network or located outside the network. TheMMSC receives MMS messages from senders and routes them to the recipients.A message sent from a GSM mobile terminal using the Short Message Service.A message sent from a GSM mobile terminal using the Multimedia Message Service.UCP/EMI (Universal Computer Protocol/External Machine Interface)A protocol used as an interface to an SMSC. EMI is an extension of UCP.Communication on the application level is based on transactions, which consist of anoperation and the result of the operation.WAP (Wireless Application Protocol)A specification for a set of communication protocols to standardize the way thatwireless devices, such as mobile terminals, can be used for Internet access, includingemail.

ManualDatePage2013-02-01 48 (48)Coverage Identifier VersionService Provider’s Software Developer TS1209282657 1.0 ApprovedApproved on Valid from Expiry Relation2013-01-29 2013-02-01 Content GatewayXML (eXtensible Markup Language)A markup language that is used for transferring push messages in Content Gateway.Both binary and text messages are accepted.