API Description for Extended Web Services

User Status

The following sections provide detailed information about the User Status service capability:

• Web Service
• Listener interface

 

---

Web Service

The User Status Web Service provides an application with functions for retrieving the status of a telephony terminal.

getStatus

Get the status of one or more telephony terminals. Asynchronous request.

Table 11-1 getStatus(endpoint, addresses, serviceCode, requesterID)

Parameter Name	Type	Description
Input
endpoint	xsd:string	The URL to the Web Service that implements the listener interface. See Listener interface. An example is http://www.acompany.com/axis/services/UserStatusListener
addresses	mpl:ArrayOf_xsd_string	See ArrayOf_xsd_string. List of addresses, in URI format (tel:<address>), of the telephony terminals to retrieve the status for.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
getStatusReturn	xsd:int	ID of the request. This ID is supplied in setStatus to keep track of the different request-response pairs.
Exceptions
UserStatusException		See UserStatusException.
GeneralException		See GeneralException.

getStatusWait

Get the status of one or more telephony terminals. Synchronous request.

Table 11-2 getStatusWait(addresses, waitTimeoutSeconds, serviceCode, requesterID)

Parameter Name	Type	Description
Input
addresses	impl:ArrayOf_xsd_string	See ArrayOf_xsd_string. List of addresses, in URI format (tel:<address>), of the telephony terminals to retrieve the status for.
waitTimeoutSeconds	xsd:int	The time, in seconds, to wait for a response. If the response is not delivered within this time frame, and exception is thrown.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
getStatusWaitReturn	impl:ArrayOfStatusResult	See ArrayOfStatusResult. Array of the requested statuses.
Exceptions
UserStatusException		See UserStatusException.
GeneralException		See GeneralException.

startTriggeredStatusReporting

Starts to retrieve the status of one or more telephony terminals periodically. Asynchronous request.

Table 11-3 startTriggeredStatusReporting(endpoint, addresses, serviceCode, requesterID)

Parameter Name	Type	Description
Input
endpoint	xsd:string	The URL to the Web Service that implements the listener interface. See Listener interface. An example is http://www.acompany.com/axis/services/UserStatusListener
addresses	impl:ArrayOf_xsd_string	See ArrayOf_xsd_string. List of addresses, in URI format (tel:<address>), of the telephony terminals to retrieve the status for.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
startTriggeredStatusReportingReturn	xsd:int	ID of the request. This ID is supplied in setStatus to keep track of the different request-response pairs and to stop the reporting, see stopTriggeredStatusReporting.
Exceptions
UserStatusException		See UserStatusException.
GeneralException		See GeneralException.

stopTriggeredStatusReporting

Stops a periodic user status reporting session. Synchronous request.

Table 11-4 stopTriggeredStatusReporting(id)

Parameter Name	Type	Description
Parameters
id	xsd:int	Identifier for the session. See startTriggeredStatusReporting for information on how to start the session.
Returns
Void.
Exceptions
UserStatusException		See UserStatusException.
GeneralException		See GeneralException.

Exceptions

UserStatusException

Exceptions of this type are raised when there are error conditions related to the User Status Web Service. Other error conditions are reported using the exception GeneralException.

GeneralException

This exception is raised when the applications session has expired or there are communication problems with the underlying platform.

Complex data types

ArrayOf_xsd_string

Table 11-5

Name	Description
Array of xsd:string	Each element holds the MSISDN of a terminal.

ArrayOfStatusResult

Table 11-6

Name	Description
Array of StatusResult	A set of results of a user status request. See StatusResult.

StatusResult

The result of a user status request for an individual telephony terminal.

Table 11-7

Name	Type	Value
address	xsd:string	The telephony terminals address in URI format (tel:<address>).
reqStatus	impl:StatusCode	See StatusCode.
userStatus	impl:Status	See Status.

StatusCode

Indicates the outcome of the request. Enumeration (xsd:string) with one of the following values.

Table 11-8

Value	Description
OK	The request was successful.
SYSTEM_FAILURE	The request failed due to system failure.
UNAUTHORIZED_NETWORK	The request failed due to that the terminal belongs to network that does not accept status requests.
UNAUTHORIZED_APPLICATION	The request failed due to that the application was not authorized to perform a status request.
UNKNOWN_SUBSCRIBER	The request failed due to that the telephony terminal whose status was requested is unknown.
ABSENT_SUBSCRIBER	The request failed due to that the telephony terminal is not within the home network.
STATUS_METHOD_FAILURE	The request failed due to that the status request was performed using an illegal method.

Status

Table 11-9

Name	Type	Description
aStatusIndicator	impl:StatusIndicator	See StatusIndicator.
aTerminalType	tns7:TerminalType	TerminalType.

StatusIndicator

Indicates the status of the telephony terminal. Enumeration (xsd:string) with one of the following values:

Table 11-10

Value	Description
REACHABLE	The terminal is reachable.
NOT_REACHABLE	The terminal is not reachable.
BUSY	The terminal is busy.

TerminalType

Indicates the type of terminal whose status was requested. Enumeration (xsd:string) with one of the following values.

Table 11-11

Value	Description
TT_FIXED	Connected to the fixed network.
TT_IP	Connected to the IP-network.
TT_MOBILE	Mobile terminal.
TT_UNKNOWN	Unknown terminal type.

 

---

Listener interface

The User Status listener interface defines the methods that the underlying platform invokes on a Web Service that is implemented by an application. When an application performs asynchronous requests from the User Status Web Service, the responses are delivered according to this interface.

deactivate

Used by the underlying system to inform the application that a session is no longer valid. The application can not use the session no more.

Table 11-12 deactivate(id)

Parameter Name	Type	Description
Input
id	xsd:int	ID of the session to be deactivated. The ID was returned when getStatus was invoked.
Returns
Void.
Exceptions
-

setStatusError

Errors related to requests invoked by getStatus are reported using this method.

Table 11-13 setStatusError(id, errorCode, errorMsg)

Parameter Name	Type	Description
Input
id	xsd:int	ID of the request. The ID was returned when getStatus was invoked.
errorCode	xsd:int	Error code.
errorMsg	xsd:string	Error message.
Returns
Void.
Exceptions
-

setStatus

The result of a successful invocation of getStatus.

Table 11-14 setStatus(id, result)

Parameter Name	Type	Description
Input
id	xsd:int	ID of the request. The ID was returned when getStatus was invoked.
result	impl:ArrayOfStatusResult	See ArrayOfStatusResult. Status information of the terminals whose status were requested.
Returns
Void.
Exceptions
-

Complex data types

The data types are the same as the ones for the User Status Web Service, described in section Complex data types.