ETSI TS V9.0.0 ( ) Technical Specification

Transcription

1 TS V9.0.0 ( ) Technical Specification Digital cellular telecommunications system (Phase 2+); Universal Mobile Telecommunications System (UMTS); LTE; Open Service Access (OSA) Application Programming Interface (API); Part 10: Connectivity manager Service Capability Feature (SCF) (3GPP TS version Release 9)

2 1 TS V9.0.0 ( ) Reference RTS/TSGC v900 Keywords GSM, LTE, UMTS 650 Route des Lucioles F Sophia Antipolis Cedex - FRANCE Tel.: Fax: Siret N NAF 742 C Association à but non lucratif enregistrée à la Sous-Préfecture de Grasse (06) N 7803/88 Important notice Individual copies of the present document can be downloaded from: The present document may be made available in more than one electronic version or in print. In any case of existing or perceived difference in contents between such versions, the reference version is the Portable Document Format (PDF). In case of dispute, the reference shall be the printing on printers of the PDF version kept on a specific network drive within Secretariat. Users of the present document should be aware that the document may be subject to revision or change of status. Information on the current status of this and other documents is available at If you find errors in the present document, please send your comment to one of the following services: Copyright Notification No part may be reproduced except as authorized by written permission. The copyright and the foregoing restriction extend to reproduction in all media. European Telecommunications Standards Institute All rights reserved. DECT TM, PLUGTESTS TM, UMTS TM, TIPHON TM, the TIPHON logo and the logo are Trade Marks of registered for the benefit of its Members. 3GPP TM is a Trade Mark of registered for the benefit of its Members and of the 3GPP Organizational Partners. LTE is a Trade Mark of currently being registered for the benefit of its Members and of the 3GPP Organizational Partners. GSM and the GSM logo are Trade Marks registered and owned by the GSM Association.

3 2 TS V9.0.0 ( ) Intellectual Property Rights IPRs essential or potentially essential to the present document may have been declared to. The information pertaining to these essential IPRs, if any, is publicly available for members and non-members, and can be found in SR : "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to in respect of standards", which is available from the Secretariat. Latest updates are available on the Web server ( Pursuant to the IPR Policy, no investigation, including IPR searches, has been carried out by. No guarantee can be given as to the existence of other IPRs not referenced in SR (or the updates on the Web server) which are, or may be, or may become, essential to the present document. Foreword This Technical Specification (TS) has been produced by 3rd Generation Partnership Project (3GPP). The present document may refer to technical specifications or reports using their 3GPP identities, UMTS identities or GSM identities. These should be interpreted as being references to the corresponding deliverables. The cross reference between GSM, UMTS, 3GPP and identities can be found under

4 3 TS V9.0.0 ( ) Contents Intellectual Property Rights... 2 Foreword... 2 Foreword... 6 Introduction Scope References Definitions and abbreviations Definitions Abbreviations Connectivity Manager SCF Sequence Diagrams Operator Selects Service Components and creates a new VPrP Operator Browses Virtual Provisioned Pipe Operator Browses SAPs and Sites Class Diagrams The Service Interface Specifications Interface Specification Format Interface Class Method descriptions Parameter descriptions State Model Base Interface Interface Class IpInterface Service Interfaces Overview Generic Service Interface Interface Class IpService Method setcallback() Method setcallbackwithsessionid() Connectivity Manager Interface Classes Interface Class IpConnectivityManager Method getqosmenu() Method getenterprisenetwork() Interface Class IpEnterpriseNetwork Method getsitelist() Method getvprn() Method getsite() Interface Class IpEnterpriseNetworkSite Method getsaplist() Method getsiteid() Method getsitelocation() Method getsitedescription() Method getipsubnet() Method getsapipsubnet() Interface Class IpQoSMenu Method gettemplate() Method gettemplatelist() Interface Class IpQoSTemplate Method gettemplatetype() Method getdescription()... 33

5 4 TS V9.0.0 ( ) Method setslaid() Method getpipeqosinfo() Method setpipeqosinfo() Method getvalidityinfo() Method setvalidityinfo() Method setprovisionedqosinfo() Method getprovisionedqosinfo() Method getdscodepoint() Interface Class IpVPrN Method getvprplist() Method getvprp() Method createvprp() Method deletevprp() Interface Class IpVPrP Method getvprpid() Method getslaid() Method getstatus() Method getprovisionedqosinfo() Method getvalidityinfo() Method getpipeqosinfo() Method getdscodepoint() State Transition Diagrams Data Definitions Connectivity Manager Data Types TpIPSubnet TpIPv4AddType TpIPVersion TpVprpStatus TpDsCodepoint TpProvisionedQoSInfo TpDelayDescriptor TpLossDescriptor TpJitterDescriptor TpNameDescrpTagInt TpNameDescrpTagString TpTagValue TpNameDescrpTagExcessLoadAction TpAction TpPipeQoSInfo TpNameDescrpTagDir TpTrafficDirection TpEndpoint TpSiteOrSap TpLoadDescriptor TpValidityInfo TpNameDescrpTagDateTime TpNameDescrpTagTimePeriod TpNameDescrpTagTimeOfDay TpNameDescrpTagDayOfWeek TpNameDescrpTagMonth Exception Classes Annex A (normative): Annex B (informative): Annex C (informative): Annex D (informative): OMG IDL Description of Connectivity Manager SCF W3C WSDL Description of Connectivity Manager SCF Java API Description of the Connectivity Manager SCF Description of Connectivity Manager for 3GPP2 cdma2000 networks D.1 General Exceptions... 56

6 5 TS V9.0.0 ( ) D.2 Specific Exceptions D.2.1 Clause 1: Scope D.2.2 Clause 2: References D.2.3 Clause 3: Definitions and abbreviations D.2.4 Clause 4: Connectivity Manager SCF D.2.5 Clause 5: Sequence Diagrams D.2.6 Clause 6: Class Diagrams D.2.7 Clause 7: The Service Interface Specifications D.2.8 Clause 8: Connectivity Manager Interface Classes D.2.9 Clause 9: State Transition Diagrams D.2.10 Clause 10: Connectivity Manager Service Properties D.2.11 Clause 11: Data Definitions D.2.12 Clause 12: Exception Classes D.2.13 Annex A (normative): OMG IDL Description of Connectivity Manager SCF D.2.14 Annex B (informative): W3C WSDL Description of Connectivity Manager SCF Annex E (informative): Change history History... 59

7 6 TS V9.0.0 ( ) Foreword This Technical Specification has been produced by the 3 rd Generation Partnership Project (3GPP). The contents of the present document are subject to continuing work within the TSG and may change following formal TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an identifying change of release date and an increase in version number as follows: Version x.y.z where: x the first digit: 1 presented to TSG for information; 2 presented to TSG for approval; 3 or greater indicates TSG approved document under change control. y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, updates, etc. z the third digit is incremented when editorial only changes have been incorporated in the document. Introduction The present document is part 10 of a multi-part TS covering the 3 rd Generation Partnership Project: Technical Specification Group Core Network; Open Service Access (OSA); Application Programming Interface (API), as identified below. The API specification (3GPP TS ) is structured in the following Parts: Part 1: "Overview"; Part 2: "Common Data Definitions"; Part 3: "Framework"; Part 4: "Call Control"; Sub-part 1: "Call Control Common Definitions"; Sub-part 2: "Generic Call Control SCF"; Sub-part 3: "Multi-Party Call Control SCF"; Sub-part 4: "Multi-Media Call Control SCF"; Sub-part 5: "Conference Call Control SCF"; Part 5: "User Interaction SCF"; Part 6: "Mobility SCF"; Part 7: "Terminal Capabilities SCF"; Part 8: "Data Session Control SCF"; Part 9: "Generic Messaging SCF"; (not part of 3GPP Release 8) Part 10: "Connectivity Manager SCF"; (new in 3GPP Release 8) Part 11: "Account Management SCF"; Part 12: "Charging SCF". Part 13: "Policy Management SCF"; Part 14: "Presence and Availability Management SCF"; Part 15: "Multi Media Messaging SCF"; Part 16: "Service Broker SCF". The Mapping specification of the OSA APIs and network protocols (3GPP TR ) is also structured as above. A mapping to network protocols is however not applicable for all Parts, but the numbering of Parts is kept. Also in case a Part is not supported in a Release, the numbering of the parts is maintained.

8 7 TS V9.0.0 ( ) Table: Overview of the OSA APIs & Protocol Mappings & family OSA API specifications family OSA API Mapping family Overview Overview Common Data Definitions Not Applicable Framework Not Applicable Call Generic Call Control CAP mapping Control Generic Call Control INAP mapping (CC) Common Generic Multi- Multimedia Conf Generic Call Control Megaco mapping SCF CC data definitions CC SCF Party CC SCF CC SCF CC SCF Multiparty Call Control ISC mapping User Interaction SCF User Interaction CAP mapping User Interaction INAP mapping User Interaction Megaco mapping User Interaction SMS mapping Mobility SCF User Status and User Location MAP mapping User Status and User Location SIP mapping Terminal Capabilities SCF Not Applicable Data Session Control SCF Data Session Control CAP mapping Generic Messaging SCF Not Applicable Connectivity Manager SCF Not Applicable Account Management SCF Not Applicable Charging SCF Not Applicable Policy Management SCF Not Applicable Presence & Availability Management SCF Not Applicable Multi-media Messaging SCF Not Applicable Service Broker SCF Not Applicable

9 8 TS V9.0.0 ( ) 1 Scope The present document is Part 10 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 concepts and the functional architecture for the OSA are contained in 3GPP TS [3]. The requirements for OSA are contained in 3GPP TS [2]. The present document specifies the Connectivity Manager Service Capability Feature (SCF) aspects of the interface. All aspects of the Connectivity Manager 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 The process by which this task is accomplished is through the use of object modelling techniques described by the Unified Modelling Language (UML). This specification has been defined jointly between 3GPP TSG CT WG5, TISPAN and the Parlay Group, in cooperation with a number of JAIN Community member companies. 2 References The following documents contain provisions which, through reference in this text, constitute provisions of the present document. References are either specific (identified by date of publication, edition number, version number, etc.) or non-specific. For a specific reference, subsequent revisions do not apply. For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same Release as the present document. [1] 3GPP TS "Open Service Access; Application Programming Interface; Part 1: Overview". [2] 3GPP TS : "Service Requirement for the Open Services Access (OSA); Stage 1". [3] 3GPP TS : "Open Service Access (OSA); Stage 2". 3 Definitions and abbreviations 3.1 Definitions For the purposes of the present document, the terms and definitions given in TS [1] apply.

10 9 TS V9.0.0 ( ) 3.2 Abbreviations For the purposes of the present document, the abbreviations given in TS [1] apply. 4 Connectivity Manager SCF Connectivity Manager includes the APIs between the enterprise operator and the provider network for the two parties to establish QoS parameters for enterprise network packets travelling through the provider network. The Connectivity Manager service provides tools for the enterprise operator to set up a Provisioned QoS service in the provider network. The QoS measures used in the enterprise network are outside the scope of the service. The API does not require any specific QoS method to be used in the enterprise network, nor in the provider network. However, in order for Provisioned QoS service to be applied to packets arriving from the enterprise network into the provider network, the packets have to be marked using DS Codepoint marking. Once the packets are so marked, they can enjoy the QoS service provisioned in the provider network. APIs provide the enterprise network operator on-line access to provision quality of service measures that control the enterprise's own traffic passing through the provider network. Using APIs the operator can create Virtual Provisioned Pipes (VPrPs) in the provider network to carry the enterprise traffic and support it with pre-specified quality of service attributes. A VPrP can be thought of as a Virtual Leased Line (VLL) provisioned to deliver pre-specified QoS. The provider may offer to the enterprise operator a set of templates that are used by the operator to specify a VPrP. For instance, the provider may offer templates for video conferencing, audio conferencing, Gold Service, Silver Service, etc. Using these templates the operator can select and provision a VPrP that specifies the quality of service attributes for this VPrP. Elements that can be specified for a VPrP include attributes such as packet delay and packet loss. Characteristics of traffic that enters the VPrP at its access point to the provider network can be also specified with attributes such as maximum rate and burst rate. The following is an example of a possible scenario: The provider prepares a template with operator-specified attributes, provider-specified attributes, and unspecified attributes, one for each QoS level. The provider generates for the enterprise network a list of all the current sites and their access points to the provider network. Enterprise operator logs into connectivity manager after being authenticated and authorised by the Framework service. Operator gets the list of the sites and service access points of the enterprise Virtual Private Network (VPN) already provided to the enterprise by the provider. Enterprise operator retrieves the set of templates available to the enterprise (as supported by the SLA), selects one, and requests a template for constructing a new VPrP based upon the selected QoS. Enterprise operator completes the VPrP template: i.e. selects a value for delay, loss, jitter and excess traffic treatment action, enters the SLA ID against which the template could be validated, selects endpoints, load parameters and traffic flow direction, and selects the time requirements desired. The enterprise operator can choose or modify those attributes that are operator-specified attributes in the template. Provider-specified attributes cannot be modified and are inherently part of the service. Enterprise operator submits the completed VPrP template for validation by the CM service. Operator creates a new VPrP with pending-status that holds these selections. The provider responds after validating the requests, which may be an approval or a denial (e.g. the requested service is not available at this access point, or at the specified time). If the provider approves service, the operator may send packets marked with the templates DiffServ Codepoint, which identifies together with the endpoints the VPrP that carries these packets.

11 10 TS V9.0.0 ( ) Some additional clarification points: A VPrN is associated with a single network provider. A VPrP defines QoS parameters for traffic flowing through this provider network, between two specified enterprise endpoints, optionally during specified date/time period(s). The enterprise operator may be (provider's choice) constrained to selecting QoS parameter values from a predefined set of values, and selecting endpoints from a predefined set of enterprise sites; where these sets were negotiated off-line between the enterprise and the network provider and possibly documented in a Service Level Agreement (SLA). The CM service validates each VPrP request submitted by the enterprise operator. The validation process is not specified here. Validation against the SLA is an example of such possible validation. If the CM service accepts the VPrP request, it adds it to the VPrN. The DiffServ Codepoint provided by the enterprise operator is then used by the enterprise for marking all packets belonging to any traffic flow associated with the VPrP. The following is a summary of interfaces and methods supported by connectivity manager. The syntax method (interface) is used for this description. There are Passive CM interface functions (CM1, CM2, CM4) that are used to retrieve information (read) relative to VPN, VPrN, and QoS templates provided by the service provider, and active (CM3) functions (read/write) used to provision new services. CM1: Retrieve information on a Virtual Private Network, its sites and their service access points: getenterprisenetwork(ipconnectivitymanager) getsitelist(ipeterprisenetwork) getsite(ipeterprisenetwork) getsaplist(ipenterprisenetworksite) getsiteid(ipenterprisenetworksite) getsitelocation(ipenterprisenetworksite) getsitedescription(ipenterprisenetworksite) getsapipsubnet(ipenterprisenetworksite) getsiteipsubnet(ipenterprisenetworksite) CM2: Retrieve QoS services offered by provider, stored in QoS templates: getqosmenu(ipconnectivitymanager) gettemplatelist(ipqosmenu) gettemplate(ipqosmenu) gettemplatetype(ipqostemplate) getdescription(ipqostemplate) getpipeqosinfo(ipqostemplate) getvalidityinfo(ipqostemplate) getprovisionedqosinfo(ipqostemplate) getdscodepoint(ipqostemplate)

12 11 TS V9.0.0 ( ) CM3: Set up a new Virtual Provisioned Pipe: createvprp(ipvprn) deletevprp(ipvprn) setslaid(ipqostemplate) setpipeqosinfo(ipqostemplate) setvalidityinfo(ipqostemplate) setprovisionedqosinfo(ipqostemplate) CM4: Retrieve information on a Virtual Provisioned Network and its Virtual Provisioned Pipes: getvprn(ipeterprisenetwork) getvprplist(ipvprn) getvprp(ipvprn) getvprpid(ipvprp) getslaid(ipvprp) getstatus(ipvprp) getprovisionedqosinfo(ipvprp) getpipeqosinfo(ipvprp) getdscodepoint(ipvprp) Two typical scenarios: 1) To set up a new VPrP: The enterprise operator retrieves information regarding enterprise's existing VPN (sites and SAPs), using as needed the methods listed in CM1 above. Enterprise operator retrieves information on provider's offered QoS services, using methods listed in CM2 above as needed. Enterprise operator submits a request to set up a new VPrP, using methods listed in CM3 above as needed. Enterprise operator checks the status of the request using the methods listed in CM4 above as needed. If the request was approved by the network provider, the VPrP is put in an active mode, and packets that are marked in the enterprise network with appropriate marking in their packet header will travel the provider's network through the new Virtual Provisioned Pipe that supports the requested QoS levels. 2) Retrieve information on current enterprise network services delivered to the enterprise by the provider network: Enterprise operator retrieves information on current QoS services delivered to the enterprise network using CM4 methods listed above as needed. Enterprise operator checks if the provider offers new QoS services using CM2 listed above as needed. The following clauses describe each aspect of the Connectivity Manager Service Capability Feature (SCF).

13 12 TS V9.0.0 ( ) 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 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.

14 13 TS V9.0.0 ( ) 5 Sequence Diagrams 5.1 Operator Selects Service Components and creates a new VPrP The following sequence diagram shows how an enterprise operator client collects the information required to select a service, and then selects the service parameters, and finally submits it to the connectivity manager. OperatorClient : IpConnectivityManager : IpQoSMenu : IpQoSTemplate : IpVPrN 1: getqosmenu( ) 2: gettemplatelist( ) 3: gettemplate( ) 4: getpipeqosinfo( ) 5: setpipeqosinfo( ) 6: getprovisionedqosinfo( ) 7: setprovisionedqosinfo( ) 8: getvalidityinfo( ) 9: setvalidityinfo( ) 10: createvprp( ) 5.2 Operator Browses Virtual Provisioned Pipe The following shows an enterprise operator client browses and collect information pertinent to an existing virtual provisioned pipe, including all the QoS parameters that have been set for this pipe.

15 14 TS V9.0.0 ( ) OperatorClient : IpConnectivityManager : IpEnterpriseNetwork : IpVPrN : IpVPrP 1: getenterprisenetwork( ) 2: getvprn( ) 3: getvprplist( ) 4: getvprp( ) 5: getvprpid( ) 6: getslaid( ) 7: getprovisionedqosinfo( ) 8: getvalidityinfo( ) 9: getpipeqosinfo( ) 10: getdscodepoint( ) 11: getstatus( )

16 15 TS V9.0.0 ( ) 5.3 Operator Browses SAPs and Sites The following sequence diagram shows how an enterprise operator browses service access points and sites to retrieve information regarding a site and its SAP(s). : OperatorClient IpConnectivityManager 1: getenterprisenetwork( ) : IpEnterpriseNetwork : IpEnterpriseNetworkSite 2: getsitelist( ) 3: getsite( ) 4: getsaplist( ) 5: getsiteid( ) 6: getsitelocation( ) 7: getsitedescription( ) 8: getsapipsubnet( ) 9: getipsubnet( )

17 16 TS V9.0.0 ( ) 6 Class Diagrams The class diagram below shows the connectivity manager interfaces. The connectivity manager interface is the entry point to this service. From this interface a reference to the enterprise network and to the Quality of Service (QoS) menu interfaces can be retrieved. The QoS menu interface provides a list of templates, each of which specifies the QoS service parameters that are offered by the service provider. The service is composed of components that are associated with a Provisioned QoS. The template interface is used to specify the service parameters that are offered by the service provider, and also, for temporary storage of parameters that the operator selects. The enterprise network interface is associated with two components: enterprise network sites, and the Virtual Provisioned Network that has been already provisioned in the provider network. The Virtual Provisioned Network interface contains references to all the Virtual Provisioned Pipes (VPrPs) already established. The QoS Menu contains references to all the QoS templates offered by the provider. Each template specifies the QoS parameters that can be set in order to create a new VPrP. Once the operator selects the QoS parameters provided in the QoS template, and submits the request to create a new VPrP, the provider validates the information submitted and if the request is approved, the new VPrP is set to an active mode. <<Interface>> IpConnectivityManager (from cm) <<Interface>> IpQoSMenu (from cm) <<Interface>> IpEnterpriseNetwork (from cm) <<Interface>> IpVPrN (f ro m cm ) n <<Interface>> IpQoSTemplate (from cm) 1 0..n <<Interface>> IpVPrP (f ro m cm ) 1..n <<Interface>> IpEnterpriseNetworkSite (from cm) Figure : Connectivity Management High level class diagram The connectivity manager class is associated with the QoS menu class and the enterprise network class as shown in the figure below. From the CM class the QoS Menu and Enterprise Network reference can be retrieved. The QoS menu provides a method (gettemplatelist()), to get the list of all the QoS offered services, each of which is stored as a template (e.g. Gold template, Silver template). The QoS menu provides a method (gettemplate()) that instantiates a temporary template to retrieve the default parameters for a specific template, and store the parameters selected by the operator for a new service (VPrP). The Enterprise Network class is used to retrieve the list of sites that the operator has established for a Virtual Private Network (VPN) service with the service provider, and to get a reference to a specific

18 17 TS V9.0.0 ( ) site. This class also provides a reference to the Virtual Provisioned Network class that holds the information regarding the already established QoS network with the provider. <<Interface>> IpConnectivityManager (f ro m c m) getqosmenu() getenterprisenetwork() 1 1 <<Interface>> IpQoSMenu (from cm) 1 1 <<Interface>> IpEnterpriseNetwork (from cm) gettemplate() gettemplatelist() getsitelist() getvprn() getsite() Figure : QoS Menu and Enterprise Network class diagram The figure below shows QoS templates class that is used to retrieve the QoS parameters offered by the provider and select the parameters for a new VPrP and store them in this template. Most of these parameters are tagged using the TPNameDescrpTag class to indicate whether the parameter is set by the provider and cannot be changed by the operator, or is a parameter that can be set by the operator. A third option associated with each QoS parameter is the unspecified tag, that means that the operator does not offer this parameter as an option for this template. All the QoS parameters that constitute a VPrP are stored in the template class, including the source and destination site/sap, the direction of the traffic, the provisioned QoS parameters, such as packet loss, delay, jitter, the Pipe QoS parameters, such as load conditioning.

19 18 TS V9.0.0 ( ) <<Interf ace>> IpQoSMenu (from cm) gettemplate() gettemplatelist() 1 <<CORBASt ruc t>> TpPipeQoSInf o (from cm_data) 0..n <<Interf ace>> IpQoSTem plate (from cm) gettemplatety pe() getdescription() setslaid() getpipeqosinf o() setpipeqosinf o() getvalidity Inf o() setvalidity Inf o() setprov isionedqosinf o() getprov isionedqosinf o() getdscodepoint() <<CORBAStruct>> TpProv isionedqosinf o (from cm_data) <<CORBAStruct>> TpValidity Inf o (from cm_data) <<CORBAStruct >> TpDsCodepoint (from cm_data) Figure : QoS Template class diagram The figure below shows the data types that specify the Provisioned QoS information: as packet loss, packet delay, packet jitter. All use the Name Description Tag class to indicate whether each parameter is specified by the provider, the operator, or unspecified for this template. The value used for each of individual parameters is either an integer, or a string. For the excess load condition, one of the four actions can be applied: drop, transmit, reshape, and remark. The DS Codepoint used by this template is also shown below.

20 19 TS V9.0.0 ( ) <<CORBAStruct>> TpJitterDescriptor ( from cm_data) <<CORBAStruct>> TpProv isionedqosinf o (from cm_data) M M TpNameDescrpTagM M M M <<CORBAStruct>> TpDelay Descriptor (from cm_data) M M <<CORBAEnum>> TpTagValue (from cm_data) OPERATOR_SPECIFIED PROVIDER_SPECIFIED UNSPECIFIED <<CORBAStruct>> TpNameDescrpTagExcessLoadAction (from cm_data) M <<CORBASt ruct>> TpLossDescriptor (from cm_data) <<CORBAStruct>> TpNameDescrpTagInt (from cm_data) <<CORBAStruct>> TpNameDes crptagstring (from cm_data) +v alue <<CORBAEnum>> TpAction (from cm_data) DROP TRANSMIT RESHAPE REMARK Figure : Provisioned QoS Data Types Classes The figure below shows the Pipe QoS information data type classes. They include the load parameters, and the endpoint termination of the pipe. The individual values are integer, and for the directional type, either uni-directional traffic or bidirectional traffic is specified for the Pipe.

21 20 TS V9.0.0 ( ) <<CORBAStruct>> TpLoadDescriptor (from cm_data) <<CORBAStruct>> TpPipeQoSInfo (from cm_data) <<CORBAEnum>> TpTagValue (from cm_data) OPERATOR_SPECIFIED PROVIDER_SPECIFIED UNSPECIFIED M M +serviceorigin +servicedestination <<CORBAS truct>> TpEndpoint (from cm_data) M TpNameDescrpTag M M +type <<CORBAE num>> TpSiteOrSap SITE SAP (from cm_data) <<CORBAStruct>> TpNameDescrpTagInt (from cm_data) M M <<CORBAEnum>> TpTrafficDirection (from cm_data) UNIDIRECTIONAL BIDIRECTIONAL +va lue <<CORBAStruct>> TpNameDescrpTagString (from cm_data) <<CORBAStruct>> TpNameDescrpTagDir (from cm_data) Figure : Pipe QoS Data Types The figure below shows the classes that store information regarding the existing services already established between the provider and the enterprise. This includes the Virtual Private Network that is contained in the Enterprise Network Site class, and the Virtual Provisioned Network Class, and the associated Virtual Provisioned Pipe class. Also shown here is the information included for Pipe QoS, and the IP subnet information stored in these classes. However, the class that shows the information collected for Provisioned QoS is not shown here but in another class diagram below.

22 21 TS V9.0.0 ( ) <<Interface>> IpEnterpriseNetwork (f rom cm) 1 getsitelist() getvprn() getsite() 1 <<Interface>> IpVPrN (f rom cm) 1 1..n <<Interface>> IpEnterpriseNetworkSite (f rom cm) getvprplist() getvprp() createvprp() deletevprp() 1 0..n <<Interface>> IpVPrP (f rom cm) getvprpid() getslaid() getstatus() getprovisionedqosinfo() getvalidityinfo() getpipeqosinfo() getdscodepoint() <<CORBAStruct>> TpDsCo depoint (f rom cm _data) <<CORBAEnum>> TpVprpStatus (f r om c m_da t a) ACTIVE PENDING DISALLOWED <<CORBAStruct>> TpPipeQoSInfo <<CORBAStruct>> TpProvisionedQoSInfo (f rom cm_data) <<CORBAStruct>> TpValidityInfo (f rom cm_data) getsaplist() getsiteid() getsitelocation() getsitedescription() getipsubnet() getsapipsubnet() +IPVersi onsupport <<CORBAEnum>> TpIPVersion (f rom cm_data) VERSION_UNKNOWN VERSION_IPV4 VERSION_IPV6 <<CORBAStruct>> TpIPSubnet (f rom cm_data) +addresst ype <<CORBAEnum>> TpIPv4AddType (f rom cm _data) IPV4_ADD_CLASS_A IPV4_ADD_CLASS_B IPV4_ADD_CLASS_C IPV4_ADD_CLASS_D IPV4_ADD_CLASS_E Figure : Existing VPN and VPrN services class diagram The figure below shows the validity data type classes. They specify a window between two points in time, and repetitions events during a day, which days of the week, and which month of the year. They can be specified by the provider, to limit the service to certain time periods, or by the operator. The individual values are shown as subclasses to the Name Description Tag class.

23 22 TS V9.0.0 ( ) <<CORBAStruct>> TpNameDescrpTagDateTime (from cm_data) <<CORBAStruct>> TpValidityInfo (from cm _data) M <<CORBAStruct>> TpNameDescrpTagTimeOfDay (from cm_data) M M TpNameDescrpTag M M M M <<CORBAStruct>> TpNameDescrpTagTimePeriod (from cm_data) <<CORBAStruct>> TpNameDescrpTagDayOfWeek (from cm_data) <<CORBAStruct>> TpNameDescrpTagMonth (from cm_data) Figure : Validity Data Type Classes 7 The Service Interface Specifications 7.1 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 Interface Class 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<name>. The callback interfaces to the applications are denoted by classes with name IpApp<name>. For the interfaces between a Service and the Framework, the Service interfaces are typically denoted by classes with name IpSvc<name>, while the Framework interfaces are denoted by classes with name IpFw<name> Method descriptions Each method (API method 'call') is described. Both synchronous and asynchronous methods are used in the API. Asynchronous methods are identified by a 'Req' suffix for a method request, and, if applicable, are served by asynchronous methods identified by either a 'Res' or 'Err' suffix for method results and errors, respectively. To handle responses and reports, the application or service developer must implement the relevant IpApp<name> or IpSvc<name> interfaces to provide the callback mechanism.

24 23 TS V9.0.0 ( ) Parameter descriptions Each method parameter and its possible values are described. described as 'in' represent those that must have a value when the method is called. Those described as 'out' are those that contain the return result of the method when the method returns State Model If relevant, a state model is shown to illustrate the states of the objects that implement the described interface. 7.2 Base 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. <<Interface>> IpInterface 7.3 Service Interfaces Overview 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 'Service Interface'. The corresponding interfaces that must be implemented by the application (e.g. for API callbacks) are denoted as 'Application Interface'. 7.4 Generic Service Interface Interface Class IpService Inherits from: IpInterface; All service interfaces inherit from the following interface. <<Interface>> IpService setcallback (appinterface : in IpInterfaceRef) : void setcallbackwithsessionid (appinterface : in IpInterfaceRef, sessionid : in TpSessionID) : void

25 24 TS V9.0.0 ( ) 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'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. appinterface : in IpInterfaceRef Specifies a reference to the application interface, which is used for callbacks. sessionid : in TpSessionID Specifies the session for which the service can invoke the application's callback interface. TpCommonExceptions, P_INVALID_SESSION_ID, P_INVALID_INTERFACE_TYPE 8 Connectivity Manager Interface Classes 8.1 Interface Class IpConnectivityManager Inherits from: IpService. The service Connectivity Manager Interface is the entry point to the Connectivity Manager service. After the enterprise operator client is authenticated and authorised, the client application discovers the Connectivity Manager interface, then the operator can use this interface to step through the process of provisioning a new VPrP. This interface has two methods, one to get the handle to the menu of QoS services offered by the provider, and the other one is a handle to the enterprise network interface that holds information about current services that the provider network delivers to the enterprise network.

26 25 TS V9.0.0 ( ) <<Interface>> IpConnectivityManager getqosmenu () : IpInterfaceRef getenterprisenetwork () : IpInterfaceRef Method getqosmenu() A client uses this method to get a reference to the QoS menu interface. Returns menuref : This parameter is a reference to the QoS menu interface. If no menu is found, P_UNKNOWN_MENU exception is raised. No were identified for this method. Returns IpInterfaceRef TpCommonExceptions, P_UNKNOWN_MENU Method getenterprisenetwork() This method is used to get a handle to the enterprise network interface, which holds information regarding network services that are already provisioned for the enterprise network in the provider network. Returns enterprisenetworkref : This parameter is a reference to the enterprise network interface. If enterprise network is not found, P_UNKNOWN_ENTERPRISE_NETWORK exception is raised. No were identified for this method. Returns IpInterfaceRef TpCommonExceptions, P_UNKNOWN_ENTERPRISE_NETWORK 8.2 Interface Class IpEnterpriseNetwork Inherits from: IpService.

27 26 TS V9.0.0 ( ) This interface stores enterprise network information maintained by the provider as it relates to the virtual private network service and the virtual provisioned network service that the enterprise had already established with the service provider network. The enterprise operator can only retrieve but not change the information stored with this interface. The methods of this interface enable the enterprise operator to obtain the handle to the interface that holds information regarding an existing VPrN, to list the sites connected to the VPN, and get the handle to a specific site interface that store information about the site. <<Interface>> IpEnterpriseNetwork getsitelist () : TpStringList getvprn () : IpInterfaceRef getsite (siteid : in TpString) : IpInterfaceRef Method getsitelist() This method is used to get the list of enterprise network site IDs. These IDs identify the sites that are inter-connected through the provider network. These IDs were set when the VPN was provisioned in the provider network in the provider network. Returns sitelist : This parameter lists the site IDs (e.g., research, marketing, Middletown Building D5, London) of the enterprise network that are serviced by the provider network. If no site is found, then a P_UNKNOWN_SITES exception is raised. No were identified for this method. Returns TpStringList TpCommonExceptions, P_UNKNOWN_SITES Method getvprn() This method is used to get a handle to the interface that holds information regarding a previously provisioned Virtual Provisioned Network (VPrN). Returns vprnref : This parameter is a handle to the VPrN interface that holds information about previously provisioned VPrN. If no VPrN is found for this enterprise network, then a P_UNKNOWN_VPRN exception is raised. No were identified for this method.

28 27 TS V9.0.0 ( ) Returns IpInterfaceRef TpCommonExceptions, P_UNKNOWN_VPRN Method getsite() This method is used to get a handle to an interface that holds information about a specific site. Returns siteref : This parameter is a reference to the site interface. siteid : in TpString This parameter is the ID given to a particular site. The ID is not assigned via OSA APIs, but previously when a new VPN (or VLL) is established for the enterprise on the provider network. These ID are typically names that refer to objects that are meaningful in the context of the enterprise network, such as: Marketing, New York, or Bulling 4. This site ID can be used as an endpoint of a provisioned virtual provisioned pipe (VPrP). - If the string representation of the siteid does not obey the rules for site identification, then a P_ILLEGAL_SITE_ID exception is raised. - If the site ID representation is legal but there is no site with this ID, then P_UNKNOWN_SITE_ID exception is raised. Returns IpInterfaceRef TpCommonExceptions, P_ILLEGAL_SITE_ID, P_UNKNOWN_SITE_ID 8.3 Interface Class IpEnterpriseNetworkSite Inherits from: IpEnterpriseNetwork. This interface stores enterprise network site information maintained by the provider.

29 28 TS V9.0.0 ( ) <<Interface>> IpEnterpriseNetworkSite getsaplist () : TpStringList getsiteid () : TpString getsitelocation () : TpString getsitedescription () : TpString getipsubnet () : TpIPSubnet getsapipsubnet (sapid : in TpString) : TpIPSubnet Method getsaplist() This method is used to get the list of SAP IDs of the enterprise VPN (i.e. on the provider network) that have previously been established for this site with the provider network. Returns saplist : This parameter is a list of SAP IDs. This SAP ID can be used as an endpoint of a provisioned virtual provisioned pipe (VPrP). If no SAPs are found for this site, then P_UNKNOWN_SAPS exception is raised. No were identified for this method. Returns TpStringList TpCommonExceptions, P_UNKNOWN_SAPS Method getsiteid() This method is used to get the site ID for this site. Returns siteid : This parameter holds the value for the site ID. If no site ID is found for this site, then P_UNKNOWN_SITE_ID exception is raised. No were identified for this method.

30 29 TS V9.0.0 ( ) Returns TpString TpCommonExceptions, P_UNKNOWN_SITE_ID Method getsitelocation() This method is used to get the site location. Returns sitelocation : This parameter holds the value for the site location. If no site location is found for this site, then P_UNKNOWN_SITE_LOCATION exception is raised. No were identified for this method. Returns TpString TpCommonExceptions, P_UNKNOWN_SITE_LOCATION Method getsitedescription() This method is used to get the description associated with this site. Returns sitedescription : This parameter is a string that holds the site description. If no description is found for this site, then P_UNKNOWN_SITE_DESCRIPTION exception is raised. No were identified for this method. Returns TpString TpCommonExceptions, P_UNKNOWN_SITE_DESCRIPTION Method getipsubnet() This method is used to get IP subnet information for this site. Returns ipsubnet : This parameter lists the subnet information.

31 30 TS V9.0.0 ( ) If no IP Subnet information is found for this site, then a P_UNKNOWN_IPSUBNET exception is raised. No were identified for this method. Returns TpIPSubnet TpCommonExceptions, P_UNKNOWN_IPSUBNET Method getsapipsubnet() This method is used to get the IP address of the SAP on the enterprise network. Returns ipsubnet : This parameter holds the IP address information for the SAP. This TpIPSubnet data type follows the DMTF CIM specification for IP sub-net. sapid : in TpString This parameter holds the IP address information for the SAP. - If the string representation of the sapid does not obey the rules for site identification, then a P_ILLEGAL_SITE_ID exception is raised. - If the site ID representation is legal but there is no site with this ID, then P_UNKNOWN_SAP exception is raised. - If no IP Subnet information is found for this SAP, then a P_UNKNOWN_IPSUBNET exception is raised. Returns TpIPSubnet TpCommonExceptions, P_ILLEGAL_SITE_ID, P_UNKNOWN_SAP, P_UNKNOWN_IPSUBNET 8.4 Interface Class IpQoSMenu Inherits from: IpService. This interface holds the QoS menu offered by the provider. Each QoS service offered (e.g. Gold, Silver) is specified in a separate template. The template specifies the parameters and their default values from which the operator may choose to create a VPrP. When the operator asks for a specific template from the list of templates (gettemplate method), a temporary template interface is created. This temporary template interface holds all the parameters (e.g. all the Gold parameters) and their default values offered by the provider for this template.

32 31 TS V9.0.0 ( ) <<Interface>> IpQoSMenu gettemplate (templatetype : in TpString) : IpInterfaceRef gettemplatelist () : TpStringList Method gettemplate() This method is used to get an interface reference to a specific template. The provider creates a temporary copy of the original template that contains all the QoS parameters for this template (e.g. Gold). Returns templateref : This parameter contains a reference to the template interface. Note that if the reference to this temporary template is lost, there is no way to recall it. To create a new temporary template this method has to be applied again, however, any values that were set in the old temporary template are lost. templatetype : in TpString This parameter contains template type. Returns IpInterfaceRef TpCommonExceptions Method gettemplatelist() This method is used to get a list of templates, each of which specifies a QoS service, such as Gold or Silver. Returns templatelist : This parameter contains a list of QoS service templates IDs. If no templates are found, then a P_UNKNOWN_TEMPLATES exception is raised. No were identified for this method. Returns TpStringList TpCommonExceptions, P_UNKNOWN_TEMPLATES

33 32 TS V9.0.0 ( ) 8.5 Interface Class IpQoSTemplate Inherits from: IpService. This interface provides access to a specific QoS template, such as Gold, offered by the provider. This interface provides get methods to discover the QoS service details, and set methods to set the requested values for a new VPrP. The template specifies the QoS parameters and their default values. Each service template parameter is tagged by the service provider to indicate one of the following: - Provider specified: the value cannot be modified for this template. - Enterprise operator specified: operator may change the default value set by the provider. The default value can be blank to indicate that there is no default value for this parameter, and the user can change it according to advice typically given by the description parameters. - Unspecified: the parameter is not used for this template, and the Enterprise operator cannot change it. For example, maximum delay for a Gold template may be provider specified, while maximum bandwidth may be Enterprise operator specified, meaning that its values can be changed by the setprovisionedqosinfo, or by setpipeqosinfo methods. Guidance how to change the default values may be provided by the template description parameter. The tag of a parameter cannot be changed by any set method of this interface, i.e., if a parameter is tagged unspecified, or provider specified, Enterprise operator cannot override the value of this tag to say operator specified. This template is a temporary interface created as a copy of the original template that stores all the template parameters. The temporary interface is created with the gettemplate method of IpQoSMenu interface. The values passed to this template interface by the set methods replace (if permitted by the tags) the default values stored in this template interface, i.e. a get following a set method to this template interface will fetch the new values set by the Enterprise operator. Once a new VPrP is created by the create method in IpVPrN, the temporary interface might not be accessible anymore. <<Interface>> IpQoSTemplate gettemplatetype () : TpString getdescription () : TpString setslaid (slaid : in TpString) : void getpipeqosinfo () : TpPipeQoSInfo setpipeqosinfo (pipeqosinfo : in TpPipeQoSInfo) : void getvalidityinfo () : TpValidityInfo setvalidityinfo (validityinfo : in TpValidityInfo) : void setprovisionedqosinfo (provisionedqosinfo : in TpProvisionedQoSInfo) : void getprovisionedqosinfo () : TpProvisionedQoSInfo getdscodepoint () : TpDsCodepoint Method gettemplatetype() This method is used to get the template type, e.g. Gold. Returns templatetype : This parameter contains the template type. If template type is not found, then P_UNKNOWN_TEMPLATE_TYPE exception is raised.