29.198-143GPPOpen Service Access (OSA) Application Programming Interface (API)Part 14: Presence and Availability Management (PAM) Service Capability Feature (SCF)TS
Most of the methods in the PAM interfaces are independently used to query or update presence and availability related information with no transactions or state transitions involved. There are two use cases for which sequence diagrams are useful
- Acquiring and using authentication tokens
- Registering for PAM events and getting notifications on the occurrence of the event.
The sequence diagrams for these two cases are provided below. It is assumed that the authentication with the OSA framework has already occurred and the application has access to the PAM interfaces.
5.1 Use of authentication tokens
As an OSA Service, PAM uses the authentication features of the OSA Framework to provide access control to the PAM interfaces. In addition, PAM provides an optional mechanism for service/application level identification and authentication of the entity requesting the operation or alternatively on whose behalf the operation is being requested. To handle privacy requirements, the results of presence and availability data updates or queries are dependent on the entity requesting the operations.
In the simplest case, the entity authenticating to the OSA Framework to get access to the service interface is the entity requesting the operation. In general, however, a proxy or an application (such as a messaging server or a conferencing server) may authenticate with the OSA Framework once and then check for presence and availability on behalf of multiple client applications (such as instant messaging clients). The credential of these client applications if and when needed by the PAM service can then be provided via the credential parameter in each of the interface methods.
The mechanism to provide the asker data is via the optional parameter of type TpPAMCredential in each of the methods. Supplying the entire asker data in each of the methods is expensive for an implementation since it will need to parse and validate the data supplied in the asker data structure each time. An application may be accessing multiple methods for itself or for the benefit of end user(s) and will need to supply the relevant asker data in each case. To make the consideration of asker data more efficient, the application uses the getAuthToken() method in each of the managers in the SCFs once for each session per asker and gets a credential that can be reused as many times as necessary in the same session to represent the same asker.
The sequence diagram for an example usage is given below.
1: For any unique entity requesting the operation, the authenticated client of the OSA PAM service, requests for an authentication token using the getAuthToken() method in the PresenceAvailability Manager interface.
2: The token returned by the getAuthToken() method is used as the credential parameter of the getIdentityPresence() request.
3: The same token is used as the credential parameter of the getAvailability() request(). An authorization token can be used multiple times within the same session established with OSA framework.
5.2 Event registration and notification
An OSA client can register for certain events in the PAM service either for itself or on behalf of its own clients. The client will register one or more application interfaces with the event management service and then activate one or more events for each such registered interface.
The sequence diagram for an example is given below.
1: The client uses the registerAppInterface() method to register its notification interface. The getAuthToken() can be null since the client is doing this registration on its own behalf. The client gets a unique client ID back.
2: The client uses the getAuthToken() to get authentication credentials for its own application client on behalf of whom an event registration is required.
3: The client uses the registerForEvent() method to register for a change in availability event on behalf of its own client. The client gets a unique event ID back.
4: The presence information for an identity of interest in 3 above is changed by another client application acting on its behalf using the setIdentityPresence() method.
5: When the change in presence results in a change in the availability of the identity for the client that has registered for the availability change, a notification is sent out using the previously registered application interface.