NOKIA M2M GATEWAY 2.2 SERVICE PROVIDER EDITION BILLING SUPPORT PROGRAMMING GUIDE. Copyright Nokia. All rights reserved. Issue 2.

Transcription

1 NOKIA M2M GATEWAY 2.2 SERVICE PROVIDER EDITION BILLING SUPPORT PROGRAMMING GUIDE Copyright Nokia. All rights reserved. Issue

2 Contents ACRONYMS AND TERMS ABOUT THIS DOCUMENT INTRODUCTION BILLING EVENTS FROM THE GATEWAY SESSION START SESSION END MESSAGE TRANSMIT WAKE-UP SHORT MESSAGE FIELDS OF BILLING EVENTS COMMON FIELDS Transmit bearer info Billing session info Billing info Data unit Direction Session end reason Fail reason SESSION START EVENT SESSION END EVENT MESSAGE TRANSMIT EVENT WAKE-UP EVENT SHORT MESSAGE EVENT BILLING ADAPTER MEDIATOR INTERFACE settransportdriver() method close() method Event processing methods TRANSPORT DRIVER INTERFACE starttransport() method...16

3 5.2.2 closetransport() method sendmessage(byte[] message) method Example Transport Driver USING THE BILLING ADAPTER APPLICATION...18 APPENDIX...19

4 Legal Notice Copyright Nokia. All rights reserved. Reproduction, transfer, distribution or storage of part or all of the contents in this document in any form without the prior written permission of Nokia is prohibited. Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other product and company names mentioned herein may be trademarks or trade names of their respective owners. Nokia operates a policy of continuous development. Nokia reserves the right to make changes and improvements to any of the products described in this document without prior notice. Under no circumstances shall Nokia be responsible for any loss of data or income or any special, incidental, consequential or indirect damages howsoever caused. The contents of this document are provided "as is". Except as required by applicable law, no warranties of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose, are made in relation to the accuracy, reliability or contents of this document. Nokia reserves the right to revise this document or withdraw it at any time without prior notice.

5 ACRONYMS AND TERMS Acronym/term CORBA CP CSD DCD Downlink GGSN GIOP GPRS HTTP IDL IP JAXP LCP M2M MSISDN NAS ORB RADIUS SMS SMSC USSD USSDC Uplink XML Description Common Object Request Broker Architecture Connection Provider Circuit Switched Data Data Carrier Detect Connection away from the Nokia M2M Gateway Gateway GPRS Support Node General Inter-ORB Protocol General Packet Radio Service Hypertext Transfer Protocol Interface Definition Language Internet Protocol Java API for XML Processing Link Control Protocol Machine-to-Machine Mobile Subscriber ISDN Number Network Access Server Object Request Broker Remote Authentication Dial-in User Server Short Message Service Short Message Service Centre Unstructured Supplementary Service Data Unstructured Supplementary Service Data Centre Connection towards the Nokia M2M Gateway extensible Markup Language 1/20

6 1. ABOUT THIS DOCUMENT This document specifies the Mediator and TransportDriver interfaces for implementing the generation and transfer of billing records from the Nokia M2M Gateway Service Provider Edition 1 to external billing systems. 1 Note that the billing support feature is included only in the Nokia M2M Gateway Service Provider Edition and not in other editions. 2/20

7 2. INTRODUCTION The Mediator and TransportDriver interfaces are part of the so-called Billing Adapter framework delivered by Nokia. It can be used as a basis for connecting the Gateway to external billing systems. Customers build their implementations on top of this framework. The Billing Adapter gathers atomic billing events from the Gateway and composes these events into billing records suitable for the used billing system. The Gateway uses Common Object Request Broker Architecture (CORBA) Event Service for sending events to the Billing Adapter. The CORBA Event Service is not delivered by Nokia, but must be acquired separately. M2M application Nokia M2M Gateway Service Provider Edition Gateway billing events CORBA Event Service Event channel M2M Billing Adapter Customer billing records Customer billing system push pull GSM network SMSC/USSDC GGSN NAS Nokia GSM Connectivity Terminals Figure 1. Billing architecture 3/20

8 3. BILLING EVENTS FROM THE GATEWAY Billing from the Gateway is based on transmitted messages and communication sessions. Five different billing events are specified in Table 1. Table 1. Billing events Event type SessionStartEvent SessionEndEvent MessageTransmitEvent WakeUpEvent ShortMessageEvent Description Session establishment. Session close. GIOP message (M2M communication) routed via the Gateway. Wake-up message sent by the Gateway to a terminal that is asking it to initiate a data call or open a GPRS context. Non-GIOP message, such as plain text SMS message or Smart Message, routed via the Gateway. The CORBA Interface Definition Language (IDL) specifications for these events are described in the Appendix. The billing events are explained in the following chapters. 3.1 SESSION START A SessionStartEvent is generated when the connection is initiated either by the Gateway (downlink) or a terminal (uplink). With Short Message Service (SMS) and Unstructured Supplementary Service Data (USSD) bearers, the session starts when the Gateway handles the first message coming from or going to a terminal that belongs to a known domain. With General Packet Radio Service (GPRS) and Circuit Switched Data (CSD) bearers, the session starts when the Remote Authentication Dial-in User Server (RADIUS) notifies the Billing Manager of an opened connection. 3.2 SESSION END With SMS and USSD bearers, a SessionEndEvent is generated when no messages are transmitted within a given idle period. With GPRS and CSD bearers, a SessionEndEvent is generated when the RADIUS server notifies the Billing Manager of a dropped connection. 4/20

9 3.3 MESSAGE TRANSMIT A MessageTransmitEvent is generated when the Gateway has transferred a General Inter-ORB Protocol (GIOP) message to its destination. The message includes the count of used data units, and information on the session and on possible errors. 3.4 WAKE-UP A WakeUpEvent is generated when the Gateway sends an SMS to a terminal asking it to initiate a data call or to open a GPRS context. 3.5 SHORT MESSAGE A ShortMessageEvent is generated the Gateway transmits a message that is not GIOP-related, such as a text message or a smart message. 5/20

10 4. FIELDS OF BILLING EVENTS This chapter describes all the events of the CORBA IDL specification (see the ). All the used time values are presented as integers. These values show the time in milliseconds from the standard base time known as the epoch (January 1st, 1970, 00:00:00 GMT). 4.1 COMMON FIELDS Some structures and constants are common to all events as described in Table 2. Table 2. Common structures and constants Structure/constant TransmitBearerInfo BillingSessionInfo BillingInfo DataUnit Direction SessionEndReason FailReason Description Information on the session used in MessageTransmitEvents. Information on the session used in SessionStartEvents and SessionEnd Events. Information on the used communication resources. Specifies the different communication resources. Direction of connection. Reason for closing the current session. Reason for transmit failure Transmit bearer info The fields of TransmitBearerInfo structure are presented in Table 3. Table 3. TransmitBearerInfo Name IDL type Description SessionID long long ID for the billing session. Domain String Name of the domain. ConnectionProviderName String Name of the Connection Provider (CP). BearerType String SMS, USSD, GPRS, CSD, or TUNNELING. Msisdn String Mobile Subscriber International ISDN N b (MSISDN) ( t d 6/20

11 Name IDL type Description ISDN Number (MSISDN) (not used with incoming CSD) Billing session info The fields of the BillingSessionInfo are presented in Table 4. Table 4. BillingSessionInfo Name IDL type Description SessionID long long ID for the billing session. Domain String Name of the domain. BearerType String SMS, USSD, GPRS, or CSD. TerminalID String ID for a terminal. NASAddress String Network address for the Gateway GPRS Support Node (GGSN), Network Access Server (NAS), Short Message service Centre (SMSC), or Unstructured Supplementary Service Data Centre (USSDC). Port Short Port for SMSC or USSDC. chargingid 2 String Charging identifier (GGSN). IPAddress String Internet Protocol (IP) address for M2M devices (used with CSD and GPRS bearers). Msisdn String MSISDN (used with incoming SMS, USSD, and GPRS). Imsi 3 String Used with GPRS Billing info BillingInfo is a sequence of BillingData structures. The fields of the BillingData structure are presented in Table 5. 2 Attribute number 221 (reserved from the implementation specific range) contains the charging ID of a mobile station. The charging ID format is in binary coded decimal and contains four bytes. 3 Attribute number 224 (reserved from the implementation specific range) contains the International Mobile Subscriber Identity (IMSI) of a mobile station. The IMSI format is in binary coded decimal with extra four bits set to 1 for an odd number of digits, for example, 123 equals to hexadecimal bytes 21 F3. 7/20

12 Table 5. BillingInfo Name Value Explanation unit DataUnit Type of the used communication resource. count long Number of used resources Data unit DataUnit specifies different kinds of communication resources. The fields of the DataUnit are presented in Table 6. Table 6. DataUnit Constant Value Description GIOP_DATA_UP 0 GIOP data unit sent towards the Gateway. GIOP_DATA_DOWN 1 GIOP data unit sent by the Gateway. SMS_MESSAGE_UP 2 SMS sent towards the Gateway. SMS_MESSAGE_DOWN 3 SMS sent by the Gateway. USSD_MESSAGE_UP 4 USSD sent towards the Gateway. USSD_MESSAGE_DOWN 5 USSD sent by the Gateway. WAKE_UP_MESSAGE 6 Wake-up message sent by the Gateway Direction The fields of the Direction constant are presented in Table 7. Table 7. Direction Constant Value Description DOWNLINK true Connection from the Gateway. UPLINK false Connection towards the Gateway Session end reason The SessionEndReason constant describes the trigger for the SessionCloseEvent. The fields of the SessionEndReason are described in Table 8. 8/20

13 Table 8. Session end reason Constant Value Explanation UNKNOWN 0 The Gateway could not resolve the reason for session end. USER_REQUEST 1 User requested the termination of service, for example with Link Control Protocol (LCP) Terminate or by logging out. LOST_CARRIER 2 Data Carrier Detect (DCD) was dropped at the port. LOST_SERVICE 3 Service can no longer be provided; for example, connection between the user and the host was interrupted. IDLE_TIMEOUT 4 Idle timer expired. SESSION_TIMEOUT 5 Maximum session length timer expired. ADMIN_RESET 6 Administrator reset the port or session. ADMIN_REBOOT 7 Administrator is ending the service at NAS, for example prior to rebooting it. PORT_ERROR 8 NAS detected an error at the port that required ending the session. NAS_ERROR 9 NAS detected an error (other than at the port) that required ending the session. NAS_REQUEST 10 NAS ended the session for a nonerror reason not listed here. NAS_REBOOT 11 NAS ended the session in order to perform a non-administrative reboot. PORT_UNNEEDED 12 NAS ended the session because resource usage fell below the lowwater mark (for example, if a bandwidth-on-demand algorithm decided that the port was no longer needed). PORT_PREEMPTED 13 NAS ended the session to allocate the port to a higher priority use. PORT_SUSPENDED 14 NAS ended the session to suspend a virtual session. SERVICE_UNAVAILABLE 15 NAS was unable to provide the requested service. 9/20

14 Constant Value Explanation CALLBACK 16 NAS is terminating the current session in order to perform call-back for a new session. USER_ERROR 17 Termination of the session due to an error in user input. HOST_REQUEST 18 Login host terminated the session normally. M2M_GATEWAY_MAX_TIME 99 Session reached its maximum alive time. M2M_GATEWAY_IDLE_TIME 100 Session reached its idle time, for example, no SMS messages were sent within this session during the last 10 minutes. M2M_GATEWAY_SHUTDOWN 101 The Gateway is shutting down Fail reason The fail reason describes the reason for a failed transmit event. A successful transmission is presented with the value 0. For more information, please contact Nokia s technical support. 4.2 SESSION START EVENT The fields of the SessionStartEvent are described in Table 9. Table 9. SessionStartEvent Name IDL type Explanation gatewayid string ID of the Gateway. sessioninfo BillingSessionInfo Session identification. starttime long long Start time of the session. direction Direction Direction of connection (uplink/downlink). 10/20

15 4.3 SESSION END EVENT The fields of SessionEndEvent are described in Table 10. Table 10. Session end event Name Value Explanation gatewayid string ID of the Gateway. sessioninfo BillingSessionInfo Session identification. starttime long long Start time of the session. endtime long long End time of the session. direction Direction Direction of connection (uplink/downlink). billinginfo BillingInfo Information on the used communication resources. reason SessionEndReason Reason for closing the session. 4.4 MESSAGE TRANSMIT EVENT The fields of the MessageTransmitEvent are described in Table 11. Table 11. Message transmit event Name Value Explanation gatewayid string ID of the Gateway. upsessioninfo TransmitBearerInfo TransmitBearerInfo for uplink direction. downsessioninfo TransmitBearerInfo TransmitBearerInfo for downlink direction. uptime long long Time a message was received by the Gateway. downtime long long Time a message was sent by the Gateway. billinginfo BillingInfo Information on the used communication resources. reason FailReason Reason for transmit failure. 4.5 WAKE-UP EVENT The fields of the WakeUpEvent are described in Table /20

16 Table 12. WakeUpEvent Name Value Explanation gatewayid string ID of the Gateway. sessioninfo BillingSessionInfo Session identification. connectionprovidername string Name of the CP. bearertype string SMS, USSD, GPRS, or CSD. address string Destination address of the WakeUpEvent. 4.6 SHORT MESSAGE EVENT The fields of the ShortMessageEvent are described in Table 13. Table 13. ShortMessageEvent Name Value Explanation messagetype string SmartMessage or TextMessage. gatewayid string ID of the Gateway. domain string Name of the domain. connectionproviderinstance Name string Name of the CP instance bearertype string SMS or USSD. msisdn string Destination address (MSISDN) of the WakeUpEvent. time long long Time of the event. direction Direction Direction of the message. databytes long Number of transferred bytes. 12/20

17 5. BILLING ADAPTER All Billing Adapter classes and interfaces belong to a Java language package named com.nokia.m2m.billingadapter, delivered by Nokia. The event classes generated from the IDL specifications are in a package named com.nokia.m2m.billingadapter.billingevents. The IDL file is also included in the Billing Adapter so that customers can generate their own classes from the IDL specifications for the Object Request Broker (ORB) they are using. The Billing Adapter framework consists of three components: control classes, Mediator interface, and TransportDriver interface. Billing Adapter Event Service Custom mediator implementation Custom transport implementation Event channel pull Control classes Mediator Transport Figure 2. Components of the Billing Adapter Control classes are already implemented and they: Start up the Billing Adapter Dynamically load Mediator and TransportDriver implementations Start listening to the event channel where the Gateway pushes the billing events Pass events to the Mediator implementation For complete reference, see the Javadoc documentation of the classes in the com.nokia.m2m.billingadapter package. 13/20

18 5.1 MEDIATOR INTERFACE The purpose of the Mediator component is to construct messages for the used billing system. The Mediator interface has five methods that must be implemented. Mediator interface methods include com.nokia.m2m.billingadapter.billingevents.*; public interface Mediator { void processmessagetransmit(messagetransmitevent); void processsessionend(sessionendevent event); void processsessionstart(sessionstartevent event); void processwakeup(wakeupevent event); void processshortmessage(shortmessageevent event) void settransportdriver(transportdriver driver); } void close(); settransportdriver() method This method is called by the startadapter() method of the BillingAdapter class. StartAdapter() dynamically loads both the Mediator and the Transport driver implementations, and uses the settransportdriver() method to set the driver for the Mediator close() method The Billing Adapter calls this method when it is shutting down. This method should include the necessary actions for a controlled shutdown of the Mediator implementation. 14/20

19 5.1.3 Event processing methods All five billing events have an event processing method of their own, which is called by the Billing Adapter framework. The event is given as a parameter. These methods should process the billing events and the generated billing records to a suitable format for the used billing system using the TransportDriver implementation transport. In the following example, an extensible Mark-up Language (XML) message is constructed from a billing event. After the XML message is generated, it is converted to a byte array so that the TransportDriver method writemessage(byte[] record) can be used. An example of Mediator implementation import javax.xml.transform.dom.*; import javax.xml.transform.*; import javax.xml.transform.stream.*; import org.w3c.dom.*; import java.io.*; public void processsessionstart(com.nokia.m2m.billingadapter.billingevents.sessionstart Event event) { try { // create new XML Document // containing information from the billing event // create String presentation from the XML Document // String to bytes // init transport driver.starttransport(); // write message driver.writemessage(bytes); } } catch (Exception exception) { // handle exception } 5.2 TRANSPORT DRIVER INTERFACE The TransportDriver implementation transports the generated billing records to the billing system of the customer. 15/20

20 The TransportDriver has three different methods that must be implemented. TransportDriver interface methods package com.nokia.m2m.billingadapter; public interface TransportDriver { void starttransport(); void closetransport(); } void sendmessage(byte[] message); starttransport() method This method initialises the connection to the used billing system closetransport() method This method closes the connection sendmessage(byte[] message) method This method writes the generated billing record to the connection initialised by the starttransport() method Example Transport Driver In this example, billing records are transported to a billing system over Hypertext Transfer Protocol (HTTP). An example servlet reads the transported record from ServletInputStream. An example of TransportDriver implementation package com.nokia.m2m.billingadapter; import java.io.*; import java.net.*; public class ExampleTransportDriver implements TransportDriver { private HttpURLConnection connection = null; public ExampleTransportDriver() { super(); } public void starttransport() { try { // Create new URL and connect to it } catch (Exception e) { 16/20

21 } // handle exception public void stoptransport() {} // close URL connection public void writemessage(byte[] message) { try { // create OutPutStream // write message to OutPutStream // close stream // get responsecode } } catch (Exception e) { // handle exception } 17/20

22 6. USING THE BILLING ADAPTER APPLICATION The Billing Adapter can be started with a start-up script that depends on the operating system. In Windows environment, this may be, for example, billing_adapter_visibroker.bat, and in Unix environments, for example, billing_adapter_visibroker.sh. These files are located in the bin directory of the Gateway. The start-up scripts call the main() method of the BillingAdapter class. The shutdown script, for example shutdown_billing_adapter_visibroker.bat or shutdown_billing_adapter_visibroker.sh depending on the used operating system, stops the Billing Adapter. These files are located in the bin directory of the Gateway. Set the properties by placing the billingadapter.properties file, located in the lib directory of the Gateway, to the classpath of the system. The needed properties are: Reference of the used event channel The used Mediator and TransportDriver implementation classes Parser class settings that used to initialise the parser factory (parsing of the atomic billing events follows the factory design pattern) An example of a billingadapter.properties file #event channel initial reference ORBInitRef.M2MBillingEventChannel=corbaname:rir:#BillingEventChannel #Transportdriver implentation wipunen.billingadapter.transportdriver= com.nokia.m2m.billingadapter.exampletransportdriver #mediator implentation wipunen.billingadapter.mediator= com.nokia.m2m.billingadapter.examplemediator # available parser class for billing events wipunen.billingadapter.eventfactory.sessionstart=com.nokia.m2m.billingadapt er.sessionstartparser wipunen.billingadapter.eventfactory.sessionend=com.nokia.m2m.billingadapter.sessionendparser wipunen.billingadapter.eventfactory.messagetransmit=com.nokia.m2m.billingad apter.messagetransmitparser wipunen.billingadapter.eventfactory.wakeup=com.nokia.m2m.billingadapter.wak eupparser wipunen.billingadapter.eventfactory.shortmessage.class=com.nokia.m2m.billin gadapter.shortmessageparser Note: The example application writes data in XML format, and this is why Java API for XML Processing (JAXP) is required. 18/20

23 APPENDIX CORBA IDL specifications for billing events #pragma prefix "com.nokia.m2m" module billingevents { typedef boolean Direction; const Direction UPLINK = TRUE; const Direction DOWNLINK = FALSE; struct TransmitBearerInfo { long long sessionid; string domain; string connectionprovidername; string bearertype; string msisdn; }; struct BillingSessionInfo { long long sessionid; string domain; string bearertype; string terminalid; string networkaddress; short port; string chargingid; string address; string msisdn; string imsi; }; typedef octet DataUnit; const DataUnit GIOP_DATA_UP = 0; const DataUnit GIOP_DATA_DOWN = 1; const DataUnit SMS_MESSAGE_UP = 2; const DataUnit SMS_MESSAGE_DOWN = 3; const DataUnit USSD_MESSAGE_UP = 4; const DataUnit USSD_MESSAGE_DOWN = 5; const DataUnit WAKE_UP_MESSAGE = 6; struct BillingData { DataUnit unit; long count; }; typedef sequence <BillingData> BillingInfo; typedef octet SessionEndReason; typedef long FailReason; struct SessionStartEvent { string gatewayid; BillingSessionInfo sessioninfo; long long starttime; Direction direction; }; struct SessionEndEvent { 19/20

24 }; string gatewayid; BillingSessionInfo sessioninfo; long long starttime; long long endtime; Direction direction; BillingInfo billinginfo; SessionEndReason reason; struct MessageTransmitEvent { string gatewayid; TransmitBearerInfo upsessioninfo; TransmitBearerInfo downsessioninfo; long long uptime; long long downtime; BillingInfo billinginfo; FailReason reason; }; struct WakeUpEvent { string gatewayid; BillingSessionInfo session; string connectionprovidername; string bearertype; string address; }; struct ShortMessageEvent { string messagetype; string gatewayid; string domain; string connectionproviderinstancename; string bearertype; string msisdn; long long time; Direction direction; long databytes; }; }; 20/20