8 Web service interface definition
29.199-083GPPOpen Service Access (OSA)Parlay X web servicesPart 8: Terminal statusTS
8.1 Interface: TerminalStatus
Request the status for a terminal or set of terminals.
8.1.1 Operation: GetStatus
This operation is intended to retrieve the status for a single terminal. The URI provided is for a single terminal, not a group URI. If a group URI is provided, a PolicyException will be returned to the application.
8.1.1.1 Input message: GetStatusRequest
|
Part name |
Part type |
Optional |
Description |
|
Address |
xsd:anyURI |
No |
Terminal to request status for |
8.1.1.2 Output message: GetStatusResponse
|
Part name |
Part type |
Optional |
Description |
|
Result |
Status |
No |
Status for the terminal for which status was requested |
8.1.1.3 Referenced faults
ServiceException from 3GPP TS 29.199-1 [6]:
- SVC0001: Service error.
- SVC0002: Invalid input value.
- SVC0004: No valid address(es) – if the address does not exist.
PolicyException from 3GPP TS 29.199-1 [6]:
- POL0001: Policy error.
- POL0002: Privacy error.
- POL0006: Groups not allowed.
8.1.2 Operation: GetStatusForGroup
The getStatusForGroup operation initiates a retrieval activity, where one or more terminals, or groups of terminals, may have their status determined.
The Web Service may return a result set that does not include complete information, allowing the Web Service implementation to choose to deliver a partial set of results to accommodate other conditions, such as avoiding timeouts. In this case, the addresses for which no attempt was made to provide data will be marked NotRetrieved in the result for each address this applies to.
8.1.2.1 Input message: GetStatusForGroupRequest
|
Part name |
Part type |
Optional |
Description |
|
Addresses |
xsd:anyURI [1..unbounded] |
No |
List of URIs to get status for, including group URIs |
8.1.2.2 Output message: GetStatusForGroupResponse
|
Part name |
Part type |
Optional |
Description |
|
Result |
StatusData [1..unbounded] |
No |
Set of results for the request |
8.1.2.3 Referenced faults
ServiceException from 3GPP TS 29.199-1 [6]:
- SVC0001: Service error.
- SVC0002: Invalid input value.
- SVC0004: No valid addresses.
- SVC0006: Invalid group.
PolicyException from 3GPP TS 29.199-1 [6]:
- POL0001: Policy error.
- POL0003: Too many addresses.
- POL0006: Groups not allowed.
- POL0007: Nested groups not allowed.
- POL0013: Addresses duplication.
8.2 Interface: TerminalStatusNotificationManager
Set up notifications for terminal status changes.
8.2.1 Operation: StartNotification
Notifications of status changes are made available to applications. The number and duration of notifications may be requested as part of the setup of the notification or may be governed by service policies, or a combination of the two.
If CheckImmediate is set to true, then the notification will be set up, and then the current value of the terminal status will be checked. If the terminal status meets the criteria provided, a notification will be sent to the application. This notification will count against the count requested. This addresses the case where the status of the device changes during the time the notification is being set up, which may be appropriate in some applications.
The correlator provided in the reference must be unique for this Web Service at the time the notification is initiated, otherwise a ServiceException (SVC0005) will be returned to the application.
If the frequency requested is more often than allowed by the service policy, then the value in the service policy will be used. If the duration requested exceeds the time allowed in the service policy, then the value in the service policy will be used. If the notification period (duration) ends before all of the notifications (count) have been delivered, then the notification terminates. In all cases, when the notifications have run their course (by duration or count), an end of notifications message will be provided to the application.
Service policies may govern what count values can be requested, including maximum number of notifications allowed and whether unlimited notifications can be requested (i.e. either by not specifying the optional Count message part or by specifying it with a value of zero). If the count value requested is not in policy, a PolicyException (POL0004 or POL0005 as appropriate) will be returned.
8.2.1.1 Input message: StartNotificationRequest
|
Part name |
Part type |
Optional |
Description |
|
Reference |
common:SimpleReference |
No |
Notification endpoint definition |
|
Addresses |
xsd:anyURI [1..unbounded] |
No |
Addresses of terminals to monitor |
|
Criteria |
Status [1..unbounded] |
No |
List of status values to generate notifications for (these apply to all addresses specified) |
|
CheckImmediate |
xsd:boolean |
No |
Check status immediately after establishing notification |
|
Frequency |
common:TimeMetric |
No |
Maximum frequency of notifications (can also be considered minimum time between notifications) |
|
Duration |
common:TimeMetric |
Yes |
Length of time notifications occur for, do not specify to use default notification time defined by service policy |
|
Count |
xsd:integer |
Yes |
Maximum number of notifications. For no maximum, either do not specify this part or specify a value of zero. |
8.2.1.2 Output message: StartNotificationResponse
|
Part name |
Part type |
Optional |
Description |
|
None |
8.2.1.3 Referenced faults
ServiceException from 3GPP TS 29.199-1 [6]:
- SVC0001: Service error.
- SVC0002: Invalid input value.
- SVC0004: No valid addresses.
- SVC0005: Duplicate correlator.
- SVC0006: Invalid group.
PolicyException from 3GPP TS 29.199-1 [6]:
- POL0001: Policy error.
- POL0003: Too many addresses.
- POL0004: Unlimited notifications not supported.
- POL0005: Too many notifications requested.
- POL0006: Groups not allowed.
- POL0007: Nested groups not allowed.
- POL0009: Invalid frequency requested.
- POL0013: Addresses duplication.
- POL0200: Busy criteria not supported.
8.2.2 Operation: EndNotification
The application may end a notification using this operation. Until this operation returns, notifications may continue to be received by the application.
An end of notification (statusEnd) message will not be delivered to the application for a notification ended using this operation.
8.2.2.1 Input message: EndNotificationRequest
|
Part name |
Part type |
Optional |
Description |
|
Correlator |
xsd:string |
No |
Correlator of request to end |
8.2.2.2 Output message: EndNotificationResponse
|
Part name |
Part type |
Optional |
Description |
|
None |
8.2.2.3 Referenced faults
ServiceException from 3GPP TS 29.199-1 [6]:
- SVC0001: Service error.
- SVC0002: Invalid input value.
PolicyException from 3GPP TS 29.199-1 [6]:
- POL0001: Policy error.
8.3 Interface: TerminalNotification
Notification interface to which notifications are delivered.
8.3.1 Operation: StatusNotification
When the status of monitored devices change, a notification is delivered to the application with the new status information for each of the devices. If a group identifier was used, the terminal device URI is provided, not the group URI.
8.3.1.1 Input message: StatusNotificationRequest
|
Part name |
Part type |
Optional |
Description |
|
Correlator |
xsd:string |
No |
Correlator provided in request to set up this notification |
|
TerminalStatus |
StatusInformation [1..unbounded] |
No |
List of Statusinformation elements describing address and new terminal status. |
8.3.1.2 Output message: StatusNotificationResponse
|
Part name |
Part type |
Optional |
Description |
|
None |
8.3.1.3 Referenced faults
None.
8.3.2 Operation: StatusError
The status changed error message is sent to the application to indicate that the notification is being cancelled by the Web Service.
8.3.2.1 Input message: StatusErrorRequest
|
Part name |
Part type |
Optional |
Description |
|
Correlator |
xsd:string |
No |
Correlator provided in request to set up this notification. |
|
Address |
xsd:anyURI |
Yes |
Address of terminal if the error applies to an individual terminal, or not specified if it applies to the whole notification. |
|
Reason |
common:ServiceError |
No |
Reason notification is being discontinued. |
8.3.2.2 Output message: StatusErrorResponse
|
Part name |
Part type |
Optional |
Description |
|
None |
8.3.2.3 Referenced faults
None.
8.3.3 Operation: StatusEnd
The notifications have completed for this correlator. This message will be delivered when the duration or count for notifications have been completed. This message will not be delivered in the case of an error ending the notifications or deliberate ending of the notifications (using endNotification operation).
8.3.3.1 Input message: StatusEndRequest
|
Part name |
Part type |
Optional |
Description |
|
Correlator |
xsd:string |
No |
Correlator provided in request to set up this notification. |
8.3.3.2 Output message: StatusEndResponse
|
Part name |
Part type |
Optional |
Description |
|
None |
8.3.3.3 Referenced faults
None.