ETSI ES 202 504-9 V1.1.1 (2008-05)
Open Service Access (OSA); Parlay X Web Services; Part 9: Terminal Location (Parlay X 3)
Open Service Access (OSA); Parlay X Web Services; Part 9: Terminal Location (Parlay X 3)
DES/TISPAN-01034-9-OSA
Odprti dostop do storitve (OSA) - Spletne storitve Parlay X - 9. del: Lokacija terminala (Parlay X 3)
General Information
Standards Content (Sample)
Final draft ETSI ES 202 504-9 V1.1.1 (2008-02)
ETSI Standard
Open Service Access (OSA);
Parlay X Web Services;
Part 9: Terminal Location
(Parlay X 3)
�
2 Final draft ETSI ES 202 504-9 V1.1.1 (2008-02)
Reference
DES/TISPAN-01034-9-OSA
Keywords
API, OSA, service
ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE
Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16
Siret N° 348 623 562 00017 - 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:
http://www.etsi.org
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 ETSI printers of the PDF version kept on a specific network drive
within ETSI 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 ETSI documents is available at
http://portal.etsi.org/tb/status/status.asp
If you find errors in the present document, please send your comment to one of the following services:
http://portal.etsi.org/chaircor/ETSI_support.asp
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 2008.
© The Parlay Group 2008.
All rights reserved.
TM TM TM TM
DECT , PLUGTESTS , UMTS , TIPHON , the TIPHON logo and the ETSI logo are Trade Marks of ETSI registered
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.
ETSI
3 Final draft ETSI ES 202 504-9 V1.1.1 (2008-02)
Contents
Intellectual Property Rights.5
Foreword.5
1 Scope.7
2 References.7
2.1 Normative references.7
3 Definitions and abbreviations.8
3.1 Definitions.8
3.2 Abbreviations.8
4 Detailed service description .8
5 Namespaces.8
6 Sequence diagrams.9
6.1 Terminal location query .9
6.2 Terminal location group query .10
6.3 Terminal location notification .11
6.4 Terminal location notification with check immediate .12
6.5 Terminal location periodic notification .13
7 XML Schema data type definition .14
7.1 Latitude and Longitude values .14
7.2 Accuracy values.14
7.3 EnteringLeavingCriteria enumeration.14
7.4 LocationInfo structure.15
7.5 RetrievalStatus enumeration.15
7.6 LocationData structure.15
7.7 DelayTolerance enumeration.16
8 Web Service interface definition.16
8.1 Interface: TerminalLocation.16
8.1.1 Operation: getLocation.16
8.1.1.1 Input message: getLocationRequest.16
8.1.1.2 Output message: getLocationResponse.16
8.1.1.3 Referenced faults.17
8.1.2 Operation: getTerminalDistance.17
8.1.2.1 Input message: getTerminalDistanceRequest .17
8.1.2.2 Output message: getTerminalDistanceResponse.17
8.1.2.3 Referenced faults.17
8.1.3 Operation: getLocationForGroup.18
8.1.3.1 Input message: getLocationForGroupRequest .18
8.1.3.2 Output message: getLocationForGroupResponse.18
8.1.3.3 Referenced faults.18
8.2 Interface: TerminalLocationNotificationManager.19
8.2.1 Operation: startGeographicalNotification.19
8.2.1.1 Input message: startGeographicalNotificationRequest .19
8.2.1.2 Output message: startGeographicalNotificationResponse.20
8.2.1.3 Referenced faults.20
8.2.2 Operation: startPeriodicNotification.20
8.2.2.1 Input message: startPeriodicNotificationRequest.21
8.2.2.2 Output message: startPeriodicNotificationResponse .21
8.2.2.3 Referenced faults.21
8.2.3 Operation: endNotification.21
8.2.3.1 Input message: endNotificationRequest.22
8.2.3.2 Output message: endNotificationResponse.22
8.2.3.3 Referenced faults.22
ETSI
4 Final draft ETSI ES 202 504-9 V1.1.1 (2008-02)
8.3 Interface: TerminalLocationNotification.22
8.3.1 Operation: locationNotification.22
8.3.1.1 Input message: locationNotificationRequest.22
8.3.1.2 Output message: locationNotificationResponse.22
8.3.1.3 Referenced faults.22
8.3.2 Operation: locationError.23
8.3.2.1 Input message: locationErrorRequest.23
8.3.2.2 Output message: locationErrorResponse.23
8.3.2.3 Referenced faults.23
8.3.3 Operation: locationEnd.23
8.3.3.1 Input message: locationEndRequest.23
8.3.3.2 Output message: locationEndResponse.23
8.3.3.3 Referenced faults.23
9 Fault definitions.24
9.1 ServiceException.24
9.1.1 SVC0200: Accuracy out of limit .24
9.2 PolicyException.24
9.2.1 POL0230: Requested accuracy not supported .24
9.2.2 POL0231: Geographic notification not available .24
9.2.3 POL0232: Periodic notification not available.24
10 Service policies .25
Annex A (normative): WSDL for Terminal Location .26
Annex B (informative): Bibliography.27
History .28
ETSI
5 Final draft ETSI ES 202 504-9 V1.1.1 (2008-02)
Intellectual Property Rights
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: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in
respect of ETSI standards", 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.
Foreword
This ETSI Standard (ES) has been produced by ETSI Technical Committee Telecommunications and Internet
converged Services and Protocols for Advanced Networking (TISPAN), and is now submitted for the ETSI standards
Membership Approval Procedure.
The present document is part 9 of a multi-part deliverable covering Open Service Access (OSA); Parlay X 3 Web
Services, as identified below:
Part 1: "Common";
Part 2: "Third Party Call";
Part 3: "Call Notification";
Part 4: "Short Messaging";
Part 5: "Multimedia Messaging";
Part 6: "Payment";
Part 7: "Account Management";
Part 8: "Terminal Status";
Part 9: "Terminal Location";
Part 10: "Call Handling";
Part 11: "Audio Call";
Part 12: "Multimedia Conference";
Part 13: "Address List Management";
Part 14: "Presence";
Part 15: "Message Broadcast";
Part 16: "Geocoding";
Part 17: "Application-driven Quality of Service (QoS)";
Part 18: "Device Capabilities and Configuration";
Part 19: "Multimedia Streaming Control";
Part 20: "Multimedia Multicast Session Management".
ETSI
6 Final draft ETSI ES 202 504-9 V1.1.1 (2008-02)
The present document has been defined jointly between ETSI, The Parlay Group (http://www.parlay.org) and the 3GPP.
The present document forms part of the Parlay X 3.0 set of specifications.
The present document is equivalent to 3GPP TS 29.199-09 V7.2.2 (Release 7).
ETSI
7 Final draft ETSI ES 202 504-9 V1.1.1 (2008-02)
1 Scope
The present document is part 9 of the Stage 3 Parlay X 3 Web Services specification for Open Service Access (OSA).
The OSA specifications define an architecture that enables application developers to make use of network functionality
through an open standardized interface, i.e. the OSA APIs.
The present document specifies the Terminal Location Web Service. The following are defined here:
• Name spaces.
• Sequence diagrams.
• Data definitions.
• Interface specification plus detailed method descriptions.
• Fault definitions.
• Service Policies.
• WSDL Description of the interfaces.
2 References
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific.
• For a specific reference, subsequent revisions do not apply.
• Non-specific reference may be made only to a complete document or a part thereof and only in the following
cases:
- if it is accepted that it will be possible to use all future changes of the referenced document for the
purposes of the referring document;
- for informative references.
Referenced documents which are not found to be publicly available in the expected location might be found at
http://docbox.etsi.org/Reference.
For online referenced documents, information sufficient to identify and locate the source shall be provided. Preferably,
the primary source of the referenced document should be cited, in order to ensure traceability. Furthermore, the
reference should, as far as possible, remain valid for the expected life of the document. The reference shall include the
method of access to the referenced document and the full network address, with the same punctuation and use of upper
case and lower case letters.
NOTE: While any hyperlinks included in this clause were valid at the time of publication ETSI cannot guarantee
their long term validity.
2.1 Normative references
The following referenced documents are indispensable for the application of the present document. For dated
references, only the edition cited applies. For non-specific references, the latest edition of the referenced document
(including any amendments) applies.
[1] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes".
NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.
ETSI
8 Final draft ETSI ES 202 504-9 V1.1.1 (2008-02)
[2] ETSI ES 202 504-1: "Open Service Access (OSA); Parlay X Web Services; Part 1: Common
(Parlay X 3)".
[3] ISO 6709: "Standard representation of latitude, longitude and altitude for geographic point
locations".
3 Definitions and abbreviations
3.1 Definitions
For the purposes of the present document, the terms and definitions given in ES 202 504-1 [2] apply.
3.2 Abbreviations
For the purposes of the present document, the abbreviations given in ES 202 504-1 [2] apply.
4 Detailed service description
Terminal Location provides access to the location of a terminal through:
• Request for the location of a terminal.
• Request for the location of a group of terminals.
• Notification of a change in the location of a terminal.
• Notification of terminal location on a periodic basis.
• Location is expressed through a latitude, longitude, altitude and accuracy.
When a request for a group of terminals is made, the response may contain a full or partial set of results. This allows the
service to provide results based on a number of criteria including number of terminals for which the request is made and
amount of time required to retrieve the information. This allows the requester to initiate additional requests for those
terminals for which information was not provided.
5 Namespaces
The TerminalLocation interface uses the namespace:
http://www.csapi.org/wsdl/parlayx/terminal_location/v3_1
The TerminalLocationNotificationManager interface uses the namespace:
http://www.csapi.org/wsdl/parlayx/terminal_location/notification_manager/v3_1
The TerminalLocationNotification interface uses the namespace:
http://www.csapi.org/wsdl/parlayx/terminal_location/notification/v3_0
The data types are defined in the namespace:
http://www.csapi.org/schema/parlayx/terminal_location/v3_0
The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in
XML Schema [1]. The use of the name 'xsd' is not semantically significant.
ETSI
9 Final draft ETSI ES 202 504-9 V1.1.1 (2008-02)
6 Sequence diagrams
6.1 Terminal location query
Pattern: Request / Response.
For an application to determine the location of a terminal device, it provides a terminal device address and desired
accuracy, and receives the location for the device requested.
: Application : Terminal Location
Web Service
Request terminal location
Retrieve location
Location data
Figure 1
ETSI
10 Final draft ETSI ES 202 504-9 V1.1.1 (2008-02)
6.2 Terminal location group query
Pattern: Request / Response.
When an application requires the locations of a set of terminal devices, it may provide an array of terminal device
addresses, including network managed group addresses, and receive the location data for the set of devices requested.
: Application : Terminal Location
Web Service
Request terminal location for group
Process groups
Retrieve locations
Location data
Figure 2
ETSI
11 Final draft ETSI ES 202 504-9 V1.1.1 (2008-02)
6.3 Terminal location notification
Pattern: Application Correlated Multiple Notification.
An application can be notified of a terminal device entering or leaving a geographical area. When a matching event
occurs; a notification message will be sent to the application.
: Application : Terminal Location : Notification : Notification
Web Service Application Web Service
Create correlation id
Create notification with correlator
At some later time, an event occurs to
trigger the notification
Notification with correlator
At some later time, the notification may
be cancelled
Cancel notification with correlator
Figure 3
ETSI
12 Final draft ETSI ES 202 504-9 V1.1.1 (2008-02)
6.4 Terminal location notification with check immediate
In some applications, the terminal location notification will be used to watch for a specific location change. An example
is a 'call when present' service, where the terminal location is checked and determined to be outside the target area, and
a notification is set up to notify the application when the terminal enters the target area. Between the time of the original
location determination and the time the notification is set up, the terminal could move into the target area, thus the
notification on entry into the target area would not be sent.
Using the check immediate flag, after the notification is established, the terminal location will be determined, and if the
terminal is in the target area, then a notification will be sent immediately. The following sequence diagram shows this
scenario.
: Application : Terminal Location : Terminal Location : Notification : Notification
Web Service Notification Application Web Service
Get location
Location
Create correlator
Start geographical notification with check immediate
Set up notification
Check terminal location
Location notification
Apply count to notification
Status end
Void
Figure 4
This sequence shows:
• The Enterprise Application checks the location of a terminal, and receives its location (in this scenario
determining that the terminal is outside the target area).
• The Enterprise Application generates a correlator, and starts a notification with criteria defined to notify the
Enterprise Web Service when the terminal enters the target area and the check immediate flag set to true.
• Sets up the notification to monitor terminal location.
• Check the current location of the terminal, and determine if the terminal lies inside the target area.
ETSI
13 Final draft ETSI ES 202 504-9 V1.1.1 (2008-02)
• In this case, the terminal is in the target area, and a notification is delivered to the Enterprise Web Service.
• The count of notifications is incremented and compared to the notification count limit.
• In this case, a single notification was requested, and the end notification message is sent.
• The startGeographicalNotification operation completes.
This scenario includes the full set of interactions in one sequence, which also shows that the notifications can be
received concurrent with the creation of the notification.
6.5 Terminal location periodic notification
Pattern: Application Correlated Multiple Notification.
An application can be notified of a terminal device location on a periodic basis. At each interval, a notification message
will be sent to the application.
: Application : Terminal Location : Notification : Notification
Web Service Application Web Service
Create correlation id
Create notification with correlator
Set up timer
Repeat for intervals
Timer expiration Notification with correlator
At some later time, the notification may
be cancelled
Cancel notification with correlator
Figure 5
ETSI
14 Final draft ETSI ES 202 504-9 V1.1.1 (2008-02)
7 XML Schema data type definition
7.1 Latitude and Longitude values
Latitude and longitude values used in the present document follow the conventions of the ISO 6709 [3] specification, as
it applies to latitudes and longitudes specified using decimal degrees.
Latitude values are expressed as floating point numbers in the range -90,0000 to +90,0000, using decimal degrees (as
opposed to minutes and seconds). Positive values indicate locations north of and on the equator. Negative values
indicate locations south of the equator.
Longitude values are expressed as floating point numbers in the range -180,0000 to +180,0000, using decimal degrees
(as opposed to minutes and seconds). Positive values indicate locations east of and on the prime meridian (Greenwich).
th
Negative values indicate locations west of the prime meridian up to the 180 meridian.
7.2 Accuracy values
Two accuracy values are used in some of the operations. The
...
ETSI Standard
Open Service Access (OSA);
Parlay X Web Services;
Part 9: Terminal Location
(Parlay X 3)
�
2 ETSI ES 202 504-9 V1.1.1 (2008-05)
Reference
DES/TISPAN-01034-9-OSA
Keywords
API, OSA, service
ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE
Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16
Siret N° 348 623 562 00017 - 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:
http://www.etsi.org
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 ETSI printers of the PDF version kept on a specific network drive
within ETSI 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 ETSI documents is available at
http://portal.etsi.org/tb/status/status.asp
If you find errors in the present document, please send your comment to one of the following services:
http://portal.etsi.org/chaircor/ETSI_support.asp
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 2008.
© The Parlay Group 2008.
All rights reserved.
TM TM TM TM
DECT , PLUGTESTS , UMTS , TIPHON , the TIPHON logo and the ETSI logo are Trade Marks of ETSI registered
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.
ETSI
3 ETSI ES 202 504-9 V1.1.1 (2008-05)
Contents
Intellectual Property Rights.5
Foreword.5
1 Scope.7
2 References.7
2.1 Normative references.7
3 Definitions and abbreviations.8
3.1 Definitions.8
3.2 Abbreviations.8
4 Detailed service description .8
5 Namespaces.8
6 Sequence diagrams.9
6.1 Terminal location query .9
6.2 Terminal location group query .10
6.3 Terminal location notification .11
6.4 Terminal location notification with check immediate .12
6.5 Terminal location periodic notification .13
7 XML Schema data type definition .14
7.1 Latitude and Longitude values .14
7.2 Accuracy values.14
7.3 EnteringLeavingCriteria enumeration.14
7.4 LocationInfo structure.15
7.5 RetrievalStatus enumeration.15
7.6 LocationData structure.15
7.7 DelayTolerance enumeration.16
8 Web Service interface definition.16
8.1 Interface: TerminalLocation.16
8.1.1 Operation: getLocation.16
8.1.1.1 Input message: getLocationRequest.16
8.1.1.2 Output message: getLocationResponse.16
8.1.1.3 Referenced faults.17
8.1.2 Operation: getTerminalDistance.17
8.1.2.1 Input message: getTerminalDistanceRequest .17
8.1.2.2 Output message: getTerminalDistanceResponse.17
8.1.2.3 Referenced faults.17
8.1.3 Operation: getLocationForGroup.18
8.1.3.1 Input message: getLocationForGroupRequest .18
8.1.3.2 Output message: getLocationForGroupResponse.18
8.1.3.3 Referenced faults.18
8.2 Interface: TerminalLocationNotificationManager.19
8.2.1 Operation: startGeographicalNotification.19
8.2.1.1 Input message: startGeographicalNotificationRequest .19
8.2.1.2 Output message: startGeographicalNotificationResponse.20
8.2.1.3 Referenced faults.20
8.2.2 Operation: startPeriodicNotification.20
8.2.2.1 Input message: startPeriodicNotificationRequest.21
8.2.2.2 Output message: startPeriodicNotificationResponse .21
8.2.2.3 Referenced faults.21
8.2.3 Operation: endNotification.21
8.2.3.1 Input message: endNotificationRequest.22
8.2.3.2 Output message: endNotificationResponse.22
8.2.3.3 Referenced faults.22
ETSI
4 ETSI ES 202 504-9 V1.1.1 (2008-05)
8.3 Interface: TerminalLocationNotification.22
8.3.1 Operation: locationNotification.22
8.3.1.1 Input message: locationNotificationRequest.22
8.3.1.2 Output message: locationNotificationResponse.22
8.3.1.3 Referenced faults.22
8.3.2 Operation: locationError.23
8.3.2.1 Input message: locationErrorRequest.23
8.3.2.2 Output message: locationErrorResponse.23
8.3.2.3 Referenced faults.23
8.3.3 Operation: locationEnd.23
8.3.3.1 Input message: locationEndRequest.23
8.3.3.2 Output message: locationEndResponse.23
8.3.3.3 Referenced faults.23
9 Fault definitions.24
9.1 ServiceException.24
9.1.1 SVC0200: Accuracy out of limit .24
9.2 PolicyException.24
9.2.1 POL0230: Requested accuracy not supported .24
9.2.2 POL0231: Geographic notification not available .24
9.2.3 POL0232: Periodic notification not available.24
10 Service policies .25
Annex A (normative): WSDL for Terminal Location .26
Annex B (informative): Bibliography.27
History .28
ETSI
5 ETSI ES 202 504-9 V1.1.1 (2008-05)
Intellectual Property Rights
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: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in
respect of ETSI standards", 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.
Foreword
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 9 of a multi-part deliverable covering Open Service Access (OSA); Parlay X 3 Web
Services, as identified below:
Part 1: "Common";
Part 2: "Third Party Call";
Part 3: "Call Notification";
Part 4: "Short Messaging";
Part 5: "Multimedia Messaging";
Part 6: "Payment";
Part 7: "Account Management";
Part 8: "Terminal Status";
Part 9: "Terminal Location";
Part 10: "Call Handling";
Part 11: "Audio Call";
Part 12: "Multimedia Conference";
Part 13: "Address List Management";
Part 14: "Presence";
Part 15: "Message Broadcast";
Part 16: "Geocoding";
Part 17: "Application-driven Quality of Service (QoS)";
Part 18: "Device Capabilities and Configuration";
Part 19: "Multimedia Streaming Control";
Part 20: "Multimedia Multicast Session Management".
ETSI
6 ETSI ES 202 504-9 V1.1.1 (2008-05)
The present document has been defined jointly between ETSI, The Parlay Group (http://www.parlay.org) and the 3GPP.
The present document forms part of the Parlay X 3.0 set of specifications.
The present document is equivalent to 3GPP TS 29.199-09 V7.2.2 (Release 7).
ETSI
7 ETSI ES 202 504-9 V1.1.1 (2008-05)
1 Scope
The present document is part 9 of the Stage 3 Parlay X 3 Web Services specification for Open Service Access (OSA).
The OSA specifications define an architecture that enables application developers to make use of network functionality
through an open standardized interface, i.e. the OSA APIs.
The present document specifies the Terminal Location Web Service. The following are defined here:
• Name spaces.
• Sequence diagrams.
• Data definitions.
• Interface specification plus detailed method descriptions.
• Fault definitions.
• Service Policies.
• WSDL Description of the interfaces.
2 References
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific.
• For a specific reference, subsequent revisions do not apply.
• Non-specific reference may be made only to a complete document or a part thereof and only in the following
cases:
- if it is accepted that it will be possible to use all future changes of the referenced document for the
purposes of the referring document;
- for informative references.
Referenced documents which are not found to be publicly available in the expected location might be found at
http://docbox.etsi.org/Reference.
For online referenced documents, information sufficient to identify and locate the source shall be provided. Preferably,
the primary source of the referenced document should be cited, in order to ensure traceability. Furthermore, the
reference should, as far as possible, remain valid for the expected life of the document. The reference shall include the
method of access to the referenced document and the full network address, with the same punctuation and use of upper
case and lower case letters.
NOTE: While any hyperlinks included in this clause were valid at the time of publication ETSI cannot guarantee
their long term validity.
2.1 Normative references
The following referenced documents are indispensable for the application of the present document. For dated
references, only the edition cited applies. For non-specific references, the latest edition of the referenced document
(including any amendments) applies.
[1] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes".
NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.
ETSI
8 ETSI ES 202 504-9 V1.1.1 (2008-05)
[2] ETSI ES 202 504-1: "Open Service Access (OSA); Parlay X Web Services; Part 1: Common
(Parlay X 3)".
[3] ISO 6709: "Standard representation of latitude, longitude and altitude for geographic point
locations".
3 Definitions and abbreviations
3.1 Definitions
For the purposes of the present document, the terms and definitions given in ES 202 504-1 [2] apply.
3.2 Abbreviations
For the purposes of the present document, the abbreviations given in ES 202 504-1 [2] apply.
4 Detailed service description
Terminal Location provides access to the location of a terminal through:
• Request for the location of a terminal.
• Request for the location of a group of terminals.
• Notification of a change in the location of a terminal.
• Notification of terminal location on a periodic basis.
• Location is expressed through a latitude, longitude, altitude and accuracy.
When a request for a group of terminals is made, the response may contain a full or partial set of results. This allows the
service to provide results based on a number of criteria including number of terminals for which the request is made and
amount of time required to retrieve the information. This allows the requester to initiate additional requests for those
terminals for which information was not provided.
5 Namespaces
The TerminalLocation interface uses the namespace:
http://www.csapi.org/wsdl/parlayx/terminal_location/v3_1
The TerminalLocationNotificationManager interface uses the namespace:
http://www.csapi.org/wsdl/parlayx/terminal_location/notification_manager/v3_1
The TerminalLocationNotification interface uses the namespace:
http://www.csapi.org/wsdl/parlayx/terminal_location/notification/v3_0
The data types are defined in the namespace:
http://www.csapi.org/schema/parlayx/terminal_location/v3_0
The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in
XML Schema [1]. The use of the name 'xsd' is not semantically significant.
ETSI
9 ETSI ES 202 504-9 V1.1.1 (2008-05)
6 Sequence diagrams
6.1 Terminal location query
Pattern: Request / Response.
For an application to determine the location of a terminal device, it provides a terminal device address and desired
accuracy, and receives the location for the device requested.
: Application : Terminal Location
Web Service
Request terminal location
Retrieve location
Location data
Figure 1
ETSI
10 ETSI ES 202 504-9 V1.1.1 (2008-05)
6.2 Terminal location group query
Pattern: Request / Response.
When an application requires the locations of a set of terminal devices, it may provide an array of terminal device
addresses, including network managed group addresses, and receive the location data for the set of devices requested.
: Application : Terminal Location
Web Service
Request terminal location for group
Process groups
Retrieve locations
Location data
Figure 2
ETSI
11 ETSI ES 202 504-9 V1.1.1 (2008-05)
6.3 Terminal location notification
Pattern: Application Correlated Multiple Notification.
An application can be notified of a terminal device entering or leaving a geographical area. When a matching event
occurs; a notification message will be sent to the application.
: Application : Terminal Location : Notification : Notification
Web Service Application Web Service
Create correlation id
Create notification with correlator
At some later time, an event occurs to
trigger the notification
Notification with correlator
At some later time, the notification may
be cancelled
Cancel notification with correlator
Figure 3
ETSI
12 ETSI ES 202 504-9 V1.1.1 (2008-05)
6.4 Terminal location notification with check immediate
In some applications, the terminal location notification will be used to watch for a specific location change. An example
is a 'call when present' service, where the terminal location is checked and determined to be outside the target area, and
a notification is set up to notify the application when the terminal enters the target area. Between the time of the original
location determination and the time the notification is set up, the terminal could move into the target area, thus the
notification on entry into the target area would not be sent.
Using the check immediate flag, after the notification is established, the terminal location will be determined, and if the
terminal is in the target area, then a notification will be sent immediately. The following sequence diagram shows this
scenario.
: Application : Terminal Location : Terminal Location : Notification : Notification
Web Service Notification Application Web Service
Get location
Location
Create correlator
Start geographical notification with check immediate
Set up notification
Check terminal location
Location notification
Apply count to notification
Status end
Void
Figure 4
This sequence shows:
• The Enterprise Application checks the location of a terminal, and receives its location (in this scenario
determining that the terminal is outside the target area).
• The Enterprise Application generates a correlator, and starts a notification with criteria defined to notify the
Enterprise Web Service when the terminal enters the target area and the check immediate flag set to true.
• Sets up the notification to monitor terminal location.
• Check the current location of the terminal, and determine if the terminal lies inside the target area.
ETSI
13 ETSI ES 202 504-9 V1.1.1 (2008-05)
• In this case, the terminal is in the target area, and a notification is delivered to the Enterprise Web Service.
• The count of notifications is incremented and compared to the notification count limit.
• In this case, a single notification was requested, and the end notification message is sent.
• The startGeographicalNotification operation completes.
This scenario includes the full set of interactions in one sequence, which also shows that the notifications can be
received concurrent with the creation of the notification.
6.5 Terminal location periodic notification
Pattern: Application Correlated Multiple Notification.
An application can be notified of a terminal device location on a periodic basis. At each interval, a notification message
will be sent to the application.
: Application : Terminal Location : Notification : Notification
Web Service Application Web Service
Create correlation id
Create notification with correlator
Set up timer
Repeat for intervals
Timer expiration Notification with correlator
At some later time, the notification may
be cancelled
Cancel notification with correlator
Figure 5
ETSI
14 ETSI ES 202 504-9 V1.1.1 (2008-05)
7 XML Schema data type definition
7.1 Latitude and Longitude values
Latitude and longitude values used in the present document follow the conventions of the ISO 6709 [3] specification, as
it applies to latitudes and longitudes specified using decimal degrees.
Latitude values are expressed as floating point numbers in the range -90,0000 to +90,0000, using decimal degrees (as
opposed to minutes and seconds). Positive values indicate locations north of and on the equator. Negative values
indicate locations south of the equator.
Longitude values are expressed as floating point numbers in the range -180,0000 to +180,0000, using decimal degrees
(as opposed to minutes and seconds). Positive values indicate locations east of and on the prime meridian (Greenwich).
th
Negative values indicate locations west of the prime meridian up to the 180 meridian.
7.2 Accuracy values
Two accuracy values are used in some of the operations. These values express the desire of the application for
...
SLOVENSKI STANDARD
01-september-2008
Odprti dostop do storitve (OSA) - Spletne storitve Parlay X - 9. del: Lokacija
terminala (Parlay X 3)
Open Service Access (OSA) - Parlay X Web Services - Part 9: Terminal Location (Parlay
X 3)
Ta slovenski standard je istoveten z: ES 202 504-9 Version 1.1.1
ICS:
35.100.01 Medsebojno povezovanje Open systems
odprtih sistemov na splošno interconnection in general
2003-01.Slovenski inštitut za standardizacijo. Razmnoževanje celote ali delov tega standarda ni dovoljeno.
ETSI Standard
Open Service Access (OSA);
Parlay X Web Services;
Part 9: Terminal Location
(Parlay X 3)
�
2 ETSI ES 202 504-9 V1.1.1 (2008-05)
Reference
DES/TISPAN-01034-9-OSA
Keywords
API, OSA, service
ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE
Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16
Siret N° 348 623 562 00017 - 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:
http://www.etsi.org
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 ETSI printers of the PDF version kept on a specific network drive
within ETSI 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 ETSI documents is available at
http://portal.etsi.org/tb/status/status.asp
If you find errors in the present document, please send your comment to one of the following services:
http://portal.etsi.org/chaircor/ETSI_support.asp
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 2008.
© The Parlay Group 2008.
All rights reserved.
TM TM TM TM
DECT , PLUGTESTS , UMTS , TIPHON , the TIPHON logo and the ETSI logo are Trade Marks of ETSI registered
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.
ETSI
3 ETSI ES 202 504-9 V1.1.1 (2008-05)
Contents
Intellectual Property Rights.5
Foreword.5
1 Scope.7
2 References.7
2.1 Normative references.7
3 Definitions and abbreviations.8
3.1 Definitions.8
3.2 Abbreviations.8
4 Detailed service description .8
5 Namespaces.8
6 Sequence diagrams.9
6.1 Terminal location query .9
6.2 Terminal location group query .10
6.3 Terminal location notification .11
6.4 Terminal location notification with check immediate .12
6.5 Terminal location periodic notification .13
7 XML Schema data type definition .14
7.1 Latitude and Longitude values .14
7.2 Accuracy values.14
7.3 EnteringLeavingCriteria enumeration.14
7.4 LocationInfo structure.15
7.5 RetrievalStatus enumeration.15
7.6 LocationData structure.15
7.7 DelayTolerance enumeration.16
8 Web Service interface definition.16
8.1 Interface: TerminalLocation.16
8.1.1 Operation: getLocation.16
8.1.1.1 Input message: getLocationRequest.16
8.1.1.2 Output message: getLocationResponse.16
8.1.1.3 Referenced faults.17
8.1.2 Operation: getTerminalDistance.17
8.1.2.1 Input message: getTerminalDistanceRequest .17
8.1.2.2 Output message: getTerminalDistanceResponse.17
8.1.2.3 Referenced faults.17
8.1.3 Operation: getLocationForGroup.18
8.1.3.1 Input message: getLocationForGroupRequest .18
8.1.3.2 Output message: getLocationForGroupResponse.18
8.1.3.3 Referenced faults.18
8.2 Interface: TerminalLocationNotificationManager.19
8.2.1 Operation: startGeographicalNotification.19
8.2.1.1 Input message: startGeographicalNotificationRequest .19
8.2.1.2 Output message: startGeographicalNotificationResponse.20
8.2.1.3 Referenced faults.20
8.2.2 Operation: startPeriodicNotification.20
8.2.2.1 Input message: startPeriodicNotificationRequest.21
8.2.2.2 Output message: startPeriodicNotificationResponse .21
8.2.2.3 Referenced faults.21
8.2.3 Operation: endNotification.21
8.2.3.1 Input message: endNotificationRequest.22
8.2.3.2 Output message: endNotificationResponse.22
8.2.3.3 Referenced faults.22
ETSI
4 ETSI ES 202 504-9 V1.1.1 (2008-05)
8.3 Interface: TerminalLocationNotification.22
8.3.1 Operation: locationNotification.22
8.3.1.1 Input message: locationNotificationRequest.22
8.3.1.2 Output message: locationNotificationResponse.22
8.3.1.3 Referenced faults.22
8.3.2 Operation: locationError.23
8.3.2.1 Input message: locationErrorRequest.23
8.3.2.2 Output message: locationErrorResponse.23
8.3.2.3 Referenced faults.23
8.3.3 Operation: locationEnd.23
8.3.3.1 Input message: locationEndRequest.23
8.3.3.2 Output message: locationEndResponse.23
8.3.3.3 Referenced faults.23
9 Fault definitions.24
9.1 ServiceException.24
9.1.1 SVC0200: Accuracy out of limit .24
9.2 PolicyException.24
9.2.1 POL0230: Requested accuracy not supported .24
9.2.2 POL0231: Geographic notification not available .24
9.2.3 POL0232: Periodic notification not available.24
10 Service policies .25
Annex A (normative): WSDL for Terminal Location .26
Annex B (informative): Bibliography.27
History .28
ETSI
5 ETSI ES 202 504-9 V1.1.1 (2008-05)
Intellectual Property Rights
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: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in
respect of ETSI standards", 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.
Foreword
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 9 of a multi-part deliverable covering Open Service Access (OSA); Parlay X 3 Web
Services, as identified below:
Part 1: "Common";
Part 2: "Third Party Call";
Part 3: "Call Notification";
Part 4: "Short Messaging";
Part 5: "Multimedia Messaging";
Part 6: "Payment";
Part 7: "Account Management";
Part 8: "Terminal Status";
Part 9: "Terminal Location";
Part 10: "Call Handling";
Part 11: "Audio Call";
Part 12: "Multimedia Conference";
Part 13: "Address List Management";
Part 14: "Presence";
Part 15: "Message Broadcast";
Part 16: "Geocoding";
Part 17: "Application-driven Quality of Service (QoS)";
Part 18: "Device Capabilities and Configuration";
Part 19: "Multimedia Streaming Control";
Part 20: "Multimedia Multicast Session Management".
ETSI
6 ETSI ES 202 504-9 V1.1.1 (2008-05)
The present document has been defined jointly between ETSI, The Parlay Group (http://www.parlay.org) and the 3GPP.
The present document forms part of the Parlay X 3.0 set of specifications.
The present document is equivalent to 3GPP TS 29.199-09 V7.2.2 (Release 7).
ETSI
7 ETSI ES 202 504-9 V1.1.1 (2008-05)
1 Scope
The present document is part 9 of the Stage 3 Parlay X 3 Web Services specification for Open Service Access (OSA).
The OSA specifications define an architecture that enables application developers to make use of network functionality
through an open standardized interface, i.e. the OSA APIs.
The present document specifies the Terminal Location Web Service. The following are defined here:
• Name spaces.
• Sequence diagrams.
• Data definitions.
• Interface specification plus detailed method descriptions.
• Fault definitions.
• Service Policies.
• WSDL Description of the interfaces.
2 References
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific.
• For a specific reference, subsequent revisions do not apply.
• Non-specific reference may be made only to a complete document or a part thereof and only in the following
cases:
- if it is accepted that it will be possible to use all future changes of the referenced document for the
purposes of the referring document;
- for informative references.
Referenced documents which are not found to be publicly available in the expected location might be found at
http://docbox.etsi.org/Reference.
For online referenced documents, information sufficient to identify and locate the source shall be provided. Preferably,
the primary source of the referenced document should be cited, in order to ensure traceability. Furthermore, the
reference should, as far as possible, remain valid for the expected life of the document. The reference shall include the
method of access to the referenced document and the full network address, with the same punctuation and use of upper
case and lower case letters.
NOTE: While any hyperlinks included in this clause were valid at the time of publication ETSI cannot guarantee
their long term validity.
2.1 Normative references
The following referenced documents are indispensable for the application of the present document. For dated
references, only the edition cited applies. For non-specific references, the latest edition of the referenced document
(including any amendments) applies.
[1] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes".
NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.
ETSI
8 ETSI ES 202 504-9 V1.1.1 (2008-05)
[2] ETSI ES 202 504-1: "Open Service Access (OSA); Parlay X Web Services; Part 1: Common
(Parlay X 3)".
[3] ISO 6709: "Standard representation of latitude, longitude and altitude for geographic point
locations".
3 Definitions and abbreviations
3.1 Definitions
For the purposes of the present document, the terms and definitions given in ES 202 504-1 [2] apply.
3.2 Abbreviations
For the purposes of the present document, the abbreviations given in ES 202 504-1 [2] apply.
4 Detailed service description
Terminal Location provides access to the location of a terminal through:
• Request for the location of a terminal.
• Request for the location of a group of terminals.
• Notification of a change in the location of a terminal.
• Notification of terminal location on a periodic basis.
• Location is expressed through a latitude, longitude, altitude and accuracy.
When a request for a group of terminals is made, the response may contain a full or partial set of results. This allows the
service to provide results based on a number of criteria including number of terminals for which the request is made and
amount of time required to retrieve the information. This allows the requester to initiate additional requests for those
terminals for which information was not provided.
5 Namespaces
The TerminalLocation interface uses the namespace:
http://www.csapi.org/wsdl/parlayx/terminal_location/v3_1
The TerminalLocationNotificationManager interface uses the namespace:
http://www.csapi.org/wsdl/parlayx/terminal_location/notification_manager/v3_1
The TerminalLocationNotification interface uses the namespace:
http://www.csapi.org/wsdl/parlayx/terminal_location/notification/v3_0
The data types are defined in the namespace:
http://www.csapi.org/schema/parlayx/terminal_location/v3_0
The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in
XML Schema [1]. The use of the name 'xsd' is not semantically significant.
ETSI
9 ETSI ES 202 504-9 V1.1.1 (2008-05)
6 Sequence diagrams
6.1 Terminal location query
Pattern: Request / Response.
For an application to determine the location of a terminal device, it provides a terminal device address and desired
accuracy, and receives the location for the device requested.
: Application : Terminal Location
Web Service
Request terminal location
Retrieve location
Location data
Figure 1
ETSI
10 ETSI ES 202 504-9 V1.1.1 (2008-05)
6.2 Terminal location group query
Pattern: Request / Response.
When an application requires the locations of a set of terminal devices, it may provide an array of terminal device
addresses, including network managed group addresses, and receive the location data for the set of devices requested.
: Application : Terminal Location
Web Service
Request terminal location for group
Process groups
Retrieve locations
Location data
Figure 2
ETSI
11 ETSI ES 202 504-9 V1.1.1 (2008-05)
6.3 Terminal location notification
Pattern: Application Correlated Multiple Notification.
An application can be notified of a terminal device entering or leaving a geographical area. When a matching event
occurs; a notification message will be sent to the application.
: Application : Terminal Location : Notification : Notification
Web Service Application Web Service
Create correlation id
Create notification with correlator
At some later time, an event occurs to
trigger the notification
Notification with correlator
At some later time, the notification may
be cancelled
Cancel notification with correlator
Figure 3
ETSI
12 ETSI ES 202 504-9 V1.1.1 (2008-05)
6.4 Terminal location notification with check immediate
In some applications, the terminal location notification will be used to watch for a specific location change. An example
is a 'call when present' service, where the terminal location is checked and determined to be outside the target area, and
a notification is set up to notify the application when the terminal enters the target area. Between the time of the original
location determination and the time the notification is set up, the terminal could move into the target area, thus the
notification on entry into the target area would not be sent.
Using the check immediate flag, after the notification is established, the terminal location will be determined, and if the
terminal is in the target area, then a notification will be sent immediately. The following sequence diagram shows this
scenario.
: Application : Terminal Location : Terminal Location : Notification : Notification
Web Service Notification Application Web Service
Get location
Location
Create correlator
Start geographical notification with check immediate
Set up notification
Check terminal location
Location notification
Apply count to notification
Status end
Void
Figure 4
This sequence shows:
• The Enterprise Application checks the location of a terminal, and receives its location (in this scenario
determining that the terminal is outside the target area).
• The Enterprise Application generates a correlator, and starts a notification with criteria defined to notify the
Enterprise Web Service when the terminal enters the target area and the check immediate flag set to true.
• Sets up the notification to monitor terminal location.
• Check the current location of the terminal, and determine if the terminal lies inside the target area.
ETSI
13 ETSI ES 202 504-9 V1.1.1 (2008-05)
• In this case, the terminal is in the target area, and a notification is delivered to the Enterprise Web Service.
• The count of notifications is incremented and compared to the notification count limit.
• In this case, a single notification was requested, and the end notification message is sent.
• The startGeographicalNotification operation completes.
This scenario includes the full set of interactions in one sequence, which also shows that the notifications can be
received concurrent with the creation of the notification.
6.5 Terminal location periodic notification
Pattern: Application Correlated Multiple Notification.
An application can be notified of a terminal device location on a periodic basis. At each interval, a notification message
will be sent to the application.
: Application : Terminal Location : Notification : Notification
Web Service Application Web Service
Create correlation id
Create notification with correlator
Set up timer
Repeat for intervals
Timer expiration Notification with correlator
At some later time, the notification may
be cancelled
Cancel notification with correlator
Figure 5
ETSI
14 ETSI ES 202 504-9 V1.1.1 (2008-05)
7 XML Schema data type definition
7.1 Latitude and Longitude values
Latitude and longitude values used in the present document follow the conventions of the ISO 6709 [3] specification, as
it applies to latitudes and longitudes specified using decimal degrees.
Latitude values are expressed as floating point numbers in the range -90,0000 to +90,0000, using decimal degrees (as
opposed to minutes and seconds). Positive values indicate locations north of and on the equator. Negative values
indicate locations south of the equator.
Longitude values are expressed as floating point numbers in the range -180,0000 to +180,0000, us
...
Questions, Comments and Discussion
Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.
Loading comments...