|
||||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
See:
Description
Interface Summary | |
---|---|
TerminalLocation | Request the location for a terminal. |
TerminalLocation_RI | |
TerminalLocationHome | |
TerminalLocationNotification | Notification interface to which notifications are delivered. |
TerminalLocationNotification_RI | |
TerminalLocationNotificationHome | |
TerminalLocationNotificationManager | Set up notifications for terminal location events using geographical based definitions. |
TerminalLocationNotificationManager_RI | |
TerminalLocationNotificationManagerHome | |
TerminalLocationNotificationManagerService | |
TerminalLocationNotificationService | |
TerminalLocationService |
Terminal Location.
The present document is part 9 of the Stage 3 Parlay X 2 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, for example, 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.
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 and/or edition number or version number) or nonspecific.
* For a specific reference, subsequent revisions do not apply.
* For a non-specific reference, the latest version applies.
Referenced documents which are not found to be publicly available in the expected location might be found at http://docbox.etsi.org/Reference.
[1] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes".
NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.
[2] ETSI ES 202 391-1: "Open Service Access (OSA); Parlay X 2 Web Services; Part 1: Common".
[3] ISO 6709: "Standard representation of latitude, longitude and altitude for geographic point locations".
For the purposes of the present document, the terms and definitions given in ES 202 391-1 [2] apply.
For the purposes of the present document, the abbreviations defined in ES 202 391-1 [2] apply.
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.
The Terminal Location interface uses the namespace: http://www.csapi.org/wsdl/parlayx/terminal_location/v2_12
The TerminalLocationNotificationManager interface uses the namespace: http://www.csapi.org/wsdl/parlayx/terminal_location/notification_manager/v2_23
The TerminalLocationNotification interface uses the namespace: http://www.csapi.org/wsdl/parlayx/terminal_location/notification/v2_12
The data types are defined in the namespace: http://www.csapi.org/schema/parlayx/terminal_location/v2_12
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.
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.
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.
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.
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.
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.
* 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.
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.
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). Negative values indicate locations west of the prime meridian up to the 180th meridian.
Two accuracy values are used in some of the operations. These values express the desire of the application for the location information to be provided by the Web Service. The choice of values may influence the price that the Service Provider charges.
* The 'requested accuracy' expresses the range in which the application wishes to receive location information. This may influence the choice of location technology to use (for instance, cell sector location may be suitable for requests specifying 1 000 meters, but GPS technology may be required for requests below 100 meters).
* The 'acceptable accuracy' expresses the range that the application considers useful, if the location cannot be determined within this range, then the application would prefer not to receive the information. For instance, a taxi tracking service to determine the closest taxi to a person may not be useful if the accuracy cannot be provided within 1 000 meters to provide prompt service. This will also reduce customer satisfaction issues, since results that are not useful can be handled appropriately for billing (for example, Service Provider may choose not to bill for these).
The ‘maximum_age’ expresses the maximum age of location information that the application considers useful. This can be used by the service provider to supply cached location information rather than always to do a direct network location request.
The ‘response time’ expresses the expected response time from an application point of view. If the network is unable to respond within the desired time frame, the application would prefer not to have the information as it may no longer be useful.
The ‘tolerance’ expresses the priority of response time versus accuracy. If the application is delay tolerant the network is expected to return a location with the requested accuracy even if this means not complying with the requested response time. The application can also indicate that it is more important that the location information is returned within the requested time even if this implies that the requested accuracy can not be fulfilled. An indication of ‘no delay’ implies that the application expects the service provider to return any current location estimate immediately.
In triggered notifications, a tracking accuracy is defined. This accuracy refers not to the accuracy for the area being checked against, but rather for the accuracy of the technology used to track the terminal. For instance, a fine grained tracking accuracy would be suitable for tracking the terminal entering a specific location, like a person arriving at a destination building. A coarse grained tracking accuracy would be appropriate for determining when a person has arrived at a city after a plane trip or a truck is in the vicinity of a warehouse.
Indicator for whether the notification is related to entering an area or leaving an area.
Entering
Terminal is entering an area
Leaving
Terminal is leaving an area
Location information represented as a coordinate.
address
xsd:anyURI
Address of the terminal device to which the location information applies
latitude
xsd:float
Location latitude
longitude
xsd:float
Location longitude
altitude
xsd:float
Location altitude
accuracy
xsd:int
Accuracy of location provided in meters
timestamp
xsd:dateTime
Date and time that location was collected
Enumeration of the location items that are related to an individual retrieval in a set.
Retrieved
Location retrieved, with result in currentLocation element
NotRetrieved
Location not retrieved, currentLocation is not provided (does not indicate an error, no attempt may have been made)
Error
Error retrieving location
Data structure containing device address, retrieval status and location information. As this can be related to a query of a group of terminal devices, the reportStatus element is used to indicate whether the information for the device was retrieved or not, or if an error occurred.
address
xsd:anyURI
Address of the terminal device to which the location information applies
reportStatus
RetrievalStatus
Status of retrieval for this terminal device address
currentLocation
LocationInfo
NoYes
Location of terminal. It is only provided if reportStatus=Retrieved.
errorInformation
common:ServiceError
If reportStatus=Errorreport status is error, this is the reason for the error. Error due to privacy verification will be expressed as POL0002 in the ServiceError
Enumeration of the delay tolerance items that forms part of the location request.
NoDelay
The server should immediately return any location estimate that it currently has. If no estimate is available, the server shall return the failure indication and may optionally initiate procedures to obtain a location estimate (for example, to be available for a later request).
LowDelay
Fulfillment of the response time requirement takes precedence over fulfillment of the accuracy requirement. The server shall return any current location estimate with minimum delay. The server shall attempt to fulfill any accuracy requirement, but in doing so shall not add any additional delay (for example, a quick response with lower accuracy is more desirable than waiting for a more accurate response).
DelayTolerant
Fulfillment of the accuracy requirement takes precedence over fulfillment of the response time requirement. If necessary, the server should delay providing a response until the accuracy requirement of the requesting application is met. The server shall obtain a current location with regard to fulfilling the accuracy requirement.
messageId
SVC0200
text
Accuracy of location is not within acceptable limit
variables
None
messageId
POL0230
text
Requested accuracy is not supported
variables
None
messageId
POL0231
text
Geographic notification is not available
variables
None
messageId
POL0232
text
Periodic notification is not available
variables
None
Service policies for this service.
MinimumAccuracy
xsd:int
Minimum value for requested accuracy
MinimumAcceptableAccuracy
xsd:int
Minimum value for acceptable accuracy
MinimumTrackingAccuracy
xsd:int
Minimum value for tracking accuracy
GeographicalNotificationAvailable
xsd:boolean
Can notifications be set on a geography
PeriodicNotificationAvailable
xsd:boolean
Can a periodic notification be set up
AltitudeAlwaysAvailable
xsd:boolean
Is altitude available for all location responses
AltitudeSometimesAvailable
xsd:boolean
Is altitude available for some or all location responses (if AltitudeAlwaysAvailable is true, this is also true)
MaximumNotificationAddresses
xsd:int
Maximum number of addresses for which a notification can be set up
MaximumNotificationFrequency
common:TimeMetric
Maximum rate of notification delivery (also can be considered minimum time between notifications)
MaximumNotificationDuration
common:TimeMetric
Maximum amount of time for which a notification can be set up
MaximumCount
xsd:int
Maximum number of notifications that may be requested
UnlimitedCountAllowed
xsd:boolean
Allowed to specify unlimited notification count (for example, either by not specifying the optional count message part in startGeographicalNotificationRequest or by specifying a value of zero in notification count requested)
GroupSupport
xsd:boolean
Groups URIs may be used
NestedGroupSupport
xsd:boolean
Are nested groups supported in group definitions
|
||||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |