Source: http://www.docstoc.com/docs/1527300/EDUCATIONAL
Timestamp: 2014-07-10 10:13:40
Document Index: 498245138

Matched Legal Cases: ['art 12', 'art 12', 'art 1', 'art 2', 'art 3', 'art 4', 'art 5', 'art 6', 'art 7', 'art 8', 'art 9', 'art 10', 'art 11', 'art 12', 'art 13', 'art 14', 'art 15', 'art 12', 'art 1', 'art 2']

ETSI ES 203 915-12 V1.1.1 (2005-04)
Open Service Access (OSA); Application Programming Interface (API); Part 12: Charging SCF (Parlay 5)
DES/TISPAN-01005-12-OSA
API, IDL, OSA, UML
Siret N&#176; 348 623 562 00017 - NAF 742 C Association &#224; but non lucratif enregistr&#233;e &#224; la Sous-Pr&#233;fecture de Grasse (06) N&#176; 7803/88
No part may be reproduced except as authorized by written permission. The copyright and the foregoing restriction extend to reproduction in all media. &#169; European Telecommunications Standards Institute 2005. &#169; The Parlay Group 2005. All rights reserved. DECT , PLUGTESTS and UMTS are Trade Marks of ETSI registered for the benefit of its Members. TM TIPHON and the TIPHON logo are Trade Marks currently being registered by ETSI for the benefit of its Members. TM 3GPP is a Trade Mark of ETSI registered for the benefit of its Members and of the 3GPP Organizational Partners.
Intellectual Property Rights ................................................................................................................................7 Foreword.............................................................................................................................................................7 1 2 3
Scope ........................................................................................................................................................8 References ................................................................................................................................................8 Definitions and abbreviations...................................................................................................................8
Definitions..........................................................................................................................................................8 Abbreviations .....................................................................................................................................................8
Charging SCF...........................................................................................................................................9
General requirements on support of methods.....................................................................................................9
Sequence Diagrams ..................................................................................................................................9
Reservation / payment in parts ...........................................................................................................................9 Immediate Charge ............................................................................................................................................11
7.1 7.1.1 7.1.2 7.1.3 7.1.4 7.2 7.2.1 7.3 7.3.1 7.4 7.4.1 7.4.1.1 7.4.1.2
Class Diagrams.......................................................................................................................................13 The Service Interface Specifications ......................................................................................................14
Interface Specification Format .........................................................................................................................14 Interface Class ............................................................................................................................................14 Method descriptions....................................................................................................................................15 Parameter descriptions ................................................................................................................................15 State Model.................................................................................................................................................15 Base Interface ...................................................................................................................................................15 Interface Class IpInterface ..........................................................................................................................15 Service Interfaces .............................................................................................................................................15 Overview ....................................................................................................................................................15 Generic Service Interface .................................................................................................................................15 Interface Class IpService ............................................................................................................................15 Method setCallback() ............................................................................................................................16 Method setCallbackWithSessionID()....................................................................................................16
8.1 8.1.1 8.1.2 8.2 8.2.1 8.2.2 8.3 8.3.1 8.3.2 8.3.3 8.3.4 8.3.5 8.3.6 8.3.7 8.3.8 8.3.9 8.3.10 8.3.11 8.3.12 8.3.13 8.3.14 8.3.15 8.3.16
Charging Interface Classes.....................................................................................................................17
Interface Class IpChargingManager .................................................................................................................17 Method createChargingSession()................................................................................................................18 Method createSplitChargingSession() ........................................................................................................19 Interface Class IpAppChargingManager ..........................................................................................................19 Method sessionAborted()............................................................................................................................20 Method &lt;&lt;new&gt;&gt; abortMultipleChargingSessions() .................................................................................20 Interface Class IpChargingSession...................................................................................................................20 Method creditAmountReq()........................................................................................................................21 Method creditUnitReq()..............................................................................................................................22 Method debitAmountReq().........................................................................................................................23 Method debitUnitReq()...............................................................................................................................23 Method directCreditAmountReq()..............................................................................................................24 Method directCreditUnitReq()....................................................................................................................25 Method directDebitAmountReq()...............................................................................................................25 Method directDebitUnitReq().....................................................................................................................26 Method extendLifeTimeReq() ....................................................................................................................26 Method getAmountLeft()............................................................................................................................26 Method getLifeTimeLeft()..........................................................................................................................27 Method getUnitLeft()..................................................................................................................................27 Method rateReq()........................................................................................................................................27 Method release() .........................................................................................................................................28 Method reserveAmountReq() .....................................................................................................................28 Method reserveUnitReq() ...........................................................................................................................29
8.4 8.4.1 8.4.2 8.4.3 8.4.4 8.4.5 8.4.6 8.4.7 8.4.8 8.4.9 8.4.10 8.4.11 8.4.12 8.4.13 8.4.14 8.4.15 8.4.16 8.4.17 8.4.18 8.4.19 8.4.20 8.4.21 8.4.22 8.4.23 8.4.24 8.4.25
Interface Class IpAppChargingSession ............................................................................................................29 Method creditAmountErr() .........................................................................................................................31 Method creditAmountRes() ........................................................................................................................31 Method creditUnitErr() ...............................................................................................................................32 Method creditUnitRes() ..............................................................................................................................32 Method debitAmountErr() ..........................................................................................................................32 Method debitAmountRes() .........................................................................................................................33 Method debitUnitErr() ................................................................................................................................33 Method debitUnitRes() ...............................................................................................................................33 Method directCreditAmountErr() ...............................................................................................................34 Method directCreditAmountRes() ..............................................................................................................34 Method directCreditUnitErr() .....................................................................................................................34 Method directCreditUnitRes() ....................................................................................................................35 Method directDebitAmountErr() ................................................................................................................35 Method directDebitAmountRes() ...............................................................................................................36 Method directDebitUnitErr() ......................................................................................................................36 Method directDebitUnitRes() .....................................................................................................................36 Method extendLifeTimeErr()......................................................................................................................37 Method extendLifeTimeRes().....................................................................................................................37 Method rateErr() .........................................................................................................................................37 Method rateRes() ........................................................................................................................................37 Method reserveAmountErr().......................................................................................................................38 Method reserveAmountRes()......................................................................................................................38 Method reserveUnitErr().............................................................................................................................38 Method reserveUnitRes()............................................................................................................................39 Method sessionEnded()...............................................................................................................................39
9.1 9.1.1 9.1.2 9.1.3 9.1.4
State Transition Diagrams ......................................................................................................................40
State Transition Diagrams for IpChargingSession ...........................................................................................40 Session Created State..................................................................................................................................41 Amount Reserved State ..............................................................................................................................41 Volume Reserved State...............................................................................................................................41 Reservation Ended State .............................................................................................................................41
Content Based Charging Service Properties...........................................................................................41 Data Definitions .....................................................................................................................................42
Charging Data Definitions................................................................................................................................42 IpChargingManager ....................................................................................................................................43 IpChargingManagerRef ..............................................................................................................................43 IpAppChargingManager .............................................................................................................................43 IpAppChargingManagerRef .......................................................................................................................43 IpChargingSession ......................................................................................................................................43 IpChargingSessionRef ................................................................................................................................43 IpAppChargingSession ...............................................................................................................................43 IpAppChargingSessionRef .........................................................................................................................43 TpApplicationDescription ..........................................................................................................................43 TpAppInformationSet.................................................................................................................................43 TpAppInformation ......................................................................................................................................44 TpAppInformationType..............................................................................................................................44 TpSessionEndedCause................................................................................................................................44 TpMerchantAccountID ...............................................................................................................................44 TpCorrelationID .........................................................................................................................................44 TpCorrelationType......................................................................................................................................44 TpChargingPrice.........................................................................................................................................45 TpAmount...................................................................................................................................................45 TpChargingParameterSet............................................................................................................................45 TpChargingParameter .................................................................................................................................45 TpChargingParameterID.............................................................................................................................45 TpChargingParameterValue .......................................................................................................................46 TpChargingParameterValueType ...............................................................................................................46 TpVolumeSet..............................................................................................................................................46 TpVolume ...................................................................................................................................................46
11.1 11.1.1 11.1.2 11.1.3 11.1.4 11.1.5 11.1.6 11.1.7 11.1.8 11.1.9 11.1.10 11.1.11 11.1.12 11.1.13 11.1.14 11.1.15 11.1.16 11.1.17 11.1.18 11.1.19 11.1.20 11.1.21 11.1.22 11.1.23 11.1.24 11.1.25
11.1.26 11.1.27 11.1.28 11.1.29 11.1.30
TpUnitID ....................................................................................................................................................46 TpChargingSessionID.................................................................................................................................47 TpPriceVolumeSet......................................................................................................................................47 TpPriceVolume...........................................................................................................................................47 TpChargingError.........................................................................................................................................47
Exception Classes...................................................................................................................................47 OMG IDL Description of Charging SCF.....................................................49 W3C WSDL Description of Charging SCF .................................................50 Java™ API Description of the Charging SCF ............................................51 Contents of 3GPP OSA R6 Charging...........................................................52 Description of Charging for 3GPP2 cdma2000 networks ..........................53
Annex A (normative): Annex B (informative): Annex C (informative): Annex D (informative): Annex E (informative): E.1 E.2
E.2.1 E.2.2 E.2.3 E.2.4 E.2.5 E.2.6 E.2.7 E.2.8 E.2.9 E.2.10 E.2.11 E.2.12 E.2.13 E.2.14 E.2.15
General Exceptions.................................................................................................................................53 Specific Exceptions ................................................................................................................................53
Clause 1: Scope ................................................................................................................................................53 Clause 2: References ........................................................................................................................................53 Clause 3: Definitions and abbreviations ...........................................................................................................53 Clause 4: Charging SCF ...................................................................................................................................53 Clause 5: Sequence Diagrams ..........................................................................................................................53 Clause 6: Class Diagrams.................................................................................................................................53 Clause 7: The Service Interface Specifications ................................................................................................53 Clause 8: Charging Interface Classes ...............................................................................................................54 Clause 9: State Transition Diagrams ................................................................................................................54 Clause 10: Content Based Charging Service Properties...................................................................................54 Clause 11: Data Definitions..............................................................................................................................54 Clause 12: Exception Classes...........................................................................................................................54 Annex A (normative): OMG IDL Description of Charging SCF .....................................................................54 Annex B (informative): W3C WSDL Description of Charging SCF ...............................................................54 Annex C (informative): Java™ API Description of the Charging SCF ...........................................................54
Annex F (informative): F.1
F.1.1 F.1.2 F.1.3
Record of changes ..........................................................................................55
Interfaces ................................................................................................................................................55
New ..................................................................................................................................................................55 Deprecated........................................................................................................................................................55 Removed...........................................................................................................................................................55
F.2.1 F.2.2 F.2.3 F.2.4
Methods..................................................................................................................................................55
New ..................................................................................................................................................................55 Deprecated........................................................................................................................................................55 Modified ...........................................................................................................................................................56 Removed...........................................................................................................................................................56
F.3.1 F.3.2 F.3.3
Data Definitions .....................................................................................................................................56
New ..................................................................................................................................................................56 Modified ...........................................................................................................................................................56 Removed...........................................................................................................................................................56
F.4.1 F.4.2 F.4.3 F.4.4
Service Properties...................................................................................................................................56
New ..................................................................................................................................................................56 Deprecated........................................................................................................................................................57 Modified ...........................................................................................................................................................57 Removed...........................................................................................................................................................57
F.5.1 F.5.2 F.5.3
Exceptions ..............................................................................................................................................57
New ..................................................................................................................................................................57 Modified ...........................................................................................................................................................57 Removed...........................................................................................................................................................57
Others .....................................................................................................................................................57
History ..............................................................................................................................................................58
IPRs essential or potentially essential to the present document may have been declared to ETSI. The information pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found in ETSI SR 000 314: &quot;Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in respect of ETSI standards&quot;, which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web server (http://webapp.etsi.org/IPR/home.asp). Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web server) which are, or may be, or may become, essential to the present document.
This ETSI Standard (ES) has been produced by ETSI Technical Committee Telecommunications and Internet converged Services and Protocols for Advanced Networking (TISPAN). The present document is part 12 of a multi-part deliverable covering Open Service Access (OSA); Application Programming Interface (API), as identified below. The API specification (ES 203 915) is structured in the following parts: Part 1: Part 2: Part 3: Part 4: Part 5: Part 6: Part 7: Part 8: Part 9: Part 10: Part 11: &quot;Overview&quot;; &quot;Common Data Definitions&quot;; &quot;Framework&quot;; &quot;Call Control&quot;; &quot;User Interaction SCF&quot;; &quot;Mobility SCF&quot;; &quot;Terminal Capabilities SCF&quot;; &quot;Data Session Control SCF&quot;; &quot;Generic Messaging SCF&quot;; &quot;Connectivity Manager SCF&quot;; &quot;Account Management SCF&quot;;
Part 12: &quot;Charging SCF&quot;; Part 13: Part 14: Part 15: &quot;Policy Management SCF&quot;; &quot;Presence and Availability Management SCF&quot;; &quot;Multi-Media Messaging SCF&quot;.
The present document has been defined jointly between ETSI, The Parlay Group (http://www.parlay.org) and the 3GPP, in co-operation with a number of JAIN™ Community (http://www.java.sun.com/products/jain) member companies. The present document forms part of the Parlay 5.0 set of specifications. The present document is equivalent to 3GPP TS 29.198-12 V6.2.0 (Release 6).
The present document is part 12 of the Stage 3 specification for an Application Programming Interface (API) for Open Service Access (OSA). The OSA specifications define an architecture that enables application developers to make use of network functionality through an open standardised interface, i.e. the OSA APIs. The present document specifies the Charging Service Capability Feature (SCF) aspects of the interface. All aspects of the Charging SCF are defined here, these being: • • • • • • • • Sequence Diagrams. Class Diagrams. Interface specification plus detailed method descriptions. State Transition diagrams. Data Definitions. IDL Description of the interfaces. WSDL Description of the interfaces. Reference to the Java™ API description of the interfaces.
The process by which this task is accomplished is through the use of object modelling techniques described by the Unified Modelling Language (UML).
The references listed in clause 2 of ES 203 915-1 contain provisions which, through reference in this text, constitute provisions of the present document. ETSI ES 203 915-1: &quot;Open Service Access (OSA); Application Programming Interface (API); Part 1: Overview (Parlay 5)&quot;. ETSI ES 203 915-2: &quot;Open Service Access (OSA); Application Programming Interface (API); Part 2: Common Data Definitions (Parlay 5)&quot;.
For the purposes of the present document, the terms and definitions given in ES 203 915-1 apply.
For the purposes of the present document, the abbreviations defined in ES 203 915-1 apply.
Charging SCF
The following clauses describe each aspect of the Charging Service Capability Feature (SCF). The order is as follows: • • • • The Sequence diagrams give the reader a practical idea of how each of the SCF is implemented. The Class relationships clause shows how each of the interfaces applicable to the SCF, relate to one another. The Interface specification clause describes in detail each of the interfaces shown within the Class diagram part. The State Transition Diagrams (STD) show the transition between states in the SCF. The states and transitions are well-defined; either methods specified in the Interface specification or events occurring in the underlying networks cause state transitions. The Data Definitions clause shows a detailed expansion of each of the data types associated with the methods within the classes. Note that some data types are used in other methods and classes and are therefore defined within the Common Data types part ES 203 915-2.
General requirements on support of methods
An implementation of this API which supports or implements a method described in the present document, shall support or implement the functionality described for that method, for at least one valid set of values for the parameters of that method. Where a method is not supported by an implementation of a Service interface, the exception P_METHOD_NOT_SUPPORTED shall be returned to any call of that method. Where a method is not supported by an implementation of an Application interface, a call to that method shall be possible, and no exception shall be returned.
Reservation / payment in parts
The sequence diagram illustrates how to request a reservation and how to charge a user from the reserved amount, for instance to charge a user for a streamed video which lasts 10 minutes and costs a total of $2.00. The operations and interfaces that do not provide rating are employed throughout this sequence diagram. We assume the application has already discovered the Charging SCF. As a result, the application received an object reference pointing to an object that implements the IpChargingManager interface. The operations which handle units are used exactly the same, except that the amount of application usage is indicated instead of a price.
: IpAppChargingSession 1: new()
: IpChargingManager
: IpChargingSession
2: creat eChargingSes sion(
) 3: new()
4: reserveAmountReq(
5: reserveAmountRes( 6: forward event()
7: debitAmountReq( 9: forward event()
8: debitA mountRes(
10: getLifeTimeLeft( ) 11: extendLifeTimeReq( ) 12: ex tendLifeTimeRes ( ) 13: forward event()
14: debitAmountReq(
15: debitAmountRes( 16: forward event()
17: release( )
1: The application creates a local object implementing the IpAppChargingSession interface. This object will receive response messages from the IpChargingSession object. 2: The application opens a charging session, a reference to a new or existing object implementing IpChargingSession is returned together with a unique session ID. 3: In this case a new object is used. 4: The application requests the reservation of $ 2,00. 5: Assuming the criteria for requesting a reservation are met (the application provider has permission to charge the requested amount, the charged user has agreed to pay the requested amount), the amount is reserved in the session. At this point, the application provider knows that the network operator will accept later debit requests up to the reserved amount. So, the application may start serving the user, for instance by sending the video stream.
6: The successful reservation is reported back to the application. After half of the video has been sent to the user, the application may choose to capture half of the price already: 7: The application requests to debit $ 1,00 from the reservation. 8: The successful debit is reported back to the application. 9: The acknowledge is forwarded to the application. 10: The application checks if the remaining lifetime of the reservation will cover the remaining 5 minutes of video. Let us assume, it does not. 11: The application asks the IpChargingSession object to extend the lifetime of the reservation. 12: Assuming that the application provider is allowed to keep reservations open for longer than 10 minutes, the extendLifeTimeReq() will be honoured and confirmed properly. 13: The confirmation is forwarded to the application. 14: When the complete video has been transmitted to the user without errors, the application charges another $ 1,00. 15: The IpChargingSession object acknowledges the successful debit at the IpAppChargingSession callback object. 16: The IpAppChargingSession object forwards the acknowledge to the application. 17: Since the service is complete, the application frees all resources associated with the reservation and session.
Immediate Charge
This sequence diagram illustrates how immediate charging is used. Assume a WAP gateway that charges the user $ 0,01 per requested URL. Since it is acceptable to loose one tick worth $ 0,01, no prior reservations are made. The WAP gateway sends an immediate debit for each requested URL, and should a payment have as result failure, the user is disconnected. The operations which handle units are used exactly the same, except that the amount of application usage is indicated instead of a price.
: IpAppChargingSession
1: new()
2: createChargingSession(
3: directDebitAmountReq(
4: directDebitAmountRes( 5: forward notification
6: directDebitAmountReq(
7: directDebitAmountErr( 8: forward notification
9: release( )
1: The application creates a local object implementing the IpAppChargingSession interface. This object will receive response messages from the IpChargingSession object. 2: The application orders the creation of a session. No new object is created for the charging session handling in this example implementation. 3: The application requests to charge the user $ 0,01. 4: The payment is acknowledged. 5: The acknowledgement is forwarded in the application. 6: The application requests to charge the user $ 0,01. 7: The payment is reported to fail. 8: The failure report is forwarded in the application. (repeat steps 3 to 5 and 6 to 8 as long as you want to in any order you want to) 9: The application releases the session.
(from csapi)
This class diagram shows the application interfaces for charging and their relations to the service interfaces.
IpAppChargingSession
(f rom cs)
IpChargingSession
(f rom c s )
creditAmountReq() creditUnitReq() debitAmountReq() debitUnitReq() directCreditAmountReq() directCreditUnitReq() directDebitAmountReq() directDebitUnitReq() extendLifeTimeReq() getAmountLeft() getLifeTimeLeft() getUnitLeft() rateReq() release() reserveAmountReq() reserveUnitReq() 0..n
creditAmountErr() creditAmountRes() creditUnitErr() creditUnitRes() debitAmountErr() debitAmountRes() debitUnitErr() debitUnitRes() directCreditAmountErr() directCreditAmountRes() directCreditUnitErr() directCreditUnitRes() directDebitAmountErr() directDebitAmountRes() directDebitUnitErr() directDebitUnitRes() extendLifeTimeErr() extendLifeTimeRes() rateErr() rateRes() reserveAmountErr() reserveAmountRes() reserveUnitErr() reserveUnitRes() sessionEnded() 0..n
1 IpChargingManager
1 IpAppChargingManager &lt;&lt;uses&gt;&gt;
(from cs)
createChargingSession() createS plitChargingSession()
sessionAborted() &lt;&lt;new&gt;&gt; abortMultipleChargingSessions()
Figure 1: Application Interfaces This class diagram shows the interfaces of the charging SCF.
&lt;&lt;Interface&gt;&gt; IpService
(f rom csapi)
setCallback() setCallbackWithSessionID()
&lt;&lt;Interface&gt;&gt; IpChargingManager
&lt;&lt;Interface&gt;&gt; IpChargingSession
createChargingSession() createSplitChargingSession()
creditAmountReq() creditUnitReq() debitAmountReq() debitUnitReq() directCreditAmountReq() directCreditUnitReq() directDebitAmountReq() directDebitUnitReq() extendLifeTimeReq() getAmountLeft() getLifeTimeLeft() getUnitLeft() rateReq() release() reserveAmountReq() reserveUnitReq()
Figure 2: Service Interfaces
The Service Interface Specifications
Interface Specification Format
This clause defines the interfaces, methods and parameters that form a part of the API specification. The Unified Modelling Language (UML) is used to specify the interface classes. The general format of an interface specification is described below.
This shows a UML interface class description of the methods supported by that interface, and the relevant parameters and types. The Service and Framework interfaces for enterprise-based client applications are denoted by classes with name Ip&lt;name&gt;. The callback interfaces to the applications are denoted by classes with name IpApp&lt;name&gt;. For the interfaces between a Service and the Framework, the Service interfaces are typically denoted by classes with name IpSvc&lt;name&gt;, while the Framework interfaces are denoted by classes with name IpFw&lt;name&gt;.
Each method (API method &#39;call&#39;) is described. Both synchronous and asynchronous methods are used in the API. Asynchronous methods are identified by a &#39;Req&#39; suffix for a method request, and, if applicable, are served by asynchronous methods identified by either a &#39;Res&#39; or &#39;Err&#39; suffix for method results and errors, respectively. To handle responses and reports, the application or service developer must implement the relevant IpApp&lt;name&gt; or IpSvc&lt;name&gt; interfaces to provide the callback mechanism.
Each method parameter and its possible values are described. Parameters described as &#39;in&#39; represent those that must have a value when the method is called. Those described as &#39;out&#39; are those that contain the return result of the method when the method returns.
If relevant, a state model is shown to illustrate the states of the objects that implement the described interface.
Interface Class IpInterface
All application, framework and service interfaces inherit from the following interface. This API Base Interface does not provide any additional methods. &lt;&lt;Interface&gt;&gt; IpInterface
The Service Interfaces provide the interfaces into the capabilities of the underlying network - such as call control, user interaction, messaging, mobility and connectivity management. The interfaces that are implemented by the services are denoted as &#39;Service Interface&#39;. The corresponding interfaces that must be implemented by the application (e.g. for API callbacks) are denoted as &#39;Application Interface&#39;.
Interface Class IpService
Inherits from: IpInterface; All service interfaces inherit from the following interface.
setCallback (appInterface : in IpInterfaceRef) : void setCallbackWithSessionID (appInterface : in IpInterfaceRef, sessionID : in TpSessionID) : void
Method setCallback()
This method specifies the reference address of the callback interface that a service uses to invoke methods on the application. It is not allowed to invoke this method on an interface that uses SessionIDs. Multiple invocations of this method on an interface shall result in multiple callback references being specified. The SCS shall use the most recent callback interface provided by the application using this method. In the event that a callback reference fails or is no longer available, the next most recent callback reference available shall be used.
appInterface : in IpInterfaceRef
Specifies a reference to the application interface, which is used for callbacks.
TpCommonExceptions, P_INVALID_INTERFACE_TYPE
Method setCallbackWithSessionID()
This method specifies the reference address of the application&#39;s callback interface that a service uses for interactions associated with a specific session ID: e.g. a specific call, or call leg. It is not allowed to invoke this method on an interface that does not use SessionIDs. Multiple invocations of this method on an interface shall result in multiple callback references being specified. The SCS shall use the most recent callback interface provided by the application using this method. In the event that a callback reference fails or is no longer available, the next most recent callback reference available shall be used.
sessionID : in TpSessionID
Specifies the session for which the service can invoke the application&#39;s callback interface.
TpCommonExceptions, P_INVALID_SESSION_ID, P_INVALID_INTERFACE_TYPE
Charging Interface Classes
The Charging SCF is used by applications to charge for the usage of the applications. The charged user can be the same user as that uses the application. It is also possible that another user will pay the charge. In the interfaces of the Charging SCF a &quot;Request Number&quot; is used when invoking operations that operate on the user&#39;s account (directly or indirectly via reservations) in order to make retries possible after application, service, or communication errors. A retry of these operations can be done by invoking the same operation with the same Request Number. In the callback to the application, the Request Number to be used for the next request operation is returned. This is the only Request Number besides the one in the last request operation that can be used. This mechanism ensures that an application retries an operation when it does not receive an answer. The use of the Request Number ensures that there can only be one outstanding request per Charging Session. Only after an answer is received (result or error), the next request can be made. Note however that only asynchronous operations that could lead to over or under charging of the user require a request number. Because responses from the Charging SCF can be delayed in the network the Charging SCF shall guarantee that Request Numbers are unique in a timespan where delayed responses can arrive. Suppose, for example, that the response from a retried request is received indicating the next request number to use is 1 000. During the period that the response to the original request (which also carries the next request number to use equal to 1 000) can arrive, this request number may not be used again. The units (of different types) that are used in a TpVolumeSet are NOT consolidated by the charging SCF. The application must use the same units when making the reservation and when debiting the amount. For example, when after a reservation of 10 minutes a debit request for 5 seconds is done, an error will be returned. Split Charging Functionality. There are cases where a single instance of the merchant application may serve more than a one service user. Examples are multi-user games or conferences. Typically, the costs for the resources consumed by the single service instance will be split among all service users. On the other hand, a merchant application may show advertisements within its application, and in turn the company that is advertised may subside a certain percentage of the application cost. A consumer connecting to the merchant application pays only part of the costs, while the remainder is paid by the advertised company. To support this kind of application, multiple users can be specified when a charging session is created. The charging session interface itself is the same no matter if the split charging feature is used or not. It is subject to service level agreements that are negotiated between the OSA client provider and the network operator how the charge is split between the users.
Interface Class IpChargingManager
Inherits from: IpService. This interface is the &#39;service manager&#39; interface for the Charging Service. The Charging manager interface provides management functions to the charging service. The application programmer can use this interface to start charging sessions. This interface shall be implemented by a Charging SCF. As a minimum requirement, at least one of createChargingSession() or createSplitChargingSession() shall be implemented.
createChargingSession (appChargingSession : in IpAppChargingSessionRef, sessionDescription : in TpString, merchantAccount : in TpMerchantAccountID, user : in TpAddress, correlationID : in TpCorrelationID) : TpChargingSessionID createSplitChargingSession (appChargingSession : in IpAppChargingSessionRef, sessionDescription : in TpString, merchantAccount : in TpMerchantAccountID, users : in TpAddressSet, correlationID : in TpCorrelationID) : TpChargingSessionID
Method createChargingSession()
This method creates an instance of the IpChargingSession interface to handle the charging events related to the specified user and to the application invoking this method. An IpAppChargingManager should already have been passed to the IpChargingManager, otherwise the charging manager will not be able to report a sessionAborted() to the application (the application should invoke setCallback() if it wishes to ensure this). Returns chargingSession: Defines the session.
appChargingSession : in IpAppChargingSessionRef
Callback interface for the session in the application.
sessionDescription : in TpString
Descriptive text for informational purposes.
merchantAccount : in TpMerchantAccountID
Identifies the account of the party providing the application to be used.
user : in TpAddress
Specifies the user that is using the application. This may or may not be the user that will be charged. The Charging service will determine the charged user. When this method is invoked the Charging service shall determine if charging is allowed for this application for this subscriber. An exception shall be thrown if this type of charging is not allowed.
correlationID : in TpCorrelationID
This value can be used to correlate the charging to network activity.
TpChargingSessionID
TpCommonExceptions, P_INVALID_USER, P_INVALID_ACCOUNT
Method createSplitChargingSession()
This method creates an instance of the IpChargingSession interface to handle the charging events related to the specified users and to the application invoking this method. This method differs from createChargingSession() in that it allows to specify multiple users to be charged. The SCS implementation is responsible to figure out how later reserve and charge operations are split among these subscribers. The algorithm may be selected and controlled e.g. through the chargingParameter argument in the respective methods. The algorithms provided and the details how they interpret any parameters are vendor specific. Returns chargingSession: Defines the session.
users : in TpAddressSet
Specifies the users that are involved in using the application. This could be all users in a multi-party application (conference call, multi-user-game).
Interface Class IpAppChargingManager
Inherits from: IpInterface. This interface is the manager application interface for the Charging Service. The Charging manager interface provides the application Charging Session Management functions to the charging service. &lt;&lt;Interface&gt;&gt; IpAppChargingManager
sessionAborted (sessionID : in TpSessionID) : void &lt;&lt;new&gt;&gt; abortMultipleChargingSessions (chargingSessionSet : in TpSessionIDSet) : void
Method sessionAborted()
This method indicates to the application that the charging session object (at the gateway) has aborted or terminated abnormally. No further communication will be possible between the charging session and application.
Specifies the sessionID of the charging session that has aborted or terminated abnormally.
Method &lt;&lt;new&gt;&gt; abortMultipleChargingSessions()
The service may invoke this method on the IpAppChargingManager interface to indicate that a number of ongoing charging sessions have aborted or terminated abnormally. No further communication will be possible between the application and the charging sessions. This may be used for example in the event of service failure and recovery in order to instruct the application that a number of charging sessions have failed. The service shall provide a set of charging sessionIDs indicating to the application the charging sessions that have aborted. In the case that the service invokes this method and provides an empty set of sessionIDs, this shall be used to indicate that all charging sessions previously active on the IpChargingManager interface have been aborted.
chargingSessionSet : in TpSessionIDSet
Specifies the set of sessionIDs of charging sessions that have aborted or terminated abnormally. The empty set shall be used to indicate that all charging sessions have aborted.
Interface Class IpChargingSession
Inherits from: IpService. The Charging Session interface provides operations to facilitate transactions between a merchant and a user. The application programmer can use this interface to debit or credit amounts and/or units towards a user, to create and extend the lifetime of a reservation and to get information about what is left of the reservation. This interface shall be implemented by a Charging SCF. As a minimum requirement, the release() method shall be implemented. If the reserveAmountReq() method is implemented, at least one of the debitAmountReq() or the creditAmountReq() methods shall also be implemented. If the reserveUnitReq() method is implemented, at least one of the debitUnitReq() or the creditUnitReq() methods shall also be implemented. If neither the reserveAmountReq() nor the reserveUnitReq() method is implemented, then at least one of the directDebitAmountReq() or the directDebitUnitReq(), or the directCreditAmountReq(), or the directCreditUnitReq() methods shall be implemented.
creditAmountReq (sessionID : in TpSessionID, applicationDescription : in TpApplicationDescription, amount : in TpChargingPrice, closeReservation : in TpBoolean, requestNumber : in TpInt32) : void creditUnitReq (sessionID : in TpSessionID, applicationDescription : in TpApplicationDescription, volumes : in TpVolumeSet, closeReservation : in TpBoolean, requestNumber : in TpInt32) : void debitAmountReq (sessionID : in TpSessionID, applicationDescription : in TpApplicationDescription, amount : in TpChargingPrice, closeReservation : in TpBoolean, requestNumber : in TpInt32) : void debitUnitReq (sessionID : in TpSessionID, applicationDescription : in TpApplicationDescription, volumes : in TpVolumeSet, closeReservation : in TpBoolean, requestNumber : in TpInt32) : void directCreditAmountReq (sessionID : in TpSessionID, applicationDescription : in TpApplicationDescription, chargingParameters : in TpChargingParameterSet, amount : in TpChargingPrice, requestNumber : in TpInt32) : void directCreditUnitReq (sessionID : in TpSessionID, applicationDescription : in TpApplicationDescription, chargingParameters : in TpChargingParameterSet, volumes : in TpVolumeSet, requestNumber : in TpInt32) : void directDebitAmountReq (sessionID : in TpSessionID, applicationDescription : in TpApplicationDescription, chargingParameters : in TpChargingParameterSet, amount : in TpChargingPrice, requestNumber : in TpInt32) : void directDebitUnitReq (sessionID : in TpSessionID, applicationDescription : in TpApplicationDescription, chargingParameters : in TpChargingParameterSet, volumes : in TpVolumeSet, requestNumber : in TpInt32) : void extendLifeTimeReq (sessionID : in TpSessionID) : void getAmountLeft (sessionID : in TpSessionID) : TpChargingPrice getLifeTimeLeft (sessionID : in TpSessionID) : TpInt32 getUnitLeft (sessionID : in TpSessionID) : TpVolumeSet rateReq (sessionID : in TpSessionID, chargingParameters : in TpChargingParameterSet) : void release (sessionID : in TpSessionID, requestNumber : in TpInt32) : void reserveAmountReq (sessionID : in TpSessionID, applicationDescription : in TpApplicationDescription, chargingParameters : in TpChargingParameterSet, preferredAmount : in TpChargingPrice, minimumAmount : in TpChargingPrice, requestNumber : in TpInt32) : void reserveUnitReq (sessionID : in TpSessionID, applicationDescription : in TpApplicationDescription, chargingParameters : in TpChargingParameterSet, volumes : in TpVolumeSet, requestNumber : in TpInt32) : void
Method creditAmountReq()
This method credits an amount towards the reservation associated with the session. The amount left in the reservation will be increased by this amount. Each request to debit / credit an amount towards a reservation is handled separately. For example, two requests for a payment of EUR 1,- will give a total payment of EUR 2,-. A credit of EUR 1,- and a debit of EUR 1 will give a total payment of EUR 0,-.
applicationDescription : in TpApplicationDescription
Descriptive text for informational purposes (e.g. text presented on the bill and used in communication towards the user).
amount : in TpChargingPrice
The amount of specified currency to be credited towards the user.
closeReservation : in TpBoolean
If set to true, this parameter indicates that the remaining part of the reservation can be freed. This may also mean addition of currency to the subscriber&#39;s account if more credits than debits have been made. The session is not released, this has to be done explicitly by calling the release() method.
requestNumber : in TpInt32
Specifies the number given in the result of the previous operation on this session, or when creating the session. When no answer is received the same operation with the same parameters must be retried with the same requestNumber.
TpCommonExceptions, P_INVALID_SESSION_ID, P_INVALID_AMOUNT, P_INVALID_CURRENCY, P_INVALID_REQUEST_NUMBER
Method creditUnitReq()
This method credits a volume of application usage towards the reservation. The volumes left in the reservation of this will be increased by this amount. Each request to debit / credit a volume towards a reservation is handled separately. For example, two requests for a payment for 10 kilobytes will give a total payment for 20 kilobytes.
volumes : in TpVolumeSet
Specifies the credited volumes in different units, more specifically a sequence of data elements each containing the amount and applied unit.
If set to true, this parameter indicates that the reservation can be freed. The session is not released, this has to be done explicitly by calling the release() method.
TpCommonExceptions, P_INVALID_SESSION_ID, P_INVALID_VOLUME, P_INVALID_REQUEST_NUMBER
Method debitAmountReq()
This method debits an amount from the reservation. The amount left in the reservation will be decreased by this amount. Each request to debit / credit an amount towards a reservation is handled separately. For example, two requests for a payment of EUR 1,- will give a total payment of EUR 2,-. A credit of EUR 1,- and a debit of EUR 1 will give a total payment of EUR 0,-. When a debit operation would exceed the limit of the reservation, the debit operation fails.
The amount of specified currency to be debited from the user.
Method debitUnitReq()
This method debits a volume of application usage from the reservation. The volumes left in the reservation will be decreased by this amount. Each request to debit / credit a volume towards a reservation is handled separately. For example, two requests for a payment for 10 kilobytes will give a total payment for 20 kilobytes. When a debit operation would exceed the limit of the reservation, the debit operation succeeds, and the debited volumes will be the rest of the volumes in the reservation.
Specifies the charged volumes in different units, more specifically a sequence of data elements each containing the amount and applied unit.
Method directCreditAmountReq()
This method directly credits an amount towards the user. A possible reservation associated with this session is not influenced.
chargingParameters : in TpChargingParameterSet
These parameters and their values specify to the charging service what was provided to the end user so that the charging service can determine the applicable tariff.
Method directCreditUnitReq()
This method directly credits a volume of application usage towards the user. The volumes in a possible reservation associated with this session are not influenced.
Method directDebitAmountReq()
This method directly debits an amount towards the user. A possible reservation associated with this session is not influenced.
Method directDebitUnitReq()
This method directly credits a volume of application usage towards the user. The volumes in a possible reservation associated with this session are not influence.
Method extendLifeTimeReq()
With this method an application can request the lifetime of the reservation to be extended. If no reservation has been made on the charging session, this method raises an exception (P_TASK_REFUSED).
TpCommonExceptions, P_INVALID_SESSION_ID
Method getAmountLeft()
With this method an application can request the remaining amount of the reservation. Returns amountLeft: Gives the amount left in the reservation.
TpChargingPrice
Method getLifeTimeLeft()
With this method an application can request the remaining lifetime of the reservation. If no reservation has been made on the charging session, this method raises an exception (P_TASK_REFUSED). Returns reservationTimeLeft: Indicates the number of seconds that the session remains valid.
TpInt32
Method getUnitLeft()
With this method an application can request the remaining amount of the reservation. Returns volumesLeft: Specifies the remaining volumes in different units, more specifically a sequence of data elements each containing the amount and applied unit.
TpVolumeSet
Method rateReq()
This method is used when the application wants to have an item rated by the charging service. The result can be used to present pricing information to the end-user before the end-user actually wants to start using the service.
This method releases the session, no operations can be done towards this session anymore (not even retries). Unused parts of a reservation are freed.
Specifies the number given in the result of the previous operation on this session, or when creating the session.
TpCommonExceptions, P_INVALID_SESSION_ID, P_INVALID_REQUEST_NUMBER
Method reserveAmountReq()
This method is used when an application wants to reserve an amount of money for services to be delivered to a user. It is also possible to enlarge the existing amount reservation by invoking this method. If a reservation is extended, the lifetime of the reservation is re-initialized.
preferredAmount : in TpChargingPrice
The amount of specified currency that the application wants to be reserved.
minimumAmount : in TpChargingPrice
The minimum amount that can be used by the application if the preferred amount cannot be granted.
Method reserveUnitReq()
This method is used when an application wants to reserve volumes of application usage to be delivered to a user in the session. When using units it is assumed that the price setting for the units is handled by the network side services. It is also possible to enlarge the existing unit reservation by invoking this method.
Specifies the reserved volumes in different units, more specifically a sequence of data elements each containing the amount and applied unit. It is e.g. possible to make a reservation for 10 000 octets and 5 charging units.
Interface Class IpAppChargingSession
Inherits from: IpInterface. This application interface must be implemented by the client application to handle callbacks from the IpChargingSession.
&lt;&lt;Interface&gt;&gt; IpAppChargingSession
creditAmountErr (sessionID : in TpSessionID, requestNumber : in TpInt32, error : in TpChargingError, requestNumberNextRequest : in TpInt32) : void creditAmountRes (sessionID : in TpSessionID, requestNumber : in TpInt32, creditedAmount : in TpChargingPrice, reservedAmountLeft : in TpChargingPrice, requestNumberNextRequest : in TpInt32) : void creditUnitErr (sessionID : in TpSessionID, requestNumber : in TpInt32, error : in TpChargingError, requestNumberNextRequest : in TpInt32) : void creditUnitRes (sessionID : in TpSessionID, requestNumber : in TpInt32, creditedVolumes : in TpVolumeSet, reservedUnitsLeft : in TpVolumeSet, requestNumberNextRequest : in TpInt32) : void debitAmountErr (sessionID : in TpSessionID, requestNumber : in TpInt32, error : in TpChargingError, requestNumberNextRequest : in TpInt32) : void debitAmountRes (sessionID : in TpSessionID, requestNumber : in TpInt32, debitedAmount : in TpChargingPrice, reservedAmountLeft : in TpChargingPrice, requestNumberNextRequest : in TpInt32) : void debitUnitErr (sessionID : in TpSessionID, requestNumber : in TpInt32, error : in TpChargingError, requestNumberNextRequest : in TpInt32) : void debitUnitRes (sessionID : in TpSessionID, requestNumber : in TpInt32, debitedVolumes : in TpVolumeSet, reservedUnitsLeft : in TpVolumeSet, requestNumberNextRequest : in TpInt32) : void directCreditAmountErr (sessionID : in TpSessionID, requestNumber : in TpInt32, error : in TpChargingError, requestNumberNextRequest : in TpInt32) : void directCreditAmountRes (sessionID : in TpSessionID, requestNumber : in TpInt32, creditedAmount : in TpChargingPrice, requestNumberNextRequest : in TpInt32) : void directCreditUnitErr (sessionID : in TpSessionID, requestNumber : in TpInt32, error : in TpChargingError, requestNumberNextRequest : in TpInt32) : void directCreditUnitRes (sessionID : in TpSessionID, requestNumber : in TpInt32, creditedVolumes : in TpVolumeSet, requestNumberNextRequest : in TpInt32) : void directDebitAmountErr (sessionID : in TpSessionID, requestNumber : in TpInt32, error : in TpChargingError, requestNumberNextRequest : in TpInt32) : void directDebitAmountRes (sessionID : in TpSessionID, requestNumber : in TpInt32, debitedAmount : in TpChargingPrice, requestNumberNextRequest : in TpInt32) : void directDebitUnitErr (sessionID : in TpSessionID, requestNumber : in TpInt32, error : in TpChargingError, requestNumberNextRequest : in TpInt32) : void directDebitUnitRes (sessionID : in TpSessionID, requestNumber : in TpInt32, debitedVolumes : in TpVolumeSet, requestNumberNextRequest : in TpInt32) : void extendLifeTimeErr (sessionID : in TpSessionID, error : in TpChargingError) : void extendLifeTimeRes (sessionID : in TpSessionID, sessionTimeLeft : in TpInt32) : void rateErr (sessionID : in TpSessionID, error : in TpChargingError) : void rateRes (sessionID : in TpSessionID, rates : in TpPriceVolumeSet, validityTimeLeft : in TpDuration) : void reserveAmountErr (sessionID : in TpSessionID, requestNumber : in TpInt32, error : in TpChargingError, requestNumberNextRequest : in TpInt32) : void reserveAmountRes (sessionID : in TpSessionID, requestNumber : in TpInt32, reservedAmount : in TpChargingPrice, sessionTimeLeft : in TpInt32, requestNumberNextRequest : in TpInt32) : void reserveUnitErr (sessionID : in TpSessionID, requestNumber : in TpInt32, error : in TpChargingError,
requestNumberNextRequest : in TpInt32) : void reserveUnitRes (sessionID : in TpSessionID, requestNumber : in TpInt32, reservedUnits : in TpVolumeSet, sessionTimeLeft : in TpInt32, requestNumberNextRequest : in TpInt32) : void sessionEnded (sessionID : in TpSessionID, report : in TpSessionEndedCause) : void
Method creditAmountErr()
This method indicates that the corresponding request failed completely and that no money has been credited.
This is the ID of the session for which the operation was called.
This is the request number for this request.
error : in TpChargingError
Indicates the reason for failure. Possible errors are: P_CHS_ERR_CURRENCY and P_CHS_ERR_NO_CREDIT.
requestNumberNextRequest : in TpInt32
This request number must be used in the next request (requiring a Request Number) for this session.
Method creditAmountRes()
This method indicates that the corresponding request was successful.
creditedAmount : in TpChargingPrice
Indicates the credited amount.
reservedAmountLeft : in TpChargingPrice
The amount left of the reservation.
Method creditUnitErr()
This method indicates that the corresponding request failed completely and that no units have been credited.
Indicates the reason for failure. Possible errors are: P_CHS_ERR_VOLUMES and P_CHS_ERR_NO_CREDIT.
Method creditUnitRes()
creditedVolumes : in TpVolumeSet
Indicates the credited volumes of application usage.
reservedUnitsLeft : in TpVolumeSet
The volume of application usage left in the reservation.
Method debitAmountErr()
This method indicates that the corresponding request failed completely and that no money has been debited.
Indicates the reason for failure. Possible errors are: P_CHS_ERR_CURRENCY and P_CHS_ERR_RESERVATION_LIMIT.
Method debitAmountRes()
debitedAmount : in TpChargingPrice
Indicates the debited amount.
Method debitUnitErr()
This method indicates that the corresponding request failed completely and that no units have been debited.
Indicates the reason for failure. Possible errors are: P_CHS_ERR_VOLUMES and P_CHS_ERR_RESERVATION_LIMIT.
Method debitUnitRes()
debitedVolumes : in TpVolumeSet
Indicates the debited volumes of application usage.
Method directCreditAmountErr()
Indicates the reason for failure. Possible errors are: P_CHS_ERR_PARAMETER, P_CHS_ERR_NO_CREDIT, P_CHS_ERR_CURRENCY.
Method directCreditAmountRes()
Method directCreditUnitErr()
Indicates the reason for failure. Possible errors are: P_CHS_ERR_PARAMETER, P_CHS_ERR_NO_CREDIT, P_CHS_ERR_VOLUMES.
Method directCreditUnitRes()
Method directDebitAmountErr()
Indicates the reason for failure. Possible errors are: P_CHS_ERR_PARAMETER, P_CHS_ERR_NO_DEBIT, P_CHS_ERR_CURRENCY, P_CHS_ERR_CONFIRMATION_REQUIRED.
Method directDebitAmountRes()
Method directDebitUnitErr()
Indicates the reason for failure. Possible errors are: P_CHS_ERR_PARAMETER, P_CHS_ERR_NO_DEBIT, P_CHS_ERR_VOLUMES, P_CHS_ERR_ CONFIRMATION_REQUIRED.
Method directDebitUnitRes()
Method extendLifeTimeErr()
This method indicates that the corresponding request failed.
Indicates the reason for failure. Possible errors are: P_CHS_ERR_NO_EXTEND.
Method extendLifeTimeRes()
sessionTimeLeft : in TpInt32
Indicates the number of seconds that the session remains valid.
Method rateErr()
Indicates the reason for failure. Possible errors are: P_CHS_ERR_PARAMETER.
Method rateRes()
rates : in TpPriceVolumeSet
The applicable rates.
validityTimeLeft : in TpDuration
Indicates the number of milliseconds that this information remains valid.
Method reserveAmountErr()
This method indicates that the corresponding request failed. The reservation cannot be used.
This is the same as the session ID returned in the request.
Indicates the reason for failure. Possible errors are: P_CHS_ERR_PARAMETER, P_CHS_ERR_RESERVATION_LIMIT, P_CHS_ERR_CURRENCY, P_CHS_ERR_NO_EXTEND, P_CHS_ERR_CONFIRMATION_REQUIRED.
Method reserveAmountRes()
reservedAmount : in TpChargingPrice
The amount reserved. If there was already a pending reservation, the sum of that and the new reservation is given.
Indicates the number of seconds that the session and the reservation therein remain valid.
Method reserveUnitErr()
Indicates the reason for failure. Possible errors are: P_CHS_ERR_PARAMETER, P_CHS_ERR_VOLUMES, P_CHS_ERR_RESERVATION_LIMIT, P_CHS_ERR_NO_EXTEND, P_CHS_ERR_CONFIRMATION_REQUIRED.
Method reserveUnitRes()
reservedUnits : in TpVolumeSet
The volume of application usage reserved. If there was already a pending reservation, the sum of that and the new reservation is returned. E.g. a pending reservation of 25 charging units and a new reservation of 1 000 octets and 10 charging units will result in two TpVolume elements for this parameter: 1 000 octets and 35 charging units.
Method sessionEnded()
This method indicates to the application that the charging session has terminated in the charging server. The application is expected to deassign the charging session object after having received the sessionEnded.
Specifies the charging sessionID.
report : in TpSessionEndedCause
Specifies the cause the charging session is terminated.
State Transition Diagrams for IpChargingSession
IpChargingManager.createChargingSession
Session Created getLifeTimeLeft extendLifeTimeReq getAmountLeft debitAmountReq creditAmount Req reserveAmountReq getLifeTimeLeft extendLifeTimeReq getUnitLeft reserveUnitReq debitUnit Req creditUnitReq reserveUnitReq
reserveAmountReq Amount Reserved Volume Reserved
&quot;Reservation Closed&quot;
directDebit Unit Req directCreditUnitReq directDebitAmountReq directCreditAmountReq rateReq
&quot; lifetime expired&quot; release IpAccess.terminateServiceAgreement
Figure 3: Charging Session Handling
Session Created State
In this state the Charging Session is created. No reservations have been made. In this state, the applications have the possibility to perform direct debits and credits on the user&#39;s account and to request rating.
Amount Reserved State
In this state a reservation for a certain maximum amount has been made. This reservation has succeeded and the application has the possibility to perform incremental debits/credits on this reserved amount until either the application chooses to close the reservation or the reservation limit is reached, or the Charging Session is released (either explicitly by the application or implicitly when the lifetime of the session has expired). The application can also extend the reservation and control its lifetime. If the application chooses to close the reservation or the original reservation limit is reached, a transition to the &#39;Reservation Ended&#39; state results.
Volume Reserved State
In this state a reservation for a certain maximum volume (kilobytes, emails, html-pages, etc) has been made. This reservation has succeeded and the application has the possibility to perform incremental debits/credits on this reserved volume until either the application chooses to close the reservation or the reservation limit is reached, or the Charging Session is released (either explicitly by the application or implicitly when the lifetime of the session has expired). The application can also extend the reservation and control its lifetime. If the application chooses to close the reservation or the original reservation limit is reached, a transition to the &#39;Reservation Ended&#39; state results.
Reservation Ended State
In this state an amount or volume reservation has been closed by the application, or the reservation limit has been reached. The charging session may remain active in order to carry out non-reservation related tasks such direct credit or debit operations. No further charging reservations shall be possible for this session, a new session is therefore required for future charging reservations. The charging session is closed on lifetime expiry or application &#39;release&#39;.
Content Based Charging Service Properties
Type INTEGER_SET Description/Interpretation Indicates the supported address plan (defined in TpAddressPlan.) E.g. {P_ADDRESS_PLAN_E164, P_ADDRESS_PLAN_IP}) Indicates the unit-types that are supported, e.g. {P_CHS_UNIT_OCTETS, P_CHS_UNIT_SECONDS} Indicates the currency-types that are supported according to ISO 4217: 1995, e.g. {&quot;EUR&quot;, &quot;DEM&quot;, &quot;NLG&quot;} Indicates if charging based on units (rather then amounts) is supported. Value = TRUE: unit based charging is supported Value = FALSE: unit based charging is not supported If unit charging is supported or not or is selected or not does not tell anything about amount charging.
The following table lists properties relevant for CBC SCF.
Property P_ADDRESSPLAN
P_SUPPORTED_UNITS
INTEGER_SET
P_SUPPORTED_CURRENCIES
P_UNIT_CHARGING
BOOLEAN_SET
42 Property P_AMOUNT_CHARGING Type BOOLEAN_SET
ETSI ES 203 915-12 V1.1.1 (2005-04) Description/Interpretation Indicates if charging based on amounts (rather then units) is supported. Value = TRUE: amount based charging is supported Value = FALSE: amount based charging is not supported If amount charging is supported or not or is selected or not does not tell anything about unit charging Indicates if split charging feature is available. Value = TRUE: split charging is supported Value = FALSE: split charging is not supported Upon service registration, this property describes if the SCS supports debiting at all and if it can be turned off by the application. Upon service instantiation, it describes which mode(s) the client has selected. Upon service registration, this property describes if the SCS supports crediting at all and if it can be turned off by the application. Upon service instantiation, it describes which mode(s) the client has selected
P_SPLIT_CHARGING
P_DEBITING
P_CREDITING
The previous table lists properties related to the capabilities of the SCS itself. The following table lists properties that are used in the context of the Service Level Agreement, e.g. to restrict the access of applications to the capabilities of the SCS.
Property P_DEFAULT_LIFETIME P_LIFETIME_INCREMENT P_MAX_LIFETIME P_MIN_DEBIT_AMOUNT Type INTEGER_INTERVAL INTEGER_INTERVAL INTEGER_INTERVAL STRING_SET Description/Interpretation Defines the default lifetime for a charging reservation in milliseconds. Defines the duration in milliseconds by which the lifetime of a charging reservation can be extended. Defines the maximum lifetime for a charging reservation in milliseconds. Defines the minimum amounts for a debit operation, depending on currency. Each set element is a string that contains the amount, formatted as a string and followed by the currency. Example: {&#39;1,00 EUR&#39;, &#39;0,5 GBP&#39;} means that the minimum amount in Euro is 1,00, while in Pound Sterling it is 0,5. Defines the maximum amount for a debit operation, similar to P_MIN_DEBIT_AMOUNT. Defines the range for amounts that can be credited. Valid for any allowed currency. Defines the range for the allowed amount of parallel charging sessions. Defines the range for the allowed number of charging sessions per hour.
P_MAX_DEBIT_AMOUNT P_CREDIT_AMOUNT P_PARALLEL_SESSIONS P_SESSIONS_HOUR
STRING_SET INTEGER_INTERVAL INTEGER_INTERVAL INTEGER_INTERVAL
Charging Data Definitions
This clause provides the Charging specific data definitions necessary to support the OSA interface specification. The general format of a data definition specification is the following: • Data type, that shows the name of the data type.
Description, that describes the data type. Tabular specification, that specifies the data types and values of the data type. Example, if relevant, shown to illustrate the data type.
All data types referenced but not defined in this clause are common data definitions which may be found in ES 203 915-2.
IpChargingManager
Defines the address of an IpChargingManager Interface.
IpChargingManagerRef
Defines a Reference to type IpChargingManager.
IpAppChargingManager
Defines the address of an IpAppChargingManager Interface.
IpAppChargingManagerRef
Defines a Reference to type IpAppChargingManager.
Defines the address of an IpChargingSession Interface.
IpChargingSessionRef
Defines a Reference to type IpChargingSession.
Defines the address of an IpAppChargingSession Interface.
IpAppChargingSessionRef
Defines a Reference to type IpAppChargingSession.
TpApplicationDescription
Sequence Element Name Text AppInformation Sequence Element Type TpString TpAppInformationSet
Defines a Sequence of Data Elements that specifies what is about to be charged.
11.1.10 TpAppInformationSet
Defines a Numbered Set of Data Elements that further describe what is about to be charged. The data elements are of type TpAppInformation.
11.1.11 TpAppInformation
Defines a Tagged Choice of Data Elements that comprise an individual application information.
Tag Element Type TpAppInformationType
Tag Element Value P_APP_INF_TIMESTAMP
Choice Element Type TpDateAndTime
Choice Element Name Timestamp
11.1.12 TpAppInformationType
Defines the possible information items.
Name P_APP_INF_TIMESTAMP Value 0 Description The information item contains a timestamp.
11.1.13 TpSessionEndedCause
Defines the reason for which a charging session is released.
Name P_CHS_CAUSE_UNDEFINED P_CHS_CAUSE_TIMER_EXPIRED Value 0 1 Description The reason of release is not known, because no info was received from the network. The session lifetime has expired.
11.1.14 TpMerchantAccountID
Defines a Sequence of Data Elements that defines the used service.
Sequence Element Name MerchantID AccountID TpString TpInt32 Sequence Element Type
11.1.15 TpCorrelationID
Defines the Sequence of Data Elements that identify a correlation.
Sequence Element Name CorrelationID CorrelationType Sequence Element Type TpSessionID TpCorrelationType
11.1.16 TpCorrelationType
Defines the type of correlation. This type can be extended with operator specific items.
Name P_CHS_CORRELATION_UNDEFINED P_CHS_CORRELATION_VOICE P_CHS_CORRELATION_DATA P_CHS_CORRELATION_MM Value 0 1 2 3 Description Unknown correlation type Voice Call Data Session Multi Media Session
11.1.17 TpChargingPrice
Defines the Sequence of Data Elements that identify a price.
Sequence Element Name Currency Amount Currencies as defined by ISO 4217: 1995. Sequence Element Type TpString TpAmount
11.1.18 TpAmount
Defines the Sequence of Data Elements that define an amount in integers as &quot;Number &#215; 10 ^ Exponent&quot; (i.e. if Number = 6 543 and Exponent = -2 then the amount is 65,43). This representation avoids unwanted rounding off.
Sequence Element Name Number Exponent Sequence Element Type TpInt32 TpInt32
11.1.19 TpChargingParameterSet
Defines a Numbered Set of Data Elements of TpChargingParameter.
11.1.20 TpChargingParameter
Sequence Element Name ParameterID ParameterValue Sequence Element Type TpChargingParameterID TpChargingParameterValue
11.1.21 TpChargingParameterID
Defines the type of charging parameter. This type can be extended with operator specific items.
Name P_CHS_PARAM_UNDEFINED P_CHS_PARAM_ITEM P_CHS_PARAM_SUBTYPE P_CHS_PARAM_CONFIRMATION_ID P_CHS_PARAM_CONTRACT Value 0 1 2 3 4 Description Unknown parameter Parameter represents kind of service delivered to the end user Parameter represents subtype / operation of service delivered to the end user The ID that references a stored confirmation to authorize the required payment Parameter represents a signed confirmation, which shall be of the type P_CHS_PARAMETER_OCTETSET
11.1.22 TpChargingParameterValue
Defines the Tagged Choice of Data Elements that identify a charging parameter.
Tag Element Type TpChargingParameterValueType
Tag Element Value P_CHS_PARAMETER_INT32 P_CHS_PARAMETER_FLOAT P_CHS_PARAMETER_STRING P_CHS_PARAMETER_BOOLEAN P_CHS_PARAMETER_OCTETSET
Choice Element Type TpInt32 TpFloat TpString TpBoolean TpOctetSet
Choice Element Name IntValue FloatValue StringValue BooleanValue OctetValue
11.1.23 TpChargingParameterValueType
Defines the type of charging parameter.
Name P_CHS_PARAMETER_INT32 P_CHS_PARAMETER_FLOAT P_CHS_PARAMETER_STRING P_CHS_PARAMETER_BOOLEAN P_CHS_PARAMETER_OCTETSET Value 0 1 2 3 4 Description Parameter represented by a TpInt32 Parameter represented by a TpFloat Parameter represented by a TpString Parameter represented by a TpBoolean Parameter represented by a TpOctetSet
11.1.24 TpVolumeSet
Defines the Numbered Set of Data Elements that describes list TpVolume.
11.1.25 TpVolume
Defines a volume.
Sequence Element Name Amount Unit Sequence Element Type TpAmount TpUnitID
11.1.26 TpUnitID
Defines the unit that is used in a TpVolume. This type can be extended with operator specific items.
Name P_CHS_UNIT_UNDEFINED P_CHS_UNIT_NUMBER P_CHS_UNIT_OCTETS P_CHS_UNIT_SECONDS P_CHS_UNIT_MINUTES P_CHS_UNIT_HOURS P_CHS_UNIT_DAYS Value 0 1 2 3 4 5 6 Description Undefined number of times / events unit is octets unit is seconds unit is minutes unit is hours unit is days
11.1.27 TpChargingSessionID
Defines the Sequence of Data Elements that unambiguously specify the Charging Session object.
Sequence Element Name ChargingSessionReference ChargingSessionID RequestNumberFirstRequest Sequence Element Type IpChargingSessionRef TpSessionID TpInt32 Sequence Element Description This element specifies the interface reference for the charging session object. This element specifies the session ID for the charging session. This element specifies the request number to use for the next request.
11.1.28 TpPriceVolumeSet
Defines a Numbered Set of Data Elements of TpPriceVolume.
11.1.29 TpPriceVolume
Defines the Sequence of Data Elements that identify a price for a volume.
Sequence Element Name Price Volume Sequence Element Type TpChargingPrice TpVolume
11.1.30 TpChargingError
Indicates the error that occurred.
Name P_CHS_ERR_UNDEFINED P_CHS_ERR_ACCOUNT P_CHS_ERR_USER P_CHS_ERR_PARAMETER P_CHS_ERR_NO_DEBIT P_CHS_ERR_NO_CREDIT P_CHS_ERR_VOLUMES P_CHS_ERR_CURRENCY P_CHS_ERR_NO_EXTEND P_CHS_ERR_RESERVATION_LIMIT P_CHS_ERR_CONFIRMATION_REQUIRED Value Description 0 Generic error. 1 Merchant account unknown. 2 Unknown user. 3 The set of charging parameters contains an unknown parameter, or a required parameter is missing. 4 For some reason the application is not allowed to get money from this user. 5 For some reason the application is not allowed to pay this user. 6 Required volumes are missing. 7 This currency is not supported for this transaction. 8 Request to extend the lifetime of a reservation is rejected. 9 This amount or volume violates the bounds of the reservation. 10 A user confirmation is required, but could not be obtained by the SCS. The SCS expects that the client initiates a stored confirmation scenario.
Name P_INVALID_ACCOUNT P_INVALID_REQUEST_NUMBER P_INVALID_USER P_INVALID_VOLUME Description Invalid merchant account specified. Invalid request number specified. Invalid user specified. Invalid volume specified.
The following are the list of exception classes, which are used in this interface of the API.
Each exception class contains the following structure:
Structure Element Name ExtraInformation Structure Element Type TpString Structure Element Description Carries extra information to help identify the source of the exception, e.g. a parameter name
Annex A (normative): OMG IDL Description of Charging SCF
The OMG IDL representation of this interface specification is contained in a text file (cs.idl contained in archive es_20391512v010101p0.zip) which accompanies the present document.
Annex B (informative): W3C WSDL Description of Charging SCF
The W3C WSDL representation of this interface specification is contained in a text file (cs.wsdl contained in archive es_20391512v010101p0.zip) which accompanies the present document.
Annex C (informative): Java™ API Description of the Charging SCF
The Java™ API realisation of this interface specification is produced in accordance with the Java™ Realisation rules defined in ES 203 915-1. These rules aim to deliver for Java™, a developer API, provided as a realisation, supporting a Java™ API that represents the UML specifications. The rules support the production of both J2SE™ and J2EE™ versions of the API from the common UML specifications. The J2SE™ representation of this interface specification is provided as Java™ Code, contained in archive 20391512J2SE.zip. The J2EE™ representation of this interface specification is provided as Java™ Code, contained in archive 20391512J2EE.zip. Both these archives can be found in es_20391512v010101p0.zip which accompanies the present document.
Annex D (informative): Contents of 3GPP OSA R6 Charging
All of the present document is relevant for TS 129 198-12 V6 (Release 6).
Annex E (informative): Description of Charging for 3GPP2 cdma2000 networks
This annex is intended to define the OSA API Stage 3 interface definitions and it provides the complete OSA specifications. It is an extension of OSA API specifications capabilities to enable operation in cdma2000 systems environment. They are in alignment with 3GPP2 Stage 1 requirements and Stage 2 architecture defined in [52], [53] and [54] of EN 203 915-1, clause 2. These requirements are expressed as additions to and/or exclusions from the 3GPP Release 6 specification. The information given here is to be used by developers in 3GPP2 cdma2000 network architecture to interpret the 3GPP OSA specifications.
The term UMTS is not applicable for the cdma2000 family of standards. Nevertheless these terms are used (TR 121 905) mostly in the broader sense of &quot;3G Wireless System&quot;. If not stated otherwise there are no additions or exclusions required. CAMEL and CAP mappings are not applicable for cdma2000 systems.
There are no additions or exclusions.
Normative references on TS 123 078 and on TS 129 078 are not applicable for cdma2000 systems.
Clause 3: Definitions and abbreviations
Clause 4: Charging SCF
Clause 5: Sequence Diagrams
Clause 6: Class Diagrams
Clause 7: The Service Interface Specifications
Clause 8: Charging Interface Classes
Clause 9: State Transition Diagrams
E.2.10 Clause 10: Content Based Charging Service Properties
E.2.11 Clause 11: Data Definitions
E.2.12 Clause 12: Exception Classes
E.2.13 Annex A (normative): OMG IDL Description of Charging SCF
E.2.14 Annex B (informative): W3C WSDL Description of Charging SCF
E.2.15 Annex C (informative): Java™ API Description of the Charging SCF
Annex F (informative): Record of changes
The following is a list of the changes made to the present document for each release. The list contains the names of all changed, deprecated, added or removed items in the specifications and not the actual changes. Any type of change information that is important to the reader is put in the final clause of this annex. Changes are specified as changes to the prior major release, but every minor release will have its own part of the table allowing the reader to know when the actual change was made.
Identifier Comments Interfaces added in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Interfaces deprecated in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Interfaces removed in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Methods added in ES 203 915-12 version 1.1.1 (Parlay 5.0) IpAppChargingManager.abortMultipleChargingSessions()
Identifier Comments Methods deprecated in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Methods modified in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Methods removed in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Data Definitions added in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Data Definitions modified in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Data Definitions removed in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Service Properties added in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Service Properties deprecated in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Service Properties modified in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Service Properties removed in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Exceptions added in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Exceptions modified in ES 203 915-12 version 1.1.1 (Parlay 5.0)
Identifier Comments Exceptions removed in ES 203 915-12 version 1.1.1 (Parlay 5.0)
V1.1.1 V1.1.1 February 2005 April 2005 Membership Approval Procedure Publication MV 20050408: 2005-02-08 to 2005-04-08